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(searchdata, attribute_name=None, typeclass=None, candidates=None, exact=True, use_dbref=True, tags=None)

Search as an object globally or in a list of candidates and return results. The result is always an Object. Always returns a list.

Parameters

• searchdata (str or Object) – The entity to match for. This is usually a key string but may also be an object itself. By default (if no attribute_name is set), this will search object.key and object.aliases in order. Can also be on the form #dbref, which will (if exact=True) be matched against primary key.

• attribute_name (str) – Use this named Attribute to match searchdata against, instead of the defaults. If this is the name of a database field (with or without the db_ prefix), that will be matched too.

• typeclass (str or TypeClass) – restrict matches to objects having this typeclass. This will help speed up global searches.

• candidates (list) – If supplied, search will only be performed among the candidates in this list. A common list of candidates is the contents of the current location searched.

• exact (bool) – Match names/aliases exactly or partially. Partial matching matches the beginning of words in the names/aliases, using a matching routine to separate multiple matches in names with multiple components (so “bi sw” will match “Big sword”). Since this is more expensive than exact matching, it is recommended to be used together with the candidates keyword to limit the number of possibilities. This value has no meaning if searching for attributes/properties.

• use_dbref (bool) – If False, bypass direct lookup of a string on the form #dbref and treat it like any string.

• tags (list) – A list of tuples (tagkey, tagcategory) where the matched object must have _all_ tags in order to be considered a match.

Returns

matches (list) – Matching objects

evennia.utils.search.search_account(ostring, exact=True, typeclass=None)

Searches for a particular account by name or database id.

Parameters

• ostring (str or int) – A key string or database id.

• exact (bool, optional) – Only valid for string matches. If True, requires exact (non-case-sensitive) match, otherwise also match also keys containing the ostring (non-case-sensitive fuzzy match).

• typeclass (str or Typeclass, optional) – Limit the search only to accounts of this typeclass.

Returns

Queryset – A queryset (an iterable) with 0, 1 or more matches.

evennia.utils.search.search_script(ostring, obj=None, only_timed=False, typeclass=None)

Search for a particular script.

Parameters

• ostring (str) – Search criterion - a script dbef or key.

• obj (Object, optional) – Limit search to scripts defined on this object

• only_timed (bool) – Limit search only to scripts that run on a timer.

• typeclass (class or str) – Typeclass or path to typeclass.

Returns

Queryset – An iterable with 0, 1 or more results.

evennia.utils.search.search_message(sender=None, receiver=None, freetext=None, dbref=None)

Search the message database for particular messages. At least one of the arguments must be given to do a search.

Parameters

• sender (Object, Account or Script, optional) – Get messages sent by a particular sender.

• receiver (Object, Account or Channel, optional) – Get messages received by a certain account,object or channel

• freetext (str) – Search for a text string in a message. NOTE: This can potentially be slow, so make sure to supply one of the other arguments to limit the search.

• dbref (int) – The exact database id of the message. This will override all other search criteria since it’s unique and always gives only one match.

Returns

Queryset – Iterable with 0, 1 or more matches.

evennia.utils.search.search_channel(ostring, exact=True)

Search the channel database for a particular channel.

Parameters

• ostring (str) – The key or database id of the channel.

• exact (bool, optional) – Require an exact (but not case sensitive) match.

Returns

Queryset – Iterable with 0, 1 or more matches.

evennia.utils.search.search_help_entry(ostring, help_category=None)

Retrieve a search entry object.

Parameters

• ostring (str) – The help topic to look for.

• category (str) – Limit the search to a particular help topic

Returns

Queryset – An iterable with 0, 1 or more matches.

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.

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 Scripts with tags matching

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

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

Find account 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 Accounts with tags matching

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

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

Find channel 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 Channels with tags matching

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

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.