evennia.typeclasses.models

This is the abstract django models for many of the database objects in Evennia. A django abstract (obs, not the same as a Python metaclass!) is a model which is not actually created in the database, but which only exists for other models to inherit from, to avoid code duplication. Any model can import and inherit from these classes.

Attributes are database objects stored on other objects. The implementing class needs to supply a ForeignKey field attr_object pointing to the kind of object being mapped. Attributes storing iterables actually store special types of iterables named PackedList/PackedDict respectively. These make sure to save changes to them to database - this is criticial in order to allow for obj.db.mylist[2] = data. Also, all dbobjects are saved as dbrefs but are also aggressively cached.

TypedObjects are objects ‘decorated’ with a typeclass - that is, the typeclass (which is a normal Python class implementing some special tricks with its get/set attribute methods, allows for the creation of all sorts of different objects all with the same database object underneath. Usually attributes are used to permanently store things not hard-coded as field on the database object. The admin should usually not have to deal directly with the database object layer.

This module also contains the Managers for the respective models; inherit from these to create custom managers.

---

class evennia.typeclasses.models.TypedObject(*args, **kwargs)

Bases: evennia.utils.idmapper.models.SharedMemoryModel

Abstract Django model.

This is the basis for a typed object. It also contains all the mechanics for managing connected attributes.

The TypedObject has the following properties:

key - main name name - alias for key typeclass_path - the path to the decorating typeclass typeclass - auto-linked typeclass date_created - time stamp of object creation permissions - perm strings dbref - #id of object db - persistent attribute storage ndb - non-persistent attribute storage

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_typeclass_path

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.

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_attributes

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.

db_tags

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.

objects

set_class_from_typeclass(typeclass_path=None)

__init__(*args, **kwargs)

The __init__ method of typeclasses is the core operational code of the typeclass system, where it dynamically re-applies a class based on the db_typeclass_path database field rather than use the one in the model.

Parameters

• *args – Passed through to parent.

• **kwargs – Passed through to parent.

Notes

The loading mechanism will attempt the following steps:

1. Attempt to load typeclass given on command line

2. Attempt to load typeclass stored in db_typeclass_path

3. Attempt to load __settingsclasspath__, which is by the default classes defined to be the respective user-set base typeclass settings, like BASE_OBJECT_TYPECLASS.

4. Attempt to load __defaultclasspath__, which is the base classes in the library, like DefaultObject etc.

5. If everything else fails, use the database model.

Normal operation is to load successfully at either step 1 or 2 depending on how the class was called. Tracebacks will be logged for every step the loader must take beyond 2.

attributes

locks

tags

aliases

permissions

nattributes

class Meta

Bases: object

Django setup info.

abstract = False

verbose_name = 'Evennia Database Object'

ordering = ['-db_date_created', 'id', 'db_typeclass_path', 'db_key']

property name

property key

property dbid

Caches and returns the unique id of the object. Use this instead of self.id, which is not cached.

property dbref

Returns the object’s dbref on the form #NN.

at_idmapper_flush()

This is called when the idmapper cache is flushed and allows customized actions when this happens.

Returns

do_flush (bool) –

If True, flush this object as normal. If

False, don’t flush and expect this object to handle the flushing on its own.

Notes

The default implementation relies on being able to clear Django’s Foreignkey cache on objects not affected by the flush (notably objects with an NAttribute stored). We rely on this cache being stored on the format “_<fieldname>_cache”. If Django were to change this name internally, we need to update here (unlikely, but marking just in case).

is_typeclass(typeclass, exact=False)

Returns true if this object has this type OR has a typeclass which is an subclass of the given typeclass. This operates on the actually loaded typeclass (this is important since a failing typeclass may instead have its default currently loaded) typeclass - can be a class object or the python path to such an object to match against.

Parameters

• typeclass (str or class) – A class or the full python path to the class to check.

• exact (bool, optional) – Returns true only if the object’s type is exactly this typeclass, ignoring parents.

Returns

is_typeclass (bool) –

If this typeclass matches the given

typeclass.

swap_typeclass(new_typeclass, clean_attributes=False, run_start_hooks='all', no_default=True, clean_cmdsets=False)

This performs an in-situ swap of the typeclass. This means that in-game, this object will suddenly be something else. Account will not be affected. To ‘move’ an account to a different object entirely (while retaining this object’s type), use self.account.swap_object().

Note that this might be an error prone operation if the old/new typeclass was heavily customized - your code might expect one and not the other, so be careful to bug test your code if using this feature! Often its easiest to create a new object and just swap the account over to that one instead.

Parameters

• new_typeclass (str or classobj) – Type to switch to.

• clean_attributes (bool or list, optional) – Will delete all attributes stored on this object (but not any of the database fields such as name or location). You can’t get attributes back, but this is often the safest bet to make sure nothing in the new typeclass clashes with the old one. If you supply a list, only those named attributes will be cleared.

• run_start_hooks (str or None, optional) – This is either None, to not run any hooks, “all” to run all hooks defined by at_first_start, or a string giving the name of the hook to run (for example ‘at_object_creation’). This will always be called without arguments.

• no_default (bool, optiona) – If set, the swapper will not allow for swapping to a default typeclass in case the given one fails for some reason. Instead the old one will be preserved.

• clean_cmdsets (bool, optional) – Delete all cmdsets on the object.

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

Determines if another object has permission to access this one.

Parameters

• accessing_obj (str) – Object trying to access this one.

• access_type (str, optional) – Type of access sought.

• default (bool, optional) – What to return if no lock of access_type was found

• no_superuser_bypass (bool, optional) – Turn off the superuser lock bypass (be careful with this one).

Keyword Arguments

kwargs (any) – Ignored, but is there to make the api consistent with the object-typeclass method access, which use it to feed to its hook methods.

check_permstring(permstring)

This explicitly checks if we hold particular permission without involving any locks.

Parameters

permstring (str) – The permission string to check against.

Returns

result (bool) – If the permstring is passed or not.

delete()

Cleaning up handlers on the typeclass level

property db

Attribute handler wrapper. Allows for the syntax

obj.db.attrname = value
  and
value = obj.db.attrname
  and
del obj.db.attrname
  and
all_attr = obj.db.all()

(unless there is an attribute named ‘all’, in which case that will be returned instead).

property ndb

A non-attr_obj store (NonDataBase). Everything stored to this is guaranteed to be cleared when a server is shutdown. Syntax is same as for the .db property, e.g.

obj.ndb.attrname = value
  and
value = obj.ndb.attrname
  and
del obj.ndb.attrname
  and
all_attr = obj.ndb.all()

What makes this preferable over just assigning properties directly on the object is that Evennia can track caching for these properties and for example avoid wiping objects with set .ndb data on cache flushes.

get_display_name(looker, **kwargs)

Displays the name of the object in a viewer-aware manner.

Parameters

looker (TypedObject, optional) – The object or account that is looking at/getting inforamtion for this object. If not given, some ‘safe’ minimum level should be returned.

Returns

name (str) –

A string containing the name of the object,

including the DBREF if this user is privileged to control said object.

Notes

This function could be extended to change how object names appear to users in character, but be wary. This function does not change an object’s keys or aliases when searching, and is expected to produce something useful for builders.

get_extra_info(looker, **kwargs)

Used when an object is in a list of ambiguous objects as an additional information tag.

For instance, if you had potions which could have varying levels of liquid left in them, you might want to display how many drinks are left in each when selecting which to drop, but not in your normal inventory listing.

Parameters

looker (TypedObject) – The object or account that is looking at/getting information for this object.

Returns

info (str) –

A string with disambiguating information,

conventionally with a leading space.

at_rename(oldname, newname)

This Hook is called by @name on a successful rename.

Parameters

• oldname (str) – The instance’s original name.

• newname (str) – The new name for the instance.

web_get_admin_url()

Returns the URI path for the Django Admin page for this object.

ex. Account#1 = ‘/admin/accounts/accountdb/1/change/’

Returns

path (str) – URI path to Django Admin page for object.

classmethod web_get_create_url()

Returns the URI path for a View that allows users to create new instances of this object.

Returns

path (str) – URI path to object creation page, if defined.

Examples

Chargen = '/characters/create/'

For this to work, the developer must have defined a named view somewhere in urls.py that follows the format ‘modelname-action’, so in this case a named view of ‘character-create’ would be referenced by this method.

url(r'characters/create/', ChargenView.as_view(), name='character-create')

If no View has been created and defined in urls.py, returns an HTML anchor.

Notes

This method is naive and simply returns a path. Securing access to the actual view and limiting who can create new objects is the developer’s responsibility.

web_get_detail_url()

Returns the URI path for a View that allows users to view details for this object.

Returns

path (str) – URI path to object detail page, if defined.

Examples

Oscar (Character) = '/characters/oscar/1/'

For this to work, the developer must have defined a named view somewhere in urls.py that follows the format ‘modelname-action’, so in this case a named view of ‘character-detail’ would be referenced by this method.

CharDetailView.as_view(), name='character-detail')

