evennia.objects.manager

Custom manager for Objects.

class evennia.objects.manager.ObjectManager(*args, **kwargs)

Bases: evennia.objects.manager.ObjectDBManager, evennia.typeclasses.managers.TypeclassManager

class evennia.objects.manager.ObjectDBManager(*args, **kwargs)

Bases: evennia.typeclasses.managers.TypedObjectManager

This ObjectManager implements methods for searching and manipulating Objects directly from the database.

Evennia-specific search methods (will return Typeclasses or lists of Typeclasses, whereas Django-general methods will return Querysets or database objects).

dbref (converter) dbref_search get_dbref_range object_totals typeclass_search get_object_with_account get_objs_with_key_and_typeclass get_objs_with_attr get_objs_with_attr_match get_objs_with_db_property get_objs_with_db_property_match get_objs_with_key_or_alias get_contents search_object (interface to many of the above methods,

equivalent to evennia.search_object)

copy_object

get_object_with_account(ostring, exact=True, candidates=None)

Search for an object based on its account’s name or dbref.

Parameters

• ostring (str or int) – Search criterion or dbref. Searching for an account is sometimes initiated by appending an * to the beginning of the search criterion (e.g. in local_and_global_search). This is stripped here.

• exact (bool, optional) – Require an exact account match.

• candidates (list, optional) – Only search among this list of possible object candidates.

Returns

match (query) – Matching query.

get_objs_with_key_and_typeclass(oname, otypeclass_path, candidates=None)

Returns objects based on simultaneous key and typeclass match.

Parameters

• oname (str) – Object key to search for

• otypeclass_path (str) – Full Python path to tyepclass to search for

• candidates (list, optional) – Only match among the given list of candidates.

Returns

matches (query) – The matching objects.

get_objs_with_attr(attribute_name, candidates=None)

Get objects based on having a certain Attribute defined.

Parameters

• attribute_name (str) – Attribute name to search for.

• candidates (list, optional) – Only match among the given list of object candidates.

Returns

matches (query) – All objects having the given attribute_name defined at all.

get_objs_with_attr_value(attribute_name, attribute_value, candidates=None, typeclasses=None)

Get all objects having the given attrname set to the given value.

Parameters

• attribute_name (str) – Attribute key to search for.

• attribute_value (any) – Attribute value to search for. This can also be database objects.

• candidates (list, optional) – Candidate objects to limit search to.

• typeclasses (list, optional) – Python pats to restrict matches with.

Returns

Queryset –

Iterable with 0, 1 or more matches fullfilling both the attribute_name and

attribute_value criterions.

Notes

This uses the Attribute’s PickledField to transparently search the database by matching the internal representation. This is reasonably effective but since Attribute values cannot be indexed, searching by Attribute key is to be preferred whenever possible.

get_objs_with_db_property(property_name, candidates=None)

Get all objects having a given db field property.

Parameters

• property_name (str) – The name of the field to match for.

• candidates (list, optional) – Only search among th egiven candidates.

Returns

matches (list) – The found matches.

get_objs_with_db_property_value(property_name, property_value, candidates=None, typeclasses=None)

Get objects with a specific field name and value.

Parameters

• property_name (str) – Field name to search for.

• property_value (any) – Value required for field with property_name to have.

• candidates (list, optional) – List of objects to limit search to.

• typeclasses (list, optional) – List of typeclass-path strings to restrict matches with

Returns

Queryset – Iterable with 0, 1 or more matches.

get_contents(location, excludeobj=None)

Get all objects that has a location set to this one.

Parameters

• location (Object) – Where to get contents from.

• excludeobj (Object or list, optional) – One or more objects to exclude from the match.

Returns

Queryset – Iterable with 0, 1 or more matches.

get_objs_with_key_or_alias(ostring, exact=True, candidates=None, typeclasses=None)

Parameters

• ostring (str) – A search criterion.

• exact (bool, optional) – Require exact match of ostring (still case-insensitive). If False, will do fuzzy matching using evennia.utils.utils.string_partial_matching algorithm.

• candidates (list) – Only match among these candidates.

• typeclasses (list) – Only match objects with typeclasses having thess path strings.

Returns

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

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

object_search(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

search(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

copy_object(original_object, new_key=None, new_location=None, new_home=None, new_permissions=None, new_locks=None, new_aliases=None, new_destination=None)

Create and return a new object as a copy of the original object. All will be identical to the original except for the arguments given specifically to this method. Object contents will not be copied.

Parameters

• original_object (Object) – The object to make a copy from.

• new_key (str, optional) – Name of the copy, if different from the original.

• new_location (Object, optional) – Alternate location.

• new_home (Object, optional) – Change the home location

• new_aliases (list, optional) – Give alternate object aliases as a list of strings.

• new_destination (Object, optional) – Used only by exits.

Returns

copy (Object or None) –

The copy of original_object,

optionally modified as per the ingoing keyword arguments. None if an error was encountered.

clear_all_sessids()

Clear the db_sessid field of all objects having also the db_account field set.

create_object(typeclass=None, key=None, location=None, home=None, permissions=None, locks=None, aliases=None, tags=None, destination=None, report_to=None, nohome=False, attributes=None, nattributes=None)

Create a new in-game object.

Keyword Arguments

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

• key (str) – Name of the new object. If not set, a name of #dbref will be set.

• location (Object or str) – Obj or #dbref to use as the location of the new object.

• home (Object or str) – Obj or #dbref to use as the object’s home location.

• permissions (list) – A list of permission strings or tuples (permstring, category).

• locks (str) – one or more lockstrings, separated by semicolons.

• aliases (list) – A list of alternative keys or tuples (aliasstring, category).

• tags (list) – List of tag keys or tuples (tagkey, category) or (tagkey, category, data).

• destination (Object or str) – Obj or #dbref to use as an Exit’s target.

• report_to (Object) – The object to return error messages to.

• nohome (bool) – This allows the creation of objects without a default home location; only used when creating the default location itself or during unittests.

• attributes (list) – Tuples on the form (key, value) or (key, value, category), (key, value, lockstring) or (key, value, lockstring, default_access). to set as Attributes on the new object.

• nattributes (list) – Non-persistent tuples on the form (key, value). Note that adding this rarely makes sense since this data will not survive a reload.

Returns

object (Object) – A newly created object of the given typeclass.

Raises

ObjectDB.DoesNotExist – If trying to create an Object with location or home that can’t be found.