# evennia.prototypes.prototypes

Handling storage of prototypes, both database-based ones (DBPrototypes) and those defined in modules (Read-only prototypes). Also contains utility functions, formatters and manager functions.

exception `evennia.prototypes.prototypes.``PermissionError`

  Bases: `RuntimeError`

exception `evennia.prototypes.prototypes.``ValidationError`

  Bases: `RuntimeError`

  Raised on prototype validation errors

`evennia.prototypes.prototypes.``homogenize_prototype`(prototype, custom_keys=None)

  Homogenize the more free-form prototype supported pre Evennia 0.7 into the stricter form.

  Parameters

    - prototype (dict) – Prototype.

    - custom_keys (list, optional) – Custom keys which should not be interpreted as attrs, beyond the default reserved keys.

  Returns

    homogenized (dict) –

    Prototype where all non-identified keys grouped as attributes and other

      homogenizations like adding missing prototype_keys and setting a default typeclass.

`evennia.prototypes.prototypes.``load_module_prototypes`(*mod_or_prototypes, override=True)

  Load module prototypes. Also prototype-dicts passed directly to this function are considered ‘module’ prototypes (they are impossible to change) but will have a module of None.

  Parameters

    - *mod_or_prototypes (module or dict) – Each arg should be a separate module or prototype-dict to load. If none are given, settings.PROTOTYPE_MODULES will be used.

    - override (bool, optional) – If prototypes should override existing ones already loaded. Disabling this can allow for injecting prototypes into the system dynamically while still allowing same prototype-keys to be overridden from settings (even though settings is usually loaded before dynamic loading).

  Note

  This is called (without arguments) by evennia.__init__ as Evennia initializes. It’s important to do this late so as to not interfere with evennia initialization. But it can also be used later to add more prototypes to the library on the fly. This is requried before a module-based prototype can be accessed by prototype-key.

class `evennia.prototypes.prototypes.``DbPrototype`(*args, **kwargs)

  Bases: `evennia.scripts.scripts.DefaultScript`

  This stores a single prototype, in an Attribute prototype.

  `at_script_creation`()

    Only called once, when script is first created.

  property `prototype`

    Make sure to decouple from db!

  exception `DoesNotExist`

    Bases: `evennia.scripts.scripts.DefaultScript.DoesNotExist`

  exception `MultipleObjectsReturned`

    Bases: `evennia.scripts.scripts.DefaultScript.MultipleObjectsReturned`

  `path` = 'evennia.prototypes.prototypes.DbPrototype'
  `typename` = 'DbPrototype'

`evennia.prototypes.prototypes.``save_prototype`(prototype)

  Create/Store a prototype persistently.

  Parameters

    prototype (dict) – The prototype to save. A prototype_key key is required.

  Returns

    prototype (dict or None) – The prototype stored using the given kwargs, None if deleting.

  Raises

    prototypes.ValidationError – If prototype does not validate.

  Note

  No edit/spawn locks will be checked here - if this function is called the caller is expected to have valid permissions.

`evennia.prototypes.prototypes.``create_prototype`(prototype)

  Create/Store a prototype persistently.

  Parameters

    prototype (dict) – The prototype to save. A prototype_key key is required.

  Returns

    prototype (dict or None) – The prototype stored using the given kwargs, None if deleting.

  Raises

    prototypes.ValidationError – If prototype does not validate.

  Note

  No edit/spawn locks will be checked here - if this function is called the caller is expected to have valid permissions.

`evennia.prototypes.prototypes.``delete_prototype`(prototype_key, caller=None)

  Delete a stored prototype

  Parameters

    - key (str) – The persistent prototype to delete.

    - caller (Account or Object, optionsl) – Caller aiming to delete a prototype. Note that no locks will be checked if**caller** is not passed.

  Returns

    success (bool) – If deletion worked or not.

  Raises

    PermissionError – If ‘edit’ lock was not passed or deletion failed for some other reason.

`evennia.prototypes.prototypes.``search_prototype`(key=None, tags=None, require_single=False, return_iterators=False, no_db=False)

  Find prototypes based on key and/or tags, or all prototypes.

  Keyword Arguments

    - key (str) – An exact or partial key to query for.

    - tags (str or list) – Tag key or keys to query for. These will always be applied with the ‘db_protototype’ tag category.

    - require_single (bool) – If set, raise KeyError if the result was not found or if there are multiple matches.

    - return_iterators (bool) – Optimized return for large numbers of db-prototypes. If set, separate returns of module based prototypes and paginate the db-prototype return.

    - no_db (bool) – Optimization. If set, skip querying for database-generated prototypes and only include module-based prototypes. This can lead to a dramatic speedup since module-prototypes are static and require no db-lookup.

  Returns

    matches (list) –

    Default return, all found prototype dicts. Empty list if

      no match was found. Note that if neither key nor tags were given, all available prototypes will be returned.

    list, queryset: If return_iterators are found, this is a list of

      module-based prototypes followed by a paginated queryset of db-prototypes.

  Raises

    KeyError – If require_single is True and there are 0 or >1 matches.

  Note

  The available prototypes is a combination of those supplied in PROTOTYPE_MODULES and those stored in the database. Note that if tags are given and the prototype has no tags defined, it will not be found as a match.

`evennia.prototypes.prototypes.``search_objects_with_prototype`(prototype_key)

  Retrieve all object instances created by a given prototype.

  Parameters

    prototype_key (str) – The exact (and unique) prototype identifier to query for.

  Returns

    matches (Queryset) – All matching objects spawned from this prototype.

