evennia.comms.models

Models for the in-game communication system.

The comm system could take the form of channels, but can also be adopted for storing tells or in-game mail.

The comsystem’s main component is the Message (Msg), which carries the actual information between two parties. Msgs are stored in the database and usually not deleted. A Msg always have one sender (a user), but can have any number targets, both users and channels.

For non-persistent (and slightly faster) use one can also use the TempMsg, which mimics the Msg API but without actually saving to the database.

Channels are central objects that act as targets for Msgs. Accounts can connect to channels by use of a ChannelConnect object (this object is necessary to easily be able to delete connections on the fly).

class evennia.comms.models.Msg(*args, **kwargs)

Bases: SharedMemoryModel

A single message. This model describes all ooc messages sent in-game, both to channels and between accounts.

The Msg class defines the following database fields (all accessed via specific handler methods):

• db_sender_accounts: Account senders

• db_sender_objects: Object senders

• db_sender_scripts: Script senders

• db_sender_external: External sender (defined as string name)

• db_receivers_accounts: Receiving accounts

• db_receivers_objects: Receiving objects

• db_receivers_scripts: Receiveing scripts

• db_receiver_external: External sender (defined as string name)

• db_header: Header text

• db_message: The actual message text

• db_date_created: time message was created / sent

• db_hide_from_sender: bool if message should be hidden from sender

• db_hide_from_receivers: list of receiver objects to hide message from

• db_lock_storage: Internal storage of lock strings.

db_sender_accounts

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_sender_objects

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_sender_scripts

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_sender_external

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

db_receivers_accounts

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_receivers_objects

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_receivers_scripts

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_receiver_external

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

db_header

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

db_message

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_hide_from_accounts

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_hide_from_objects

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 = <evennia.comms.managers.MsgManager object>

locks

tags

property date_created

Return the field in localized time based on settings.TIME_ZONE.

property senders

Getter. Allows for value = self.senders

remove_sender(senders)

Remove a single sender or a list of senders.

Parameters:

senders (Account, Object, str or list) – Senders to remove. If a string, removes the external sender.

property receivers

Getter. Allows for value = self.receivers. Returns four lists of receivers: accounts, objects, scripts and

external_receivers.

remove_receiver(receivers)

Remove a single receiver, a list of receivers, or a single extral receiver.

Parameters:

receivers (Account, Object, Script, list or str) – Receiver to remove. A string removes the external receiver.

property hide_from

Getter. Allows for value = self.hide_from. Returns two lists of accounts and objects.

access(accessing_obj, access_type='read', default=False)

Checks lock access.

Parameters:

• accessing_obj (Object or Account) – The object trying to gain access.

• access_type (str, optional) – The type of lock access to check.

• default (bool) – Fallback to use if access_type lock is not defined.

Returns:

result (bool) – If access was granted or not.

exception DoesNotExist

Bases: ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

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 header

A wrapper for getting database field db_header.

id

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

property lock_storage

A wrapper for getting database field db_lock_storage.

property message

A wrapper for getting database field db_message.

path = 'evennia.comms.models.Msg'

property receiver_external

A wrapper for getting database field db_receiver_external.

property sender_external

A wrapper for getting database field db_sender_external.

typename = 'SharedMemoryModelBase'

class evennia.comms.models.TempMsg(senders=None, receivers=None, message='', header='', type='', lockstring='', hide_from=None)

Bases: object

This is a non-persistent object for sending temporary messages that will not be stored. It mimics the “real” Msg object, but doesn’t require sender to be given.

__init__(senders=None, receivers=None, message='', header='', type='', lockstring='', hide_from=None)

Creates the temp message.

Parameters:

• senders (any or list, optional) – Senders of the message.

• receivers (Account, Object, Script or list, optional) – Receivers of this message.

• message (str, optional) – Message to send.

• header (str, optional) – Header of message.

• type (str, optional) – Message class, if any.

• lockstring (str, optional) – Lock for the message.

• hide_from (Account, Object, or list, optional) – Entities to hide this message from.

locks

remove_sender(sender)

Remove a sender or a list of senders.

Parameters:

