evennia.typeclasses.attributes

Attributes are arbitrary data stored on objects. Attributes supports both pure-string values and pickled arbitrary data.

Attributes are also used to implement Nicks. This module also contains the Attribute- and NickHandlers as well as the NAttributeHandler, which is a non-db version of Attributes.

class evennia.typeclasses.attributes.Attribute(*args, **kwargs)

Bases: evennia.utils.idmapper.models.SharedMemoryModel

Attributes are things that are specific to different types of objects. For example, a drink container needs to store its fill level, whereas an exit needs to store its open/closed/locked/unlocked state. These are done via attributes, rather than making different classes for each object type and storing them directly. The added benefit is that we can add/remove attributes on the fly as we like.

The Attribute class defines the following properties:

• key (str): Primary identifier.

• lock_storage (str): Perm strings.

• model (str): A string defining the model this is connected to. This

  is a natural_key, like “objects.objectdb”

• date_created (datetime): When the attribute was created.

• value (any): The data stored in the attribute, in pickled form

  using wrappers to be able to store/retrieve models.

• strvalue (str): String-only data. This data is not pickled and

  is thus faster to search for in the database.

• category (str): Optional character string for grouping the

  Attribute.

db_key

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

db_value

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

db_strvalue

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

db_category

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

db_lock_storage

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

db_model

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

db_attrtype

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

db_date_created

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

locks

property key

property strvalue

property category

property model

property attrtype

property date_created

property lock_storage

property value

Getter. Allows for value = self.value. We cannot cache here since it makes certain cases (such as storing a dbobj which is then deleted elsewhere) out-of-sync. The overhead of unpickling seems hard to avoid.

access(accessing_obj, access_type='attrread', default=False, **kwargs)

Determines if another object has permission to access.

Parameters

• accessing_obj (object) – Entity trying to access this one.

• access_type (str, optional) – Type of access sought, see the lock documentation.

• default (bool, optional) – What result to return if no lock of access_type was found. The default, False, means a lockdown policy, only allowing explicit access.

• kwargs (any, optional) – Not used; here to make the API consistent with other access calls.

Returns

result (bool) – If the lock was passed or not.

exception DoesNotExist

Bases: django.core.exceptions.ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: django.core.exceptions.MultipleObjectsReturned

accountdb_set

Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.

In the example:

class Pizza(Model):
    toppings = ManyToManyField(Topping, related_name='pizzas')

**Pizza.toppings** and **Topping.pizzas** are **ManyToManyDescriptor** instances.

Most of the implementation is delegated to a dynamically defined manager class built by **create_forward_many_to_many_manager()** defined below.

channeldb_set

Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.

In the example:

class Pizza(Model):
    toppings = ManyToManyField(Topping, related_name='pizzas')

**Pizza.toppings** and **Topping.pizzas** are **ManyToManyDescriptor** instances.

Most of the implementation is delegated to a dynamically defined manager class built by **create_forward_many_to_many_manager()** defined below.

get_next_by_db_date_created(*, field=<django.db.models.fields.DateTimeField: db_date_created>, is_next=True, **kwargs)

get_previous_by_db_date_created(*, field=<django.db.models.fields.DateTimeField: db_date_created>, is_next=False, **kwargs)

id

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

objectdb_set

Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.

In the example:

class Pizza(Model):
    toppings = ManyToManyField(Topping, related_name='pizzas')

**Pizza.toppings** and **Topping.pizzas** are **ManyToManyDescriptor** instances.

Most of the implementation is delegated to a dynamically defined manager class built by **create_forward_many_to_many_manager()** defined below.

path = 'evennia.typeclasses.attributes.Attribute'

scriptdb_set

Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.

In the example:

class Pizza(Model):
    toppings = ManyToManyField(Topping, related_name='pizzas')

**Pizza.toppings** and **Topping.pizzas** are **ManyToManyDescriptor** instances.

Most of the implementation is delegated to a dynamically defined manager class built by **create_forward_many_to_many_manager()** defined below.

typename = 'SharedMemoryModelBase'

class evennia.typeclasses.attributes.AttributeHandler(obj)

Bases: object

Handler for adding Attributes to the object.

__init__(obj)

Initialize handler.

reset_cache()

Reset cache from the outside.

has(key=None, category=None)

Checks if the given Attribute (or list of Attributes) exists on the object.

Parameters

• key (str or iterable) – The Attribute key or keys to check for. If None, search by category.

• category (str or None) – Limit the check to Attributes with this category (note, that None is the default category).

Returns

has_attribute (bool or list) –

If the Attribute exists on

