Source code for evennia.help.manager
"""
Custom manager for HelpEntry objects.
"""
from django.db import IntegrityError
from evennia.server import signals
from evennia.typeclasses.managers import TypedObjectManager
from evennia.utils import logger, utils
from evennia.utils.utils import make_iter
__all__ = ("HelpEntryManager",)
[docs]class HelpEntryManager(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)
"""
[docs] def find_topicmatch(self, topicstr, exact=False):
"""
Searches for matching topics or aliases based on player's
input.
Args:
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.
"""
dbref = utils.dbref(topicstr)
if dbref:
return self.filter(id=dbref)
topics = self.filter(db_key__iexact=topicstr)
if not topics:
topics = self.get_by_alias(topicstr)
if not topics and not exact:
topics = self.filter(db_key__istartswith=topicstr)
if not topics:
topics = self.filter(db_key__icontains=topicstr)
return topics
[docs] def find_apropos(self, topicstr):
"""
Do a very loose search, returning all help entries containing
the search criterion in their titles.
Args:
topicstr (str): Search criterion.
Returns:
matches (HelpEntries): Query results.
"""
return self.filter(db_key__icontains=topicstr)
[docs] def find_topicsuggestions(self, topicstr):
"""
Do a fuzzy match, preferably within the category of the
current topic.
Args:
topicstr (str): Search criterion.
Returns:
matches (Helpentries): Query results.
"""
return self.filter(db_key__icontains=topicstr).exclude(db_key__iexact=topicstr)
[docs] def find_topics_with_category(self, help_category):
"""
Search topics having a particular category.
Args:
help_category (str): Category query criterion.
Returns:
matches (HelpEntries): Query results.
"""
return self.filter(db_help_category__iexact=help_category)
[docs] def get_all_topics(self):
"""
Get all topics.
Returns:
all (HelpEntries): All topics.
"""
return self.all()
[docs] def get_all_categories(self):
"""
Return all defined category names with at least one topic in
them.
Returns:
matches (list): Unique list of category names across all
topics.
"""
return list(set(topic.help_category for topic in self.all()))
[docs] def all_to_category(self, 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.
Args:
default_category (str): Category to move entries to.
"""
topics = self.all()
for topic in topics:
topic.help_category = default_category
topic.save()
string = "Help database moved to category {default_category}".format(
default_category=default_category
)
logger.log_info(string)
[docs] def search_help(self, ostring, help_category=None):
"""
Retrieve a search entry object.
Args:
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.
"""
ostring = ostring.strip().lower()
if help_category:
return self.filter(db_key__iexact=ostring, db_help_category__iexact=help_category)
else:
return self.filter(db_key__iexact=ostring)
[docs] def create_help(self, 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.
Args:
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.
"""
try:
new_help = self.model()
new_help.key = key
new_help.entrytext = entrytext
new_help.help_category = category
if locks:
new_help.locks.add(locks)
if aliases:
new_help.aliases.add(make_iter(aliases))
if tags:
new_help.tags.batch_add(*tags)
new_help.save()
return new_help
except IntegrityError:
string = "Could not add help entry: key '%s' already exists." % key
logger.log_err(string)
return None
except Exception:
logger.log_trace()
return None
signals.SIGNAL_HELPENTRY_POST_CREATE.send(sender=new_help)