sender (Object, Account, str or list) – Senders to remove.

remove_receiver(receiver)

Remove a receiver or a list of receivers

Parameters:

receiver (Object, Account, Script, str or list) – Receivers to remove.

access(accessing_obj, access_type='read', default=False)

Checks lock access.

Parameters:

• accessing_obj (Object or Account) – The object trying to gain access.

• access_type (str, optional) – The type of lock access to check.

• default (bool) – Fallback to use if access_type lock is not defined.

Returns:

result (bool) – If access was granted or not.

class evennia.comms.models.ChannelDB(*args, **kwargs)

Bases: TypedObject

This is the basis of a comm channel, only implementing the very basics of distributing messages.

The Channel class defines the following database fields beyond the ones inherited from TypedObject:

• db_account_subscriptions: The Account subscriptions.

• db_object_subscriptions: The Object subscriptions.

db_account_subscriptions

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_object_subscriptions

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 = <evennia.comms.managers.ChannelDBManager object>

exception DoesNotExist

Bases: ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

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_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_key

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_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.

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.

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.

path = 'evennia.comms.models.ChannelDB'

typename = 'SharedMemoryModelBase'

subscriptions

class evennia.comms.models.SubscriptionHandler(obj)

Bases: object

This handler manages subscriptions to the channel and hides away which type of entity is subscribing (Account or Object)

__init__(obj)

Initialize the handler

Attr:

obj (ChannelDB): The channel the handler sits on.

has(entity)

Check if the given entity subscribe to this channel

Parameters:

entity (str, Account or Object) – The entity to return. If a string, it assumed to be the key or the #dbref of the entity.

Returns:

subscriber (Account, Object or None) –

The given

subscriber.

add(entity)

Subscribe an entity to this channel.

Parameters:

entity (Account, Object or list) – The entity or list of entities to subscribe to this channel.

Note

No access-checking is done here, this must have

been done before calling this method. Also no hooks will be called.

remove(entity)

Remove a subscriber from the channel.

Parameters:

entity (Account, Object or list) – The entity or entities to un-subscribe from the channel.

all()

Get all subscriptions to this channel.

Returns:

subscribers (list) –

The subscribers. This

may be a mix of Accounts and Objects!

get()

Get all subscriptions to this channel.

Returns:

subscribers (list) –

The subscribers. This

may be a mix of Accounts and Objects!

online()

Get all online accounts from our cache :returns: subscribers (list) –

Subscribers who are online or

are puppeted by an online account.

clear()

Remove all subscribers from channel.

class evennia.comms.models.LockHandler(obj)

Bases: object

This handler should be attached to all objects implementing permission checks, under the property ‘lockhandler’.

__init__(obj)

Loads and pre-caches all relevant locks and their functions.

Parameters:

• obj (object) – The object on which the lockhandler is

• defined.

add(lockstring, validate_only=False)

Add a new lockstring to handler.

Parameters:

• lockstring (str or list) – A string on the form “<access_type>:<functions>”. Multiple access types should be separated by semicolon (;). Alternatively, a list with lockstrings.

• validate_only (bool, optional) – If True, validate the lockstring but don’t actually store it.

Returns:

success (bool) –

The outcome of the addition, False on

error. If validate_only is True, this will be a tuple (bool, error), for pass/fail and a string error.

all()

Return all lockstrings

Returns:

lockstrings (list) – All separate lockstrings

append(access_type, lockstring, op='or')

Append a lock definition to access_type if it doesn’t already exist.

Parameters:

• access_type (str) – Access type.

• lockstring (str) – A valid lockstring, without the operator to link it to an eventual existing lockstring.

• op (str) – An operator ‘and’, ‘or’, ‘and not’, ‘or not’ used for appending the lockstring to an existing access-type.

Note

The most common use of this method is for use in commands where the user can specify their own lockstrings. This method allows the system to auto-add things like Admin-override access.

cache_lock_bypass(obj)

We cache superuser bypass checks here for efficiency. This needs to be re-run when an account is assigned to a character. We need to grant access to superusers. We need to check both directly on the object (accounts), through obj.account and using the get_account() method (this sits on serversessions, in some rare cases where a check is done before the login process has yet been fully finalized)

