evennia.help.manager

Custom manager for HelpEntry objects.

class evennia.help.manager.HelpEntryManager(*args, **kwargs)

Bases: TypedObjectManager

This HelpEntryManager implements methods for searching and manipulating HelpEntries directly from the database.

These methods will all return database objects (or QuerySets) directly.

Evennia-specific: find_topicmatch find_apropos find_topicsuggestions find_topics_with_category all_to_category search_help (equivalent to evennia.search_helpentry)

find_topicmatch(topicstr, exact=False)

Searches for matching topics or aliases based on player’s input.

Parameters:

• topcistr (str) – Help topic to search for.

• exact (bool, optional) – Require exact match (non-case-sensitive). If False (default), match sub-parts of the string.

Returns:

matches (HelpEntries) – Query results.

find_apropos(topicstr)

Do a very loose search, returning all help entries containing the search criterion in their titles.

Parameters:

topicstr (str) – Search criterion.

Returns:

matches (HelpEntries) – Query results.

find_topicsuggestions(topicstr)

Do a fuzzy match, preferably within the category of the current topic.

Parameters:

topicstr (str) – Search criterion.

Returns:

matches (Helpentries) – Query results.

find_topics_with_category(help_category)

Search topics having a particular category.

Parameters:

help_category (str) – Category query criterion.

Returns:

matches (HelpEntries) – Query results.

get_all_topics()

Get all topics.

Returns:

all (HelpEntries) – All topics.

get_all_categories()

Return all defined category names with at least one topic in them.

Returns:

matches (list) –

Unique list of category names across all

topics.

all_to_category(default_category)

Shifts all help entries in database to default_category. This action cannot be reverted. It is used primarily by the engine when importing a default help database, making sure this ends up in one easily separated category.

Parameters:

default_category (str) – Category to move entries to.

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

create_help(key, entrytext, category='General', locks=None, aliases=None, tags=None)

Create a static help entry in the help database. Note that Command help entries are dynamic and directly taken from the __doc__ entries of the command. The database-stored help entries are intended for more general help on the game, more extensive info, in-game setting information and so on.

Parameters:

• key (str) – The name of the help entry.

• entrytext (str) – The body of te help entry

• category (str, optional) – The help category of the entry.

• locks (str, optional) – A lockstring to restrict access.

• aliases (list of str, optional) – List of alternative (likely shorter) keynames.

• tags (lst, optional) – List of tags or tuples (tag, category).

Returns:

help (HelpEntry) – A newly created help entry.

exception evennia.help.manager.IntegrityError

Bases: DatabaseError

class evennia.help.manager.TypedObjectManager(*args, **kwargs)

Bases: SharedMemoryManager

Common ObjectManager for all dbobjects.

create_tag(key=None, category=None, data=None, tagtype=None)

Create a new Tag of the base type associated with this object. This makes sure to create case-insensitive tags. If the exact same tag configuration (key+category+tagtype+dbmodel) exists on the model, a new tag will not be created, but an old one returned.

Parameters:

• key (str, optional) – Tag key. Not case sensitive.

• category (str, optional) – Tag category. Not case sensitive.

• data (str, optional) – Extra information about the tag.

• tagtype (str or None, optional) – ‘type’ of Tag, by default this is either None (a normal Tag), alias or permission.

Notes

The data field is not part of the uniqueness of the tag: Setting data on an existing tag will overwrite the old data field. It is intended only as a way to carry information about the tag (like a help text), not to carry any information about the tagged objects themselves.

dbref(dbref, reqhash=True)

Determing if input is a valid dbref.

Parameters:

• dbref (str or int) – A possible dbref.

• reqhash (bool, optional) – If the “#” is required for this to be considered a valid hash.

Returns:

dbref (int or None) – The integer part of the dbref.

Notes

Valid forms of dbref (database reference number) are either a string ‘#N’ or an integer N.

dbref_search(dbref)

Alias to get_id.

Parameters:

dbref (str or int) – The id to search for.

Returns:

Queryset – Queryset with 0 or 1 match.

get_alias(key=None, category=None, obj=None)

Get an alias from the database.

Parameters:

• key (str, optional) – The permission’s identifier.

• category (str, optional) – The permission’s category.

• obj (object, optional) – The object on which this Tag is set.

Returns:

alias (list) – Alias objects.

get_attribute(key=None, category=None, value=None, strvalue=None, obj=None, attrtype=None, **kwargs)

Return Attribute objects by key, by category, by value, by strvalue, by object (it is stored on) or with a combination of those criteria.

Parameters:

• key (str, optional) – The attribute’s key to search for

• category (str, optional) – The category of the attribute(s) to search for.

• value (str, optional) – The attribute value to search for. Note that this is not a very efficient operation since it will query for a pickled entity. Mutually exclusive to strvalue.

• strvalue (str, optional) – The str-value to search for. Most Attributes will not have strvalue set. This is mutually exclusive to the value keyword and will take precedence if given.

• obj (Object, optional) – On which object the Attribute to search for is.

• attrype (str, optional) – An attribute-type to search for. By default this is either None (normal Attributes) or “nick”.

• **kwargs (any) – Currently unused. Reserved for future use.

Returns:

list – The matching Attributes.

get_by_alias(key=None, category=None)

Return objects having aliases with a given key or category or combination of the two.

Parameters:

• key (str, optional) – Alias key. Not case sensitive.

