evennia.utils.search

This is a convenient container gathering all the main search methods for the various database tables.

It is intended to be used e.g. as

> from evennia.utils import search > match = search.objects(…)

Note that this is not intended to be a complete listing of all search methods! You need to refer to the respective manager to get all possible search methods. To get to the managers from your code, import the database model and call its ‘objects’ property.

Also remember that all commands in this file return lists (also if there is only one match) unless noted otherwise.

Example: To reach the search method ‘get_object_with_account’

in evennia/objects/managers.py:

> from evennia.objects.models import ObjectDB > match = Object.objects.get_object_with_account(…)

evennia.utils.search.search_object(*args, **kwargs)

Search for objects in the database.

Parameters

• key (str or int) – Object key or dbref to search for. This can also be a list of keys/dbrefs. None (default) returns all objects.

• exact (bool) – Only valid for string keys. If True, requires exact key match, otherwise also match key with case-insensitive and partial matching. Default is True.

• candidates (list) – Only search among these object candidates, if given. Default is to search all objects.

• attribute_name (str) – If set, search by objects with this attribute_name defined on them, with the value specified by attribute_value.

• attribute_value (any) – What value the given attribute_name must have.

• location (Object) – Filter by objects at this location.

• typeclass (str or TypeClass) – Filter by objects having this typeclass. This can also be a list of typeclasses.

• tags (str or list) – Filter by objects having one or more Tags. This can be a single tag key, a list of tag keys, or a list of tuples (tag_key, tag_category).

• nofetch (bool) – Don’t fetch typeclass and perms data from db. This is faster but gives less info.

Returns

matches (list) – List of Objects matching the search criteria.

evennia.utils.search.search_account(*args, **kwargs)

Search for accounts in the database.

Parameters

• key (str or int) – Account key or dbref to search for. This can also be a list of keys/dbrefs. None (default) returns all accounts.

• exact (bool) – Only valid for string keys. If True, requires exact key match, otherwise also match key with case-insensitive and partial matching. Default is True.

• candidates (list) – Only search among these account candidates, if given. Default is to search all accounts.

• attribute_name (str) – If set, search by accounts with this attribute_name defined on them, with the value specified by attribute_value.

• attribute_value (any) – What value the given attribute_name must have.

• tags (str or list) – Filter by accounts having one or more Tags. This can be a single tag key, a list of tag keys, or a list of tuples (tag_key, tag_category).

• nofetch (bool) – Don’t fetch typeclass and perms data from db. This is faster but gives less info.

Returns

matches (list) – List of Accounts matching the search criteria.

evennia.utils.search.search_script(*args, **kwargs)

Search for scripts in the database.

Parameters

• key (str or int) – Script key or dbref to search for. This can also be a list of keys/dbrefs. None (default) returns all scripts.

• exact (bool) – Only valid for string keys. If True, requires exact key match, otherwise also match key with case-insensitive and partial matching. Default is True.

• candidates (list) – Only search among these script candidates, if given. Default is to search all scripts.

• attribute_name (str) – If set, search by scripts with this attribute_name defined on them, with the value specified by attribute_value.

• attribute_value (any) – What value the given attribute_name must have.

• obj (Object) – Filter by scripts defined on this object.

• account (Account) – Filter by scripts defined on this account.

• typeclass (str or TypeClass) – Filter by scripts having this typeclass. This can also be a list of typeclasses.

• tags (str or list) – Filter by scripts having one or more Tags. This can be a single tag key, a list of tag keys, or a list of tuples (tag_key, tag_category).

• nofetch (bool) – Don’t fetch typeclass and perms data from db. This is faster but gives less info.

Returns

matches (list) – List of Scripts matching the search criteria.

evennia.utils.search.search_message(*args, **kwargs)

Search for messages in the database.

Parameters

• sender (Object, Account or str) – Filter by messages sent by this entity. If a string, this is an external sender name.

• receiver (Object, Account or str) – Filter by messages received by this entity. If a string, this is an external receiver name.

• channel (Channel) – Filter by messages sent to this channel.

• date (datetime) – Filter by messages sent on this date.

• type (str) – Filter by messages of this type.

• tags (str or list) – Filter by messages having one or more Tags. This can be a single tag key, a list of tag keys, or a list of tuples (tag_key, tag_category).

• exclude_tags (str or list) – Exclude messages with these tags.

• search_text (str) – Search for text in message content.

• exact (bool) – If True, require exact text match. Default False.

Returns

matches (list) – List of Messages matching the search criteria.

evennia.utils.search.search_channel(*args, **kwargs)

Search for channels in the database.

Parameters

• key (str or int) – Channel key or dbref to search for. This can also be a list of keys/dbrefs. None (default) returns all channels.

• exact (bool) – Only valid for string keys. If True, requires exact key match, otherwise also match key with case-insensitive and partial matching. Default is True.

• candidates (list) – Only search among these channel candidates, if given. Default is to search all channels.

• attribute_name (str) – If set, search by channels with this attribute_name defined on them, with the value specified by attribute_value.

• attribute_value (any) – What value the given attribute_name must have.

• typeclass (str or TypeClass) – Filter by channels having this typeclass. This can also be a list of typeclasses.

• tags (str or list) – Filter by channels having one or more Tags. This can be a single tag key, a list of tag keys, or a list of tuples (tag_key, tag_category).

• nofetch (bool) – Don’t fetch typeclass and perms data from db. This is faster but gives less info.

Returns

matches (list) – List of Channels matching the search criteria.

evennia.utils.search.search_help_entry(*args, **kwargs)

Search for help entries in the database.

Parameters

• key (str or int) – Help entry key or dbref to search for. This can also be a list of keys/dbrefs. None (default) returns all help entries.

• exact (bool) – Only valid for string keys. If True, requires exact key match, otherwise also match key with case-insensitive and partial matching. Default is True.

• category (str) – Filter by help entries in this category.

• tags (str or list) – Filter by help entries having one or more Tags. This can be a single tag key, a list of tag keys, or a list of tuples (tag_key, tag_category).

• locks (str) – Filter by help entries with these locks.

Returns

matches (list) – List of HelpEntries matching the search criteria.

evennia.utils.search.search_tag(key=None, category=None, tagtype=None, **kwargs)

Find object based on tag or category.

Parameters

• key (str, optional) – The tag key to search for.

• category (str, optional) – The category of tag to search for. If not set, uncategorized tags will be searched.

• tagtype (str, optional) – ‘type’ of Tag, by default this is either None (a normal Tag), alias or permission. This always apply to all queried tags.

• kwargs (any) – Other optional parameter that may be supported by the manager method.

Returns

matches (list) –

List of Objects with tags matching

the search criteria, or an empty list if no matches were found.

evennia.utils.search.search_script_tag(key=None, category=None, tagtype=None, **kwargs)

Find script based on tag or category.

evennia.utils.search.search_account_tag(key=None, category=None, tagtype=None, **kwargs)

Find account based on tag or category.

evennia.utils.search.search_channel_tag(key=None, category=None, tagtype=None, **kwargs)

Find channel based on tag or category.

evennia.utils.search.search_typeclass(typeclass, include_children=False, include_parents=False)

Searches through all objects returning those of a certain typeclass.

Parameters

• typeclass (str or class) – A typeclass class or a python path to a typeclass.

• include_children (bool, optional) – Return objects with given typeclass and all children inheriting from this typeclass. Mutuall exclusive to include_parents.

• include_parents (bool, optional) – Return objects with given typeclass and all parents to this typeclass. Mutually exclusive to include_children.

Returns

objects (list) – The objects found with the given typeclasses.