<spanid="evennia-commands-default-help"></span><h1>evennia.commands.default.help<aclass="headerlink"href="#module-evennia.commands.default.help"title="Permalink to this headline">¶</a></h1>
<p>The help command. The basic idea is that help texts for commands are best
written by those that write the commands - the developers. So command-help is
all auto-loaded and searched from the current command set. The normal,
database-tied help system is used for collaborative creation of other help
topics such as RP help or game-world aides. Help entries can also be created
outside the game in modules given by <strong>**settings.FILE_HELP_ENTRY_MODULES**</strong>.</p>
<dlclass="py class">
<dtid="evennia.commands.default.help.CmdHelp">
<emclass="property">class </em><codeclass="sig-prename descclassname">evennia.commands.default.help.</code><codeclass="sig-name descname">CmdHelp</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/commands/default/help.html#CmdHelp"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.commands.default.help.CmdHelp"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">key</code><emclass="property"> = 'help'</em><aclass="headerlink"href="#evennia.commands.default.help.CmdHelp.key"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">aliases</code><emclass="property"> = ['?']</em><aclass="headerlink"href="#evennia.commands.default.help.CmdHelp.aliases"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">locks</code><emclass="property"> = 'cmd:all()'</em><aclass="headerlink"href="#evennia.commands.default.help.CmdHelp.locks"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">arg_regex</code><emclass="property"> = re.compile('\\s|$', re.IGNORECASE)</em><aclass="headerlink"href="#evennia.commands.default.help.CmdHelp.arg_regex"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">return_cmdset</code><emclass="property"> = True</em><aclass="headerlink"href="#evennia.commands.default.help.CmdHelp.return_cmdset"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">help_more</code><emclass="property"> = True</em><aclass="headerlink"href="#evennia.commands.default.help.CmdHelp.help_more"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">index_type_separator_clr</code><emclass="property"> = '|w'</em><aclass="headerlink"href="#evennia.commands.default.help.CmdHelp.index_type_separator_clr"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">index_category_clr</code><emclass="property"> = '|W'</em><aclass="headerlink"href="#evennia.commands.default.help.CmdHelp.index_category_clr"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">index_topic_clr</code><emclass="property"> = '|G'</em><aclass="headerlink"href="#evennia.commands.default.help.CmdHelp.index_topic_clr"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">suggestion_cutoff</code><emclass="property"> = 0.6</em><aclass="headerlink"href="#evennia.commands.default.help.CmdHelp.suggestion_cutoff"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">suggestion_maxnum</code><emclass="property"> = 5</em><aclass="headerlink"href="#evennia.commands.default.help.CmdHelp.suggestion_maxnum"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">subtopic_separator_char</code><emclass="property"> = '/'</em><aclass="headerlink"href="#evennia.commands.default.help.CmdHelp.subtopic_separator_char"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">clickable_topics</code><emclass="property"> = True</em><aclass="headerlink"href="#evennia.commands.default.help.CmdHelp.clickable_topics"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">msg_help</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">text</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/commands/default/help.html#CmdHelp.msg_help"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.commands.default.help.CmdHelp.msg_help"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">format_help_index</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">cmd_help_dict</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">db_help_dict</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">title_lone_category</span><spanclass="o">=</span><spanclass="default_value">False</span></em>, <emclass="sig-param"><spanclass="n">click_topics</span><spanclass="o">=</span><spanclass="default_value">True</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/commands/default/help.html#CmdHelp.format_help_index"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.commands.default.help.CmdHelp.format_help_index"title="Permalink to this definition">¶</a></dt>
<dd><p>Output a category-ordered g for displaying the main help, grouped by
category.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>cmd_help_dict</strong> (<em>dict</em>) – A dict <strong>{“category”: [topic, topic, …]}</strong> for
command-based help.</p></li>
<li><p><strong>db_help_dict</strong> (<em>dict</em>) – A dict <strong>{“category”: [topic, topic], …]}</strong> for
database-based help.</p></li>
<li><p><strong>title_lone_category</strong> (<em>bool</em><em>, </em><em>optional</em>) – If a lone category should
be titled with the category name or not. While pointless in a
general index, the title should probably show when explicitly
listing the category itself.</p></li>
<li><p><strong>click_topics</strong> (<em>bool</em><em>, </em><em>optional</em>) – If help-topics are clickable or not
(for webclient or telnet clients with MXP support).</p></li>
</ul>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><em>str</em>– The help index organized into a grid.</p>
</dd>
</dl>
<pclass="rubric">Notes</p>
<p>The input are the pre-loaded help files for commands and database-helpfiles
respectively. You can override this method to return a custom display of the list of
<codeclass="sig-name descname">can_read_topic</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">cmd_or_topic</span></em>, <emclass="sig-param"><spanclass="n">caller</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/commands/default/help.html#CmdHelp.can_read_topic"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.commands.default.help.CmdHelp.can_read_topic"title="Permalink to this definition">¶</a></dt>
<dd><p>Helper method. If this return True, the given help topic
be viewable in the help listing. Note that even if this returns False,
the entry will still be visible in the help index unless <strong>should_list_topic</strong>
is also returning False.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>cmd_or_topic</strong> (<aclass="reference internal"href="evennia.commands.command.html#evennia.commands.command.Command"title="evennia.commands.command.Command"><em>Command</em></a><em>, </em><aclass="reference internal"href="evennia.help.models.html#evennia.help.models.HelpEntry"title="evennia.help.models.HelpEntry"><em>HelpEntry</em></a><em> or </em><aclass="reference internal"href="evennia.help.filehelp.html#evennia.help.filehelp.FileHelpEntry"title="evennia.help.filehelp.FileHelpEntry"><em>FileHelpEntry</em></a>) – The topic/command to test.</p></li>
<li><p><strong>caller</strong>– the caller checking for access.</p></li>
</ul>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><em>bool</em>– If command can be viewed or not.</p>
</dd>
</dl>
<pclass="rubric">Notes</p>
<p>This uses the ‘read’ lock. If no ‘read’ lock is defined, the topic is assumed readable
<codeclass="sig-name descname">can_list_topic</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">cmd_or_topic</span></em>, <emclass="sig-param"><spanclass="n">caller</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/commands/default/help.html#CmdHelp.can_list_topic"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.commands.default.help.CmdHelp.can_list_topic"title="Permalink to this definition">¶</a></dt>
<dd><p>Should the specified command appear in the help table?</p>
<p>This method only checks whether a specified command should appear in the table of
topics/commands. The command can be used by the caller (see the ‘should_show_help’ method)
and the command will still be available, for instance, if a character type ‘help name of the
command’. However, if you return False, the specified command will not appear in the table.
This is sometimes useful to “hide” commands in the table, but still access them through the
help system.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>cmd_or_topic</strong> (<aclass="reference internal"href="evennia.commands.command.html#evennia.commands.command.Command"title="evennia.commands.command.Command"><em>Command</em></a><em>, </em><aclass="reference internal"href="evennia.help.models.html#evennia.help.models.HelpEntry"title="evennia.help.models.HelpEntry"><em>HelpEntry</em></a><em> or </em><aclass="reference internal"href="evennia.help.filehelp.html#evennia.help.filehelp.FileHelpEntry"title="evennia.help.filehelp.FileHelpEntry"><em>FileHelpEntry</em></a>) – The topic/command to test.</p></li>
<li><p><strong>caller</strong>– the caller checking for access.</p></li>
</ul>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><em>bool</em>– If command should be listed or not.</p>
</dd>
</dl>
<pclass="rubric">Notes</p>
<p>The <strong>.auto_help</strong> propery is checked for commands. For all help entries,
the ‘view’ lock will be checked, and if no such lock is defined, the ‘read’
lock will be used. If neither lock is defined, the help entry is assumed to be
<codeclass="sig-name descname">collect_topics</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">caller</span></em>, <emclass="sig-param"><spanclass="n">mode</span><spanclass="o">=</span><spanclass="default_value">'list'</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/commands/default/help.html#CmdHelp.collect_topics"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.commands.default.help.CmdHelp.collect_topics"title="Permalink to this definition">¶</a></dt>
<dd><p>Collect help topics from all sources (cmd/db/file).</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>caller</strong> (<em>Object</em><em> or </em><em>Account</em>) – The user of the Command.</p></li>
<li><p><strong>mode</strong> (<em>str</em>) – One of ‘list’ or ‘query’, where the first means we are collecting to view
the help index and the second because of wanting to search for a specific help
entry/cmd to read. This determines which access should be checked.</p></li>
</ul>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><p><em>tuple</em>– A tuple of three dicts containing the different types of help entries
<codeclass="sig-name descname">do_search</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">query</span></em>, <emclass="sig-param"><spanclass="n">entries</span></em>, <emclass="sig-param"><spanclass="n">search_fields</span><spanclass="o">=</span><spanclass="default_value">None</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/commands/default/help.html#CmdHelp.do_search"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.commands.default.help.CmdHelp.do_search"title="Permalink to this definition">¶</a></dt>
<dd><p>Perform a help-query search, default using Lunr search engine.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>query</strong> (<em>str</em>) – The help entry to search for.</p></li>
<li><p><strong>entries</strong> (<em>list</em>) – All possibilities. A mix of commands, HelpEntries and FileHelpEntries.</p></li>
<li><p><strong>search_fields</strong> (<em>list</em>) – A list of dicts defining how Lunr will find the
search data on the elements. If not given, will use a default.</p></li>
</ul>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><em>tuple</em>– A tuple (match, suggestions).</p>
<codeclass="sig-name descname">parse</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/commands/default/help.html#CmdHelp.parse"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.commands.default.help.CmdHelp.parse"title="Permalink to this definition">¶</a></dt>
<dd><p>input is a string containing the command or topic to match.</p>
<codeclass="sig-name descname">strip_cmd_prefix</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">key</span></em>, <emclass="sig-param"><spanclass="n">all_keys</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/commands/default/help.html#CmdHelp.strip_cmd_prefix"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.commands.default.help.CmdHelp.strip_cmd_prefix"title="Permalink to this definition">¶</a></dt>
<dd><p>Conditional strip of a command prefix, such as @ in @desc. By default
this will be hidden unless there is a duplicate without the prefix
in the full command set (such as @open and open).</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>key</strong> (<em>str</em>) – Command key to analyze.</p></li>
<li><p><strong>all_cmds</strong> (<em>list</em>) – All command-keys (and potentially aliases).</p></li>
</ul>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><em>str</em>– Potentially modified key to use in help display.</p>
<codeclass="sig-name descname">func</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/commands/default/help.html#CmdHelp.func"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.commands.default.help.CmdHelp.func"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">help_category</code><emclass="property"> = 'general'</em><aclass="headerlink"href="#evennia.commands.default.help.CmdHelp.help_category"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">lock_storage</code><emclass="property"> = 'cmd:all()'</em><aclass="headerlink"href="#evennia.commands.default.help.CmdHelp.lock_storage"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">search_index_entry</code><emclass="property"> = {'aliases': '?', 'category': 'general', 'key': 'help', 'no_prefix': ' ?', 'tags': '', 'text': "\n Get help.\n\n Usage:\n help\n help <topic, command or category>\n help <topic>/<subtopic>\n help <topic>/<subtopic>/<subsubtopic> ...\n\n Use the 'help' command alone to see an index of all help topics, organized\n by category. Some big topics may offer additional sub-topics.\n\n "}</em><aclass="headerlink"href="#evennia.commands.default.help.CmdHelp.search_index_entry"title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
</dd></dl>
<dlclass="py class">
<dtid="evennia.commands.default.help.CmdSetHelp">
<emclass="property">class </em><codeclass="sig-prename descclassname">evennia.commands.default.help.</code><codeclass="sig-name descname">CmdSetHelp</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/commands/default/help.html#CmdSetHelp"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.commands.default.help.CmdSetHelp"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">key</code><emclass="property"> = 'sethelp'</em><aclass="headerlink"href="#evennia.commands.default.help.CmdSetHelp.key"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">aliases</code><emclass="property"> = []</em><aclass="headerlink"href="#evennia.commands.default.help.CmdSetHelp.aliases"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">locks</code><emclass="property"> = 'cmd:perm(Helper)'</em><aclass="headerlink"href="#evennia.commands.default.help.CmdSetHelp.locks"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">help_category</code><emclass="property"> = 'building'</em><aclass="headerlink"href="#evennia.commands.default.help.CmdSetHelp.help_category"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">arg_regex</code><emclass="property"> = None</em><aclass="headerlink"href="#evennia.commands.default.help.CmdSetHelp.arg_regex"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">parse</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/commands/default/help.html#CmdSetHelp.parse"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.commands.default.help.CmdSetHelp.parse"title="Permalink to this definition">¶</a></dt>
<dd><p>We want to use the default parser rather than the CmdHelp.parse</p>
<codeclass="sig-name descname">func</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/commands/default/help.html#CmdSetHelp.func"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.commands.default.help.CmdSetHelp.func"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">lock_storage</code><emclass="property"> = 'cmd:perm(Helper)'</em><aclass="headerlink"href="#evennia.commands.default.help.CmdSetHelp.lock_storage"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">search_index_entry</code><emclass="property"> = {'aliases': '', 'category': 'building', 'key': 'sethelp', 'no_prefix': ' ', 'tags': '', 'text': "\n Edit the help database.\n\n Usage:\n sethelp[/switches] <topic>[[;alias;alias][,category[,locks]] [= <text>]\n\n Switches:\n edit - open a line editor to edit the topic's help text.\n replace - overwrite existing help topic.\n append - add text to the end of existing topic with a newline between.\n extend - as append, but don't add a newline.\n delete - remove help topic.\n\n Examples:\n sethelp lore = In the beginning was ...\n sethelp/append pickpocketing,Thievery = This steals ...\n sethelp/replace pickpocketing, ,attr(is_thief) = This steals ...\n sethelp/edit thievery\n\n If not assigning a category, the `settings.DEFAULT_HELP_CATEGORY` category\n will be used. If no lockstring is specified, everyone will be able to read\n the help entry. Sub-topics are embedded in the help text.\n\n Note that this cannot modify command-help entries - these are modified\n in-code, outside the game.\n\n # SUBTOPICS\n\n ## Adding subtopics\n\n Subtopics helps to break up a long help entry into sub-sections. Users can\n access subtopics with |whelp topic/subtopic/...|n Subtopics are created and\n stored together with the main topic.\n\n To start adding subtopics, add the text '# SUBTOPICS' on a new line at the\n end of your help text. After this you can now add any number of subtopics,\n each starting with '## <subtopic-name>' on a line, followed by the\n help-text of that subtopic.\n Use '### <subsub-name>' to add a sub-subtopic and so on. Max depth is 5. A\n subtopic's title is case-insensitive and can consist of multiple words -\n the user will be able to enter a partial match to access it.\n\n For example:\n\n | Main help text for <topic>\n |\n | # SUBTOPICS\n |\n | ## about\n |\n | Text for the '<topic>/about' subtopic'\n |\n | ### more about-info\n |\n | Text for the '<topic>/about/more about-info sub-subtopic\n |\n | ## extra\n |\n | Text for the '<topic>/extra' subtopic\n\n "}</em><aclass="headerlink"href="#evennia.commands.default.help.CmdSetHelp.search_index_entry"title="Permalink to this definition">¶</a></dt>