Parameters:

obj (object) – This is checked for the is_superuser property.

check(accessing_obj, access_type, default=False, no_superuser_bypass=False)

Checks a lock of the correct type by passing execution off to the lock function(s).

Parameters:

• accessing_obj (object) – The object seeking access.

• access_type (str) – The type of access wanted.

• default (bool, optional) – If no suitable lock type is found, default to this result.

• no_superuser_bypass (bool) – Don’t use this unless you really, really need to, it makes supersusers susceptible to the lock check.

Notes

A lock is executed in the follwoing way:

Parsing the lockstring, we (during cache) extract the valid lock functions and store their function objects in the right order along with their args/kwargs. These are now executed in sequence, creating a list of True/False values. This is put into the evalstring, which is a string of AND/OR/NOT entries separated by placeholders where each function result should go. We just put those results in and evaluate the string to get a final, combined True/False value for the lockstring.

The important bit with this solution is that the full lockstring is never blindly evaluated, and thus there (should be) no way to sneak in malign code in it. Only “safe” lock functions (as defined by your settings) are executed.

check_lockstring(accessing_obj, lockstring, no_superuser_bypass=False, default=False, access_type=None)

Do a direct check against a lockstring (‘atype:func()..’), without any intermediary storage on the accessed object.

Parameters:

• accessing_obj (object or None) – The object seeking access. Importantly, this can be left unset if the lock functions don’t access it, no updating or storage of locks are made against this object in this method.

• lockstring (str) – Lock string to check, on the form “access_type:lock_definition” where the access_type part can potentially be set to a dummy value to just check a lock condition.

• no_superuser_bypass (bool, optional) – Force superusers to heed lock.

• default (bool, optional) – Fallback result to use if access_type is set but no such access_type is found in the given lockstring.

• access_type (str, bool) – If set, only this access_type will be looked up among the locks defined by lockstring.

Returns:

access (bool) – If check is passed or not.

clear()

Remove all locks in the handler.

delete(access_type)

Remove a particular lock from the handler

Parameters:

access_type (str) – The type of lock to remove.

Returns:

success (bool) –

If the access_type was not found

in the lock, this returns False.

get(access_type=None)

Get the full lockstring or the lockstring of a particular access type.

Parameters:

access_type (str, optional)

Returns:

lockstring (str) –

The matched lockstring, or the full

lockstring if no access_type was given.

remove(access_type)

Remove a particular lock from the handler

Parameters:

access_type (str) – The type of lock to remove.

Returns:

success (bool) –

If the access_type was not found

in the lock, this returns False.

replace(lockstring)

Replaces the lockstring entirely.

Parameters:

lockstring (str) – The new lock definition.

Returns:

success (bool) – False if an error occurred.

Raises:

LockException – If a critical error occurred. If so, the old string is recovered.

reset()

Set the reset flag, so the the lock will be re-cached at next checking. This is usually called by @reload.

validate(lockstring)

Validate lockstring syntactically, without saving it.

Parameters:

lockstring (str) – Lockstring to validate.

Returns:

valid (bool) – If validation passed or not.

class evennia.comms.models.SharedMemoryModel(*args, **kwargs)

Bases: Model

Base class for idmapped objects. Inherit from this.

class Meta

Bases: object

abstract = False

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.

classmethod cache_instance(instance, new=False)

Method to store an instance in the cache.

Parameters:

• instance (Class instance) – the instance to cache.

• new (bool, optional) – this is the first time this instance is cached (i.e. this is not an update operation like after a db save).

delete(*args, **kwargs)

Delete the object, clearing cache.

classmethod flush_cached_instance(instance, force=True)

Method to flush an instance from the cache. The instance will always be flushed from the cache, since this is most likely called from delete(), and we want to make sure we don’t cache dead objects.

flush_from_cache(force=False)

Flush this instance from the instance cache. Use force to override the result of at_idmapper_flush() for the object.

classmethod flush_instance_cache(force=False)

This will clean safe objects from the cache. Use force keyword to remove all objects, safe or not.

classmethod get_all_cached_instances()

