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.
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.
A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.
A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.
A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.
A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.
A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.
Bases:
django.core.exceptions.ObjectDoesNotExist
Bases:
django.core.exceptions.MultipleObjectsReturned
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.
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.
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.
A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.
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.
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.
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.
Bases:
object
Generic tag-handler. Accessed via TypedObject.tags.
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 the cache from the outside.
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.
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 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 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().
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 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 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).
Bases:
evennia.typeclasses.tags.TagHandler
A handler for the Alias Tag type.
Bases:
evennia.typeclasses.tags.TagHandler
A handler for the Permission Tag type.