this object or not. If key was given as an iterable then the return is a list of booleans.

get(key=None, default=None, category=None, return_obj=False, strattr=False, raise_exception=False, accessing_obj=None, default_access=True, return_list=False)

Get the Attribute.

Parameters

• key (str or list, optional) – the attribute identifier or multiple attributes to get. if a list of keys, the method will return a list.

• category (str, optional) – the category within which to retrieve attribute(s).

• default (any, optional) – The value to return if an Attribute was not defined. If set, it will be returned in a one-item list.

• return_obj (bool, optional) – If set, the return is not the value of the Attribute but the Attribute object itself.

• strattr (bool, optional) – Return the strvalue field of the Attribute rather than the usual value, this is a string-only value for quick database searches.

• raise_exception (bool, optional) – When an Attribute is not found, the return from this is usually default. If this is set, an exception is raised instead.

• accessing_obj (object, optional) – If set, an attrread permission lock will be checked before returning each looked-after Attribute.

• default_access (bool, optional) – If no attrread lock is set on object, this determines if the lock should then be passed or not.

• return_list (bool, optional) –

Returns

result (any or list) –

One or more matches for keys and/or

categories. Each match will be the value of the found Attribute(s) unless return_obj is True, at which point it will be the attribute object itself or None. If return_list is True, this will always be a list, regardless of the number of elements.

Raises

AttributeError – If raise_exception is set and no matching Attribute was found matching key.

add(key, value, category=None, lockstring='', strattr=False, accessing_obj=None, default_access=True)

Add attribute to object, with optional lockstring.

Parameters

• key (str) – An Attribute name to add.

• value (any or str) – The value of the Attribute. If strattr keyword is set, this must be a string.

• category (str, optional) – The category for the Attribute. The default None is the normal category used.

• lockstring (str, optional) – A lock string limiting access to the attribute.

• strattr (bool, optional) – Make this a string-only Attribute. This is only ever useful for optimization purposes.

• accessing_obj (object, optional) – An entity to check for the attrcreate access-type. If not passing, this method will be exited.

• default_access (bool, optional) – What access to grant if accessing_obj is given but no lock of the type attrcreate is defined on the Attribute in question.

batch_add(*args, **kwargs)

Batch-version of add(). This is more efficient than repeat-calling add when having many Attributes to add.

Parameters

*args (tuple) –

Each argument should be a tuples (can be of varying length) representing the Attribute to add to this object. Supported tuples are

• (key, value)

• (key, value, category)

• (key, value, category, lockstring)

• (key, value, category, lockstring, default_access)

Keyword Arguments

strattr (bool) – If True, value must be a string. This will save the value without pickling which is less flexible but faster to search (not often used except internally).

Raises

RuntimeError – If trying to pass a non-iterable as argument.

Notes

The indata tuple order matters, so if you want a lockstring but no category, set the category to None. This method does not have the ability to check editing permissions like normal .add does, and is mainly used internally. It does not use the normal self.add but apply the Attributes directly to the database.

remove(key=None, raise_exception=False, category=None, accessing_obj=None, default_access=True)

Remove attribute or a list of attributes from object.

Parameters

• key (str or list, optional) – An Attribute key to remove or a list of keys. If multiple keys, they must all be of the same category. If None and category is not given, remove all Attributes.

• raise_exception (bool, optional) – If set, not finding the Attribute to delete will raise an exception instead of just quietly failing.

• category (str, optional) – The category within which to remove the Attribute.

• accessing_obj (object, optional) – An object to check against the attredit lock. If not given, the check will be skipped.

• default_access (bool, optional) – The fallback access to grant if accessing_obj is given but there is no attredit lock set on the Attribute in question.

Raises

AttributeError – If raise_exception is set and no matching Attribute was found matching key.

Notes

If neither key nor category is given, this acts as clear().

clear(category=None, accessing_obj=None, default_access=True)

Remove all Attributes on this object.

Parameters

• category (str, optional) – If given, clear only Attributes of this category.

• accessing_obj (object, optional) – If given, check the attredit lock on each Attribute before continuing.

• default_access (bool, optional) – Use this permission as fallback if access_obj is given but there is no lock of type attredit on the Attribute in question.

all(accessing_obj=None, default_access=True)

Return all Attribute objects on this object, regardless of category.

Parameters

• accessing_obj (object, optional) – Check the attrread lock on each attribute before returning them. If not given, this check is skipped.

• default_access (bool, optional) – Use this permission as a fallback if accessing_obj is given but one or more Attributes has no lock of type attrread defined on them.

