<spanid="evennia-utils-search"></span><h1>evennia.utils.search<aclass="headerlink"href="#module-evennia.utils.search"title="Permalink to this headline">¶</a></h1>
<p>This is a convenient container gathering all the main
search methods for the various database tables.</p>
<p>It is intended to be used e.g. as</p>
<p>> from evennia.utils import search
> match = search.objects(…)</p>
<p>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.</p>
<p>Also remember that all commands in this file return lists (also if
there is only one match) unless noted otherwise.</p>
<dlclass="simple">
<dt>Example: To reach the search method ‘get_object_with_account’</dt><dd><p>in evennia/objects/managers.py:</p>
</dd>
</dl>
<p>> from evennia.objects.models import ObjectDB
> match = Object.objects.get_object_with_account(…)</p>
<codeclass="sig-prename descclassname">evennia.utils.search.</code><codeclass="sig-name descname">search_account</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">ostring</span></em>, <emclass="sig-param"><spanclass="n">exact</span><spanclass="o">=</span><spanclass="default_value">True</span></em>, <emclass="sig-param"><spanclass="n">typeclass</span><spanclass="o">=</span><spanclass="default_value">None</span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#evennia.utils.search.search_account"title="Permalink to this definition">¶</a></dt>
<dd><p>Searches for a particular account by name or
database id.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>ostring</strong> (<em>str</em><em> or </em><em>int</em>) – A key string or database id.</p></li>
<li><p><strong>exact</strong> (<em>bool</em><em>, </em><em>optional</em>) – Only valid for string matches. If
otherwise also match also keys containing the <strong>ostring</strong>
(non-case-sensitive fuzzy match).</p></li>
<li><p><strong>typeclass</strong> (<em>str</em><em> or </em><em>Typeclass</em><em>, </em><em>optional</em>) – Limit the search only to
accounts of this typeclass.</p></li>
</ul>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><em>Queryset</em>– A queryset (an iterable) with 0, 1 or more matches.</p>
</dd>
</dl>
</dd></dl>
<dlclass="py function">
<dtid="evennia.utils.search.search_script">
<codeclass="sig-prename descclassname">evennia.utils.search.</code><codeclass="sig-name descname">search_script</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">ostring</span></em>, <emclass="sig-param"><spanclass="n">obj</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">only_timed</span><spanclass="o">=</span><spanclass="default_value">False</span></em>, <emclass="sig-param"><spanclass="n">typeclass</span><spanclass="o">=</span><spanclass="default_value">None</span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#evennia.utils.search.search_script"title="Permalink to this definition">¶</a></dt>
<dd><p>Search for a particular script.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>ostring</strong> (<em>str</em>) – Search criterion - a script dbef or key.</p></li>
<li><p><strong>obj</strong> (<em>Object</em><em>, </em><em>optional</em>) – Limit search to scripts defined on
this object</p></li>
<li><p><strong>only_timed</strong> (<em>bool</em>) – Limit search only to scripts that run
on a timer.</p></li>
<li><p><strong>typeclass</strong> (<em>class</em><em> or </em><em>str</em>) – Typeclass or path to typeclass.</p></li>
</ul>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><em>Queryset</em>– An iterable with 0, 1 or more results.</p>
</dd>
</dl>
</dd></dl>
<dlclass="py function">
<dtid="evennia.utils.search.search_message">
<codeclass="sig-prename descclassname">evennia.utils.search.</code><codeclass="sig-name descname">search_message</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">sender</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">receiver</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">freetext</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">dbref</span><spanclass="o">=</span><spanclass="default_value">None</span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#evennia.utils.search.search_message"title="Permalink to this definition">¶</a></dt>
<dd><p>Search the message database for particular messages. At least
one of the arguments must be given to do a search.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>sender</strong> (<em>Object</em><em>, </em><em>Account</em><em> or </em><em>Script</em><em>, </em><em>optional</em>) – Get messages sent by a particular sender.</p></li>
<li><p><strong>receiver</strong> (<em>Object</em><em>, </em><em>Account</em><em> or </em><em>Channel</em><em>, </em><em>optional</em>) – Get messages
received by a certain account,object or channel</p></li>
<li><p><strong>freetext</strong> (<em>str</em>) – 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.</p></li>
<li><p><strong>dbref</strong> (<em>int</em>) – The exact database id of the message. This will override
all other search criteria since it’s unique and
always gives only one match.</p></li>
</ul>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><em>Queryset</em>– Iterable with 0, 1 or more matches.</p>
</dd>
</dl>
</dd></dl>
<dlclass="py function">
<dtid="evennia.utils.search.search_channel">
<codeclass="sig-prename descclassname">evennia.utils.search.</code><codeclass="sig-name descname">search_channel</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">ostring</span></em>, <emclass="sig-param"><spanclass="n">exact</span><spanclass="o">=</span><spanclass="default_value">True</span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#evennia.utils.search.search_channel"title="Permalink to this definition">¶</a></dt>
<dd><p>Search the channel database for a particular channel.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>ostring</strong> (<em>str</em>) – The key or database id of the channel.</p></li>
<li><p><strong>exact</strong> (<em>bool</em><em>, </em><em>optional</em>) – Require an exact (but not
case sensitive) match.</p></li>
</ul>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><em>Queryset</em>– Iterable with 0, 1 or more matches.</p>
</dd>
</dl>
</dd></dl>
<dlclass="py function">
<dtid="evennia.utils.search.search_help_entry">
<codeclass="sig-prename descclassname">evennia.utils.search.</code><codeclass="sig-name descname">search_help_entry</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">ostring</span></em>, <emclass="sig-param"><spanclass="n">help_category</span><spanclass="o">=</span><spanclass="default_value">None</span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#evennia.utils.search.search_help_entry"title="Permalink to this definition">¶</a></dt>
<dd><p>Retrieve a search entry object.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>ostring</strong> (<em>str</em>) – The help topic to look for.</p></li>
<li><p><strong>category</strong> (<em>str</em>) – Limit the search to a particular help topic</p></li>
</ul>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><em>Queryset</em>– An iterable with 0, 1 or more matches.</p>
</dd>
</dl>
</dd></dl>
<dlclass="py function">
<dtid="evennia.utils.search.search_tag">
<codeclass="sig-prename descclassname">evennia.utils.search.</code><codeclass="sig-name descname">search_tag</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">key</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">category</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">tagtype</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#evennia.utils.search.search_tag"title="Permalink to this definition">¶</a></dt>
<dd><p>Find object based on tag or category.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>key</strong> (<em>str</em><em>, </em><em>optional</em>) – The tag key to search for.</p></li>
<li><p><strong>category</strong> (<em>str</em><em>, </em><em>optional</em>) – The category of tag
to search for. If not set, uncategorized
tags will be searched.</p></li>
<li><p><strong>tagtype</strong> (<em>str</em><em>, </em><em>optional</em>) –‘type’ of Tag, by default
this is either <strong>None</strong> (a normal Tag), <strong>alias</strong> or
<strong>permission</strong>. This always apply to all queried tags.</p></li>
<li><p><strong>kwargs</strong> (<em>any</em>) – Other optional parameter that may be supported
<dt>List of Objects with tags matching</dt><dd><p>the search criteria, or an empty list if no
matches were found.</p>
</dd>
</dl>
</p>
</dd>
</dl>
</dd></dl>
<dlclass="py function">
<dtid="evennia.utils.search.search_script_tag">
<codeclass="sig-prename descclassname">evennia.utils.search.</code><codeclass="sig-name descname">search_script_tag</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">key</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">category</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">tagtype</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/search.html#search_script_tag"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.search.search_script_tag"title="Permalink to this definition">¶</a></dt>
<dd><p>Find script based on tag or category.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>key</strong> (<em>str</em><em>, </em><em>optional</em>) – The tag key to search for.</p></li>
<li><p><strong>category</strong> (<em>str</em><em>, </em><em>optional</em>) – The category of tag
to search for. If not set, uncategorized
tags will be searched.</p></li>
<li><p><strong>tagtype</strong> (<em>str</em><em>, </em><em>optional</em>) –‘type’ of Tag, by default
this is either <strong>None</strong> (a normal Tag), <strong>alias</strong> or
<strong>permission</strong>. This always apply to all queried tags.</p></li>
<li><p><strong>kwargs</strong> (<em>any</em>) – Other optional parameter that may be supported
<dt>List of Scripts with tags matching</dt><dd><p>the search criteria, or an empty list if no
matches were found.</p>
</dd>
</dl>
</p>
</dd>
</dl>
</dd></dl>
<dlclass="py function">
<dtid="evennia.utils.search.search_account_tag">
<codeclass="sig-prename descclassname">evennia.utils.search.</code><codeclass="sig-name descname">search_account_tag</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">key</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">category</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">tagtype</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/search.html#search_account_tag"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.search.search_account_tag"title="Permalink to this definition">¶</a></dt>
<dd><p>Find account based on tag or category.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>key</strong> (<em>str</em><em>, </em><em>optional</em>) – The tag key to search for.</p></li>
<li><p><strong>category</strong> (<em>str</em><em>, </em><em>optional</em>) – The category of tag
to search for. If not set, uncategorized
tags will be searched.</p></li>
<li><p><strong>tagtype</strong> (<em>str</em><em>, </em><em>optional</em>) –‘type’ of Tag, by default
this is either <strong>None</strong> (a normal Tag), <strong>alias</strong> or
<strong>permission</strong>. This always apply to all queried tags.</p></li>
<li><p><strong>kwargs</strong> (<em>any</em>) – Other optional parameter that may be supported
<dt>List of Accounts with tags matching</dt><dd><p>the search criteria, or an empty list if no
matches were found.</p>
</dd>
</dl>
</p>
</dd>
</dl>
</dd></dl>
<dlclass="py function">
<dtid="evennia.utils.search.search_channel_tag">
<codeclass="sig-prename descclassname">evennia.utils.search.</code><codeclass="sig-name descname">search_channel_tag</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">key</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">category</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">tagtype</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/search.html#search_channel_tag"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.search.search_channel_tag"title="Permalink to this definition">¶</a></dt>
<dd><p>Find channel based on tag or category.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>key</strong> (<em>str</em><em>, </em><em>optional</em>) – The tag key to search for.</p></li>
<li><p><strong>category</strong> (<em>str</em><em>, </em><em>optional</em>) – The category of tag
to search for. If not set, uncategorized
tags will be searched.</p></li>
<li><p><strong>tagtype</strong> (<em>str</em><em>, </em><em>optional</em>) –‘type’ of Tag, by default
this is either <strong>None</strong> (a normal Tag), <strong>alias</strong> or
<strong>permission</strong>. This always apply to all queried tags.</p></li>
<li><p><strong>kwargs</strong> (<em>any</em>) – Other optional parameter that may be supported
<dt>List of Channels with tags matching</dt><dd><p>the search criteria, or an empty list if no
matches were found.</p>
</dd>
</dl>
</p>
</dd>
</dl>
</dd></dl>
<dlclass="py function">
<dtid="evennia.utils.search.search_typeclass">
<codeclass="sig-prename descclassname">evennia.utils.search.</code><codeclass="sig-name descname">search_typeclass</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">typeclass</span></em>, <emclass="sig-param"><spanclass="n">include_children</span><spanclass="o">=</span><spanclass="default_value">False</span></em>, <emclass="sig-param"><spanclass="n">include_parents</span><spanclass="o">=</span><spanclass="default_value">False</span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#evennia.utils.search.search_typeclass"title="Permalink to this definition">¶</a></dt>
<dd><p>Searches through all objects returning those of a certain typeclass.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>typeclass</strong> (<em>str</em><em> or </em><em>class</em>) – A typeclass class or a python path to a typeclass.</p></li>
<li><p><strong>include_children</strong> (<em>bool</em><em>, </em><em>optional</em>) – Return objects with
given typeclass <em>and</em> all children inheriting from this
typeclass. Mutuall exclusive to <strong>include_parents</strong>.</p></li>
<li><p><strong>include_parents</strong> (<em>bool</em><em>, </em><em>optional</em>) – Return objects with
given typeclass <em>and</em> all parents to this typeclass.
Mutually exclusive to <strong>include_children</strong>.</p></li>
</ul>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><em>objects (list)</em>– The objects found with the given typeclasses.</p>