If no View has been created and defined in urls.py, returns an HTML anchor.

Notes

This method is naive and simply returns a path. Securing access to the actual view and limiting who can view this object is the developer’s responsibility.

web_get_puppet_url()

Returns the URI path for a View that allows users to puppet a specific object.

Returns

path (str) – URI path to object puppet page, if defined.

Examples

Oscar (Character) = '/characters/oscar/1/puppet/'

For this to work, the developer must have defined a named view somewhere in urls.py that follows the format ‘modelname-action’, so in this case a named view of ‘character-puppet’ would be referenced by this method.

url(r'characters/(?P<slug>[\w\d\-]+)/(?P<pk>[0-9]+)/puppet/$',
    CharPuppetView.as_view(), name='character-puppet')

If no View has been created and defined in urls.py, returns an HTML anchor.

Notes

This method is naive and simply returns a path. Securing access to the actual view and limiting who can view this object is the developer’s responsibility.

web_get_update_url()

Returns the URI path for a View that allows users to update this object.

Returns

path (str) – URI path to object update page, if defined.

Examples

Oscar (Character) = '/characters/oscar/1/change/'

For this to work, the developer must have defined a named view somewhere in urls.py that follows the format ‘modelname-action’, so in this case a named view of ‘character-update’ would be referenced by this method.