class `evennia.prototypes.prototypes.``PrototypeEvMore`(caller, *args, session=None, **kwargs)

  Bases: `evennia.utils.evmore.EvMore`

  Listing 1000+ prototypes can be very slow. So we customize EvMore to display an EvTable per paginated page rather than to try creating an EvTable for the entire dataset and then paginate it.

  `__init__`(caller, *args, session=None, **kwargs)

    Store some extra properties on the EvMore class

  `init_pages`(inp)

    This will be initialized with a tuple (mod_prototype_list, paginated_db_query) and we must handle these separately since they cannot be paginated in the same way. We will build the prototypes so that the db-prototypes come first (they are likely the most volatile), followed by the mod-prototypes.

  `prototype_paginator`(pageno)

    The listing is separated in db/mod prototypes, so we need to figure out which one to pick based on the page number. Also, pageno starts from 0.

  `page_formatter`(page)

    Input is a queryset page from django.Paginator

`evennia.prototypes.prototypes.``list_prototypes`(caller, key=None, tags=None, show_non_use=False, show_non_edit=True, session=None)

  Collate a list of found prototypes based on search criteria and access.

  Parameters

    - caller (Account or Object) – The object requesting the list.

    - key (str, optional) – Exact or partial prototype key to query for.

    - tags (str or list, optional) – Tag key or keys to query for.

    - show_non_use (bool, optional) – Show also prototypes the caller may not use.

    - show_non_edit (bool, optional) – Show also prototypes the caller may not edit.

    - session (Session, optional) – If given, this is used for display formatting.

  Returns

    PrototypeEvMore – An EvMore subclass optimized for prototype listings. None: If no matches were found. In this case the caller has already been notified.

`evennia.prototypes.prototypes.``validate_prototype`(prototype, protkey=None, protparents=None, is_prototype_base=True, strict=True, _flags=None)

  Run validation on a prototype, checking for inifinite regress.

  Parameters

    - prototype (dict) – Prototype to validate.

    - protkey (str, optional) – The name of the prototype definition. If not given, the prototype dict needs to have the prototype_key field set.

    - protpartents (dict, optional) – The available prototype parent library. If note given this will be determined from settings/database.

    - is_prototype_base (bool, optional) – We are trying to create a new object based on this object. This means we can’t allow ‘mixin’-style prototypes without typeclass/parent etc.

    - strict (bool, optional) – If unset, don’t require needed keys, only check against infinite recursion etc.

    - _flags (dict, optional) – Internal work dict that should not be set externally.

  Raises

    - RuntimeError – If prototype has invalid structure.

    - RuntimeWarning – If prototype has issues that would make it unsuitable to build an object with (it may still be useful as a mix-in prototype).

`evennia.prototypes.prototypes.``protfunc_parser`(value, available_functions=None, testing=False, stacktrace=False, caller=None, **kwargs)

  Parse a prototype value string for a protfunc and process it.

  Available protfuncs are specified as callables in one of the modules of settings.PROTFUNC_MODULES, or specified on the command line.

  Parameters

    - value (any) – The value to test for a parseable protfunc. Only strings will be parsed for protfuncs, all other types are returned as-is.

    - available_functions (dict, optional) – Mapping of name:protfunction to use for this parsing. If not set, use default sources.

    - stacktrace (bool, optional) – If set, print the stack parsing process of the protfunc-parser.

  Keyword Arguments

    - session (Session) – Passed to protfunc. Session of the entity spawning the prototype.

    - protototype (dict) – Passed to protfunc. The dict this protfunc is a part of.

    - current_key (str) – Passed to protfunc. The key in the prototype that will hold this value.

    - caller (Object or Account) – This is necessary for certain protfuncs that perform object searches and have to check permissions.

    - any (any) – Passed on to the protfunc.

  Returns

    any – A structure to replace the string on the prototype leve. Note that FunctionParser functions $funcname(*args, **kwargs) can return any data type to insert into the prototype.

`evennia.prototypes.prototypes.``format_available_protfuncs`()

  Get all protfuncs in a pretty-formatted form.

  Parameters

    clr (str, optional) – What coloration tag to use.

`evennia.prototypes.prototypes.``prototype_to_str`(prototype)

  Format a prototype to a nice string representation.

  Parameters

    prototype (dict) – The prototype.

`evennia.prototypes.prototypes.``check_permission`(prototype_key, action, default=True)

  Helper function to check access to actions on given prototype.

  Parameters

    - prototype_key (str) – The prototype to affect.

    - action (str) – One of “spawn” or “edit”.

    - default (str) – If action is unknown or prototype has no locks

  Returns

    passes (bool) – If permission for action is granted or not.

`evennia.prototypes.prototypes.``init_spawn_value`(value, validator=None, caller=None, prototype=None)

  Analyze the prototype value and produce a value useful at the point of spawning.

  Parameters

    value (any) –

    This can be: callable - will be called as callable() (callable, (args,)) - will be called as callable(*args) other - will be assigned depending on the variable type validator (callable, optional): If given, this will be called with the value to

    > check and guarantee the outcome is of a given type.

    caller (Object or Account): This is necessary for certain protfuncs that perform object

      searches and have to check permissions.

    prototype (dict): Prototype this is to be used for. Necessary for certain protfuncs.

  Returns

    any (any) – The (potentially pre-processed value to use for this prototype key)

`evennia.prototypes.prototypes.``value_to_obj_or_any`(value)

  Convert value(s) to Object if possible, otherwise keep original value

`evennia.prototypes.prototypes.``value_to_obj`(value, force=True)

  Always convert value(s) to Object, or None