• category (str, optional) – Alias category. Not case sensitive.

Returns:

objects (list) – Objects with matching alias.

get_by_attribute(key=None, category=None, value=None, strvalue=None, attrtype=None, **kwargs)

Return objects having attributes with the given key, category, value, strvalue or combination of those criteria.

Parameters:

• key (str, optional) – The attribute’s key to search for

• category (str, optional) – The category of the attribute to search for.

• value (str, optional) – The attribute value to search for. Note that this is not a very efficient operation since it will query for a pickled entity. Mutually exclusive to strvalue.

• strvalue (str, optional) – The str-value to search for. Most Attributes will not have strvalue set. This is mutually exclusive to the value keyword and will take precedence if given.

• attrype (str, optional) – An attribute-type to search for. By default this is either None (normal Attributes) or “nick”.

• kwargs (any) – Currently unused. Reserved for future use.

Returns:

obj (list) – Objects having the matching Attributes.

get_by_nick(key=None, nick=None, category='inputline')

Get object based on its key or nick.

Parameters:

• key (str, optional) – The attribute’s key to search for

• nick (str, optional) – The nickname to search for

• category (str, optional) – The category of the nick to search for.

Returns:

obj (list) – Objects having the matching Nicks.

get_by_permission(key=None, category=None)

Return objects having permissions with a given key or category or combination of the two.

Parameters:

• key (str, optional) – Permissions key. Not case sensitive.

• category (str, optional) – Permission category. Not case sensitive.

Returns:

objects (list) – Objects with matching permission.

get_by_tag(key=None, category=None, tagtype=None, **kwargs)

Return objects having tags with a given key or category or combination of the two. Also accepts multiple tags/category/tagtype

Parameters:

• key (str or list, optional) – Tag key or list of keys. Not case sensitive.

• category (str or list, optional) – Tag category. Not case sensitive. If key is a list, a single category can either apply to all keys in that list or this must be a list matching the key list element by element. If no key is given, all objects with tags of this category are returned.

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

Keyword Arguments:

match (str) – “all” (default) or “any”; determines whether the target object must be tagged with ALL of the provided tags/categories or ANY single one. ANY will perform a weighted sort, so objects with more tag matches will outrank those with fewer tag matches.

Returns:

objects (list) – Objects with matching tag.

Raises:

IndexError – If key and category are both lists and category is shorter than key.

get_dbref_range(min_dbref=None, max_dbref=None)

Get objects within a certain range of dbrefs.

Parameters:

• min_dbref (int) – Start of dbref range.

• max_dbref (int) – End of dbref range (inclusive)

Returns:

objects (list) –

TypedObjects with dbrefs within

the given dbref ranges.

get_id(dbref)

Find object with given dbref.

Parameters:

dbref (str or int) – The id to search for.

Returns:

object (TypedObject) – The matched object.

get_nick(key=None, category=None, value=None, strvalue=None, obj=None)

Get a nick, in parallel to get_attribute.

Parameters:

• key (str, optional) – The nicks’s key to search for

• category (str, optional) – The category of the nicks(s) to search for.

• value (str, optional) – The attribute value to search for. Note that this is not a very efficient operation since it will query for a pickled entity. Mutually exclusive to strvalue.

• strvalue (str, optional) – The str-value to search for. Most Attributes will not have strvalue set. This is mutually exclusive to the value keyword and will take precedence if given.

• obj (Object, optional) – On which object the Attribute to search for is.

Returns:

nicks (list) – The matching Nicks.

get_permission(key=None, category=None, obj=None)

Get a permission from the database.

Parameters:

• key (str, optional) – The permission’s identifier.

• category (str, optional) – The permission’s category.

• obj (object, optional) – The object on which this Tag is set.

Returns:

permission (list) – Permission objects.

get_tag(key=None, category=None, obj=None, tagtype=None, global_search=False)

Return Tag objects by key, by category, by object (it is stored on) or with a combination of those criteria.

Parameters:

• key (str, optional) – The Tag’s key to search for

• category (str, optional) – The Tag of the attribute(s) to search for.

• obj (Object, optional) – On which object the Tag to search for is.

• tagtype (str, optional) – One of None (normal tags), “alias” or “permission”

• global_search (bool, optional) – Include all possible tags, not just tags on this object

Returns:

tag (list) – The matching Tags.

get_typeclass_totals(*args, **kwargs) → object

Returns a queryset of typeclass composition statistics.

Returns:

qs (Queryset) –

A queryset of dicts containing the typeclass (name),

the count of objects with that typeclass and a float representing the percentage of objects associated with the typeclass.

object_totals()

Get info about database statistics.

Returns:

census (dict) –

A dictionary {typeclass_path: number, …} with

all the typeclasses active in-game as well as the number of such objects defined (i.e. the number of database object having that typeclass set on themselves).

search_dbref(dbref)

Alias to get_id.

Parameters:

dbref (str or int) – The id to search for.

Returns:

Queryset – Queryset with 0 or 1 match.

typeclass_search(typeclass, include_children=False, include_parents=False)

Searches through all objects returning those which are of the specified 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. Mutually 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.

Raises:

ImportError – If the provided typeclass is not a valid typeclass or the path to an existing typeclass.

evennia.help.manager.make_iter(obj)

Makes sure that the object is always iterable.

Parameters:

obj (any) – Object to make iterable.

Returns:

iterable (list or iterable) –

The same object

passed-through or made iterable.