Returns

Attributes (list) –

All the Attribute objects (note: Not

their values!) in the handler.

exception evennia.typeclasses.attributes.NickTemplateInvalid

Bases: ValueError

evennia.typeclasses.attributes.initialize_nick_templates(in_template, out_template)

Initialize the nick templates for matching and remapping a string.

Parameters

• in_template (str) – The template to be used for nick recognition.

• out_template (str) – The template to be used to replace the string matched by the in_template.

Returns

(regex, str) –

Regex to match against strings and a template

Template with markers {arg1}, {arg2}, etc for replacement using the standard .format method.

Raises

attributes.NickTemplateInvalid – If the in/out template does not have a matching number of $args.

evennia.typeclasses.attributes.parse_nick_template(string, template_regex, outtemplate)

Parse a text using a template and map it to another template

Parameters

• string (str) – The input string to processj

• template_regex (regex) – A template regex created with initialize_nick_template.

• outtemplate (str) – The template to which to map the matches produced by the template_regex. This should have $1, $2, etc to match the regex.

class evennia.typeclasses.attributes.NickHandler(*args, **kwargs)

Bases: evennia.typeclasses.attributes.AttributeHandler

Handles the addition and removal of Nicks. Nicks are special versions of Attributes with an _attrtype hardcoded to nick. They also always use the strvalue fields for their data.

__init__(*args, **kwargs)

Initialize handler.

has(key, category='inputline')

Parameters

• key (str or iterable) – The Nick key or keys to check for.

• category (str) – Limit the check to Nicks with this category (note, that None is the default category).

Returns

has_nick (bool or list) –

If the Nick exists on this object

or not. If key was given as an iterable then the return is a list of booleans.

get(key=None, category='inputline', return_tuple=False, **kwargs)

Get the replacement value matching the given key and category

Parameters

• key (str or list, optional) – the attribute identifier or multiple attributes to get. if a list of keys, the method will return a list.

• category (str, optional) – the category within which to retrieve the nick. The “inputline” means replacing data sent by the user.

• return_tuple (bool, optional) – return the full nick tuple rather than just the replacement. For non-template nicks this is just a string.

• kwargs (any, optional) – These are passed on to AttributeHandler.get.

add(key, replacement, category='inputline', **kwargs)

Add a new nick.

Parameters

• key (str) – A key (or template) for the nick to match for.

• replacement (str) – The string (or template) to replace key with (the “nickname”).

• category (str, optional) – the category within which to retrieve the nick. The “inputline” means replacing data sent by the user.

• kwargs (any, optional) – These are passed on to AttributeHandler.get.

remove(key, category='inputline', **kwargs)

Remove Nick with matching category.

Parameters

• key (str) – A key for the nick to match for.

• category (str, optional) – the category within which to removethe nick. The “inputline” means replacing data sent by the user.

• kwargs (any, optional) – These are passed on to AttributeHandler.get.

nickreplace(raw_string, categories='inputline', 'channel', include_account=True)

Apply nick replacement of entries in raw_string with nick replacement.

Parameters

• raw_string (str) – The string in which to perform nick replacement.

• categories (tuple, optional) – Replacement categories in which to perform the replacement, such as “inputline”, “channel” etc.

• include_account (bool, optional) – Also include replacement with nicks stored on the Account level.

• kwargs (any, optional) – Not used.

Returns

string (str) –

A string with matching keys replaced with

their nick equivalents.

class evennia.typeclasses.attributes.NAttributeHandler(obj)

Bases: object

This stand-alone handler manages non-database saving. It is similar to AttributeHandler and is used by the .ndb handler in the same way as .db does for the AttributeHandler.

__init__(obj)

Initialized on the object

has(key)

Check if object has this attribute or not.

Parameters

key (str) – The Nattribute key to check.

Returns

has_nattribute (bool) – If Nattribute is set or not.

get(key)

Get the named key value.

Parameters

key (str) – The Nattribute key to get.

Returns

the value of the Nattribute.

add(key, value)

Add new key and value.

Parameters

• key (str) – The name of Nattribute to add.

• value (any) – The value to store.

remove(key)

Remove Nattribute from storage.

Parameters

key (str) – The name of the Nattribute to remove.

clear()

Remove all NAttributes from handler.

all(return_tuples=False)

List the contents of the handler.

Parameters

return_tuples (bool, optional) – Defines if the Nattributes are returns as a list of keys or as a list of (key, value).

Returns

nattributes (list) –

A list of keys [key, key, …] or a

list of tuples [(key, value), …] depending on the setting of return_tuples.