evennia.typeclasses.tags

Tags are entities that are attached to objects in the same way as Attributes. But contrary to Attributes, which are unique to an individual object, a single Tag can be attached to any number of objects at the same time.

Tags are used for tagging, obviously, but the data structure is also used for storing Aliases and Permissions. This module contains the respective handlers.

class evennia.typeclasses.tags.Tag(*args, **kwargs)

Bases: django.db.models.base.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.

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

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.

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.typeclasses.tags.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.

reset_cache()

Reset the cache from the outside.

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

Add a new tag to the handler.

Parameters

• tag (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.

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

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

Parameters

• tag (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.

get(key=None, default=None, category=None, return_tagobj=False, return_list=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.

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.

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

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.

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

class evennia.typeclasses.tags.AliasHandler(obj)

Bases: evennia.typeclasses.tags.TagHandler

A handler for the Alias Tag type.

class evennia.typeclasses.tags.PermissionHandler(obj)

Bases: evennia.typeclasses.tags.TagHandler

A handler for the Permission Tag type.