Return the objects so far cached by idmapper for this class.

classmethod get_cached_instance(id)

Method to retrieve a cached instance by pk value. Returns None when not found (which will always be the case when caching is disabled for this class). Please note that the lookup will be done even when instance caching is disabled.

objects

path = 'evennia.utils.idmapper.models.SharedMemoryModel'

save(*args, **kwargs)

Central database save operation.

Notes

Arguments as per Django documentation. Calls self.at_<fieldname>_postsave(new) (this is a wrapper set by oobhandler: self._oob_at_<fieldname>_postsave())

typename = 'SharedMemoryModelBase'

class evennia.comms.models.Tag(*args, **kwargs)

Bases: Model

Tags are quick markers for objects in-game. An typeobject can have any number of tags, stored via its db_tags property. Tagging similar objects will make it easier to quickly locate the group later (such as when implementing zones). The main advantage of tagging as opposed to using tags is speed; a tag is very limited in what data it can hold, and the tag key+category is indexed for efficient lookup in the database. Tags are shared between objects - a new tag is only created if the key+category combination did not previously exist, making them unsuitable for storing object-related data (for this a regular Attribute should be used).

The ‘db_data’ field is intended as a documentation field for the tag itself, such as to document what this tag+category stands for and display that in a web interface or similar.

The main default use for Tags is to implement Aliases for objects. this uses the ‘aliases’ tag category, which is also checked by the default search functions of Evennia to allow quick searches by alias.

exception DoesNotExist

Bases: ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: 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.

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_data

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

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_model

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

db_tagtype

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

helpentry_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.

id

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

msg_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.

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.

objects = <django.db.models.manager.Manager object>

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.

class evennia.comms.models.TagHandler(obj)

Bases: object

Generic tag-handler. Accessed via TypedObject.tags.

__init__(obj)

Tags are stored internally in the TypedObject.db_tags m2m field with an tag.db_model based on the obj the taghandler is stored on and with a tagtype given by self.handlertype

Parameters:

obj (object) – The object on which the handler is set.

add(key=None, category=None, data=None)

Add a new tag to the handler.

Parameters:

• key (str or list) – The name of the tag to add. If a list, add several Tags.

• category (str, optional) – Category of Tag. None is the default category.

• data (str, optional) – Info text about the tag(s) added. This can not be used to store object-unique info but only eventual info about the tag itself.

Notes

If the tag + category combination matches an already existing Tag object, this will be re-used and no new Tag will be created.

all(return_key_and_category=False, return_objs=False)

Get all tags in this handler, regardless of category.

Parameters:

• return_key_and_category (bool, optional) – Return a list of tuples [(key, category), …].

• return_objs (bool, optional) – Return tag objects.

Returns:

tags (list) –

A list of tag keys [tagkey, tagkey, …] or

a list of tuples [(key, category), …] if return_key_and_category is set.

batch_add(*args)

Batch-add tags from a list of tuples.

Parameters:

*args (tuple or str) – Each argument should be a tagstr keys or tuple (keystr, category) or (keystr, category, data). It’s possible to mix input types.

Notes

This will generate a mimimal number of self.add calls, based on the number of categories involved (including None) (data is not unique and may be overwritten by the content of a latter tuple with the same category).

batch_remove(*args)

Batch-remove tags from a list of tuples.

Parameters:

*args (tuple or str) – Each argument should be a tagstr keys or tuple (keystr, category) or (keystr, category, data) (the data field is ignored, only keystr/category matters). It’s possible to mix input types.

clear(category=None)

Remove all tags from the handler.

Parameters:

category (str, optional) – The Tag category to limit the request to. Note that None is the valid, default category.

get(key=None, default=None, category=None, return_tagobj=False, return_list=False, raise_exception=False)

Get the tag for the given key, category or combination of the two.

Parameters:

• key (str or list, optional) – The tag or tags to retrieve.

• default (any, optional) – The value to return in case of no match.

• category (str, optional) – The Tag category to limit the request to. Note that None is the valid, default category. If no key is given, all tags of this category will be returned.

• return_tagobj (bool, optional) – Return the Tag object itself instead of a string representation of the Tag.