url(r'characters/(?P<slug>[\w\d\-]+)/(?P<pk>[0-9]+)/change/$',
    CharUpdateView.as_view(), name='character-update')

If no View has been created and defined in urls.py, returns an HTML anchor.

Notes

This method is naive and simply returns a path. Securing access to the actual view and limiting who can modify objects is the developer’s responsibility.

web_get_delete_url()

Returns the URI path for a View that allows users to delete this object.

Returns

path (str) – URI path to object deletion page, if defined.

Examples

Oscar (Character) = '/characters/oscar/1/delete/'

For this to work, the developer must have defined a named view somewhere in urls.py that follows the format ‘modelname-action’, so in this case a named view of ‘character-detail’ would be referenced by this method.

url(r'characters/(?P<slug>[\w\d\-]+)/(?P<pk>[0-9]+)/delete/$',
    CharDeleteView.as_view(), name='character-delete')

If no View has been created and defined in urls.py, returns an HTML anchor.

Notes

This method is naive and simply returns a path. Securing access to the actual view and limiting who can delete this object is the developer’s responsibility.

property date_created

A wrapper for getting database field db_date_created.

get_absolute_url()

Returns the URI path for a View that allows users to view details for this object.

Returns

path (str) – URI path to object detail page, if defined.

Examples

Oscar (Character) = '/characters/oscar/1/'

For this to work, the developer must have defined a named view somewhere in urls.py that follows the format ‘modelname-action’, so in this case a named view of ‘character-detail’ would be referenced by this method.

CharDetailView.as_view(), name='character-detail')

If no View has been created and defined in urls.py, returns an HTML anchor.

Notes

This method is naive and simply returns a path. Securing access to the actual view and limiting who can view this object is the developer’s responsibility.

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)

property lock_storage

A wrapper for getting database field db_lock_storage.

path = 'evennia.typeclasses.models.TypedObject'

property typeclass_path

A wrapper for getting database field db_typeclass_path.

typename = 'SharedMemoryModelBase'