• return_list (bool, optional) – Always return a list, regardless of number of matches.

• raise_exception (bool, optional) – Raise AttributeError if no matches are found.

Returns:

tags (list) –

The matches, either string

representations of the tags or the Tag objects themselves depending on return_tagobj. If ‘default’ is set, this will be a list with the default value as its only element.

Raises:

AttributeError – If finding no matches and raise_exception is True.

has(key=None, category=None, return_list=False)

Checks if the given Tag (or list of Tags) exists on the object.

Parameters:

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

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

Returns:

has_tag (bool or list) –

If the Tag exists on this object or not.

If tag was given as an iterable then the return is a list of booleans.

Raises:

ValueError – If neither tag nor category is given.

remove(key=None, category=None)

Remove a tag from the handler based ond key and/or category.

Parameters:

• key (str or list, optional) – The tag or tags to retrieve.

• category (str, optional) – The Tag category to limit the request to. Note that None is the valid, default category

Notes

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

reset_cache()

Reset the cache from the outside.

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

Bases: 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

class Meta

Bases: object

Django setup info.

abstract = False

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

verbose_name = 'Evennia Database Object'

__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:

parent. (Passed through to)

Keyword Arguments:

parent. (Passed through to)

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.

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:

kwar (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.

aliases

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).

at_init()

Called when this object is loaded into cache. This is more reliable than to override __init__.

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.

attributes

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.

property date_created

Get the localized date created, based on settings.TIME_ZONE.

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).

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_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_key

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_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.

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.

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.

delete()

Cleaning up handlers on the typeclass level

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.

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

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

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_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.

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)

init_evennia_properties()

Called by creation methods; makes sure to initialize Attribute/TagProperties by fetching them once.

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.

property key

property lock_storage

A wrapper for getting database field db_lock_storage.

locks

property name

nattributes

property ndb

NonDataBase). Everything stored to this is guaranteed to be cleared when a server is shutdown. Syntax is same as for the _get_db_holder() method and property, e.g. obj.ndb.attr = value etc.

Type:

A non-attr_obj store (ndb

objects

path = 'evennia.typeclasses.models.TypedObject'

permissions

classmethod search(query, **kwargs)

Overridden by class children. This implements a common API.

Parameters:

• query (str) – A search query.

• **kwargs – Other search parameters.

Returns:

list – A list of 0, 1 or more matches, only of this typeclass.

set_class_from_typeclass(typeclass_path=None)

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 with space-separated hook-names 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.

tags

property typeclass_path

A wrapper for getting database field db_typeclass_path.

typename = 'SharedMemoryModelBase'

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.

ex. 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.

ex. 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.

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.

Returns:

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

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.

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.

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.

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

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

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:

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.

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:

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.

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.

evennia.comms.models.crop(text, width=None, suffix='[...]')

Crop text to a certain width, throwing away text from too-long lines.

Parameters:

• text (str) – Text to crop.

• width (int, optional) – Width of line to crop, in characters.

• suffix (str, optional) – This is appended to the end of cropped lines to show that the line actually continues. Cropping will be done so that the suffix will also fit within the given width. If width is too small to fit both crop and suffix, the suffix will be dropped.

Returns:

text (str) – The cropped text.

class evennia.comms.models.lazy_property(func: Callable[[...], TProp], name=None, doc=None)

Bases: Generic[TProp]

Delays loading of property until first access. Credit goes to the Implementation in the werkzeug suite: http://werkzeug.pocoo.org/docs/utils/#werkzeug.utils.cached_property

This should be used as a decorator in a class and in Evennia is mainly used to lazy-load handlers:

@lazy_property
def attributes(self):
    return AttributeHandler(self)

Once initialized, the AttributeHandler will be available as a property “attributes” on the object. This is read-only since this functionality is pretty much exclusively used by handlers.

__init__(func: Callable[[...], TProp], name=None, doc=None)

Store all properties for now

evennia.comms.models.make_iter(obj)

Makes sure that the object is always iterable.

Parameters:

obj (any) – Object to make iterable.

Returns:

iterable (list or iterable) –

The same object

passed-through or made iterable.