<spanid="evennia-comms-managers"></span><h1>evennia.comms.managers<aclass="headerlink"href="#module-evennia.comms.managers"title="Permalink to this headline">¶</a></h1>
<p>These managers define helper methods for accessing the database from
Comm system components.</p>
<dlclass="py exception">
<dtid="evennia.comms.managers.CommError">
<emclass="property">exception </em><codeclass="sig-prename descclassname">evennia.comms.managers.</code><codeclass="sig-name descname">CommError</code><aclass="reference internal"href="../_modules/evennia/comms/managers.html#CommError"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.comms.managers.CommError"title="Permalink to this definition">¶</a></dt>
<p>Raised by comm system, to allow feedback to player when caught.</p>
</dd></dl>
<dlclass="py function">
<dtid="evennia.comms.managers.identify_object">
<codeclass="sig-prename descclassname">evennia.comms.managers.</code><codeclass="sig-name descname">identify_object</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">inp</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/comms/managers.html#identify_object"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.comms.managers.identify_object"title="Permalink to this definition">¶</a></dt>
<dd><p>Helper function. Identifies if an object is an account or an object;
return its database model</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><p><strong>inp</strong> (<em>any</em>) – Entity to be idtified.</p>
<dt>This is a tuple with (<strong>inp</strong>, identifier)</dt><dd><p>where <strong>identifier</strong> is one of “account”, “object”, “channel”,
“string”, “dbref” or None.</p>
</dd>
</dl>
</p>
</dd>
</dl>
</dd></dl>
<dlclass="py function">
<dtid="evennia.comms.managers.to_object">
<codeclass="sig-prename descclassname">evennia.comms.managers.</code><codeclass="sig-name descname">to_object</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">inp</span></em>, <emclass="sig-param"><spanclass="n">objtype</span><spanclass="o">=</span><spanclass="default_value">'account'</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/comms/managers.html#to_object"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.comms.managers.to_object"title="Permalink to this definition">¶</a></dt>
<dd><p>Locates the object related to the given accountname or channel key.
If input was already the correct object, return it.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>inp</strong> (<em>any</em>) – The input object/string</p></li>
<li><p><strong>objtype</strong> (<em>str</em>) – Either ‘account’ or ‘channel’.</p></li>
</ul>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><em>obj (object)</em>– The correct object related to <strong>inp</strong>.</p>
</dd>
</dl>
</dd></dl>
<dlclass="py class">
<dtid="evennia.comms.managers.MsgManager">
<emclass="property">class </em><codeclass="sig-prename descclassname">evennia.comms.managers.</code><codeclass="sig-name descname">MsgManager</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">*</span><spanclass="n">args</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/comms/managers.html#MsgManager"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.comms.managers.MsgManager"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">identify_object</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">inp</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/comms/managers.html#MsgManager.identify_object"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.comms.managers.MsgManager.identify_object"title="Permalink to this definition">¶</a></dt>
<dd><p>Wrapper to identify_object if accessing via the manager directly.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><p><strong>inp</strong> (<em>any</em>) – Entity to be idtified.</p>
<codeclass="sig-name descname">get_message_by_id</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">idnum</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/comms/managers.html#MsgManager.get_message_by_id"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.comms.managers.MsgManager.get_message_by_id"title="Permalink to this definition">¶</a></dt>
<dd><p>Retrieve message by its id.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><p><strong>idnum</strong> (<em>int</em><em> or </em><em>str</em>) – The dbref to retrieve.</p>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><em>message (Msg)</em>– The message.</p>
<codeclass="sig-name descname">get_messages_by_sender</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">sender</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/comms/managers.html#MsgManager.get_messages_by_sender"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.comms.managers.MsgManager.get_messages_by_sender"title="Permalink to this definition">¶</a></dt>
<dd><p>Get all messages sent by one entity - this could be either a
account or an object</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><p><strong>sender</strong> (<em>Account</em><em> or </em><em>Object</em>) – The sender of the message.</p>
<codeclass="sig-name descname">get_messages_by_receiver</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">recipient</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/comms/managers.html#MsgManager.get_messages_by_receiver"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.comms.managers.MsgManager.get_messages_by_receiver"title="Permalink to this definition">¶</a></dt>
<dd><p>Get all messages sent to one given recipient.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><p><strong>recipient</strong> (<em>Object</em><em>, </em><em>Account</em><em> or </em><em>Channel</em>) – The recipient of the messages to search for.</p>
<ddclass="field-odd"><p><aclass="reference internal"href="#evennia.comms.managers.CommError"title="evennia.comms.managers.CommError"><strong>CommError</strong></a>– If the <strong>recipient</strong> is not of a valid type.</p>
<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="reference internal"href="../_modules/evennia/comms/managers.html#MsgManager.search_message"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.comms.managers.MsgManager.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>
<codeclass="sig-name descname">message_search</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.comms.managers.MsgManager.message_search"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>
<codeclass="sig-name descname">create_message</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">senderobj</span></em>, <emclass="sig-param"><spanclass="n">message</span></em>, <emclass="sig-param"><spanclass="n">receivers</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">locks</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">tags</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">header</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/comms/managers.html#MsgManager.create_message"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.comms.managers.MsgManager.create_message"title="Permalink to this definition">¶</a></dt>
<dd><p>Create a new communication Msg. Msgs represent a unit of
database-persistent communication between entites.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>senderobj</strong> (<em>Object</em><em>, </em><em>Account</em><em>, </em><em>Script</em><em>, </em><em>str</em><em> or </em><em>list</em>) – The entity (or
entities) sending the Msg. If a <strong>str</strong>, this is the id-string
for an external sender type.</p></li>
<li><p><strong>message</strong> (<em>str</em>) – Text with the message. Eventual headers, titles
etc should all be included in this text string. Formatting
will be retained.</p></li>
<li><p><strong>receivers</strong> (<em>Object</em><em>, </em><em>Account</em><em>, </em><em>Script</em><em>, </em><em>str</em><em> or </em><em>list</em>) – An Account/Object to send
to, or a list of them. If a string, it’s an identifier for an external
<li><p><strong>header</strong> (<em>str</em>) – Mime-type or other optional information for the message</p></li>
</ul>
</dd>
</dl>
<pclass="rubric">Notes</p>
<p>The Comm system is created to be very open-ended, so it’s fully
possible to let a message both go several receivers at the same time,
it’s up to the command definitions to limit this as desired.</p>
</dd></dl>
</dd></dl>
<dlclass="py class">
<dtid="evennia.comms.managers.ChannelDBManager">
<emclass="property">class </em><codeclass="sig-prename descclassname">evennia.comms.managers.</code><codeclass="sig-name descname">ChannelDBManager</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">*</span><spanclass="n">args</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/comms/managers.html#ChannelDBManager"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.comms.managers.ChannelDBManager"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">get_all_channels</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/comms/managers.html#ChannelDBManager.get_all_channels"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.comms.managers.ChannelDBManager.get_all_channels"title="Permalink to this definition">¶</a></dt>
<dd><p>Get all channels.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Returns</dt>
<ddclass="field-odd"><p><em>channels (list)</em>– All channels in game.</p>
<codeclass="sig-name descname">get_channel</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">channelkey</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/comms/managers.html#ChannelDBManager.get_channel"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.comms.managers.ChannelDBManager.get_channel"title="Permalink to this definition">¶</a></dt>
<dd><p>Return the channel object if given its key.
Also searches its aliases.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><p><strong>channelkey</strong> (<em>str</em>) – Channel key to search for.</p>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><em>channel (Channel or None)</em>– A channel match.</p>
<codeclass="sig-name descname">get_subscriptions</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">subscriber</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/comms/managers.html#ChannelDBManager.get_subscriptions"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.comms.managers.ChannelDBManager.get_subscriptions"title="Permalink to this definition">¶</a></dt>
<dd><p>Return all channels a given entity is subscribed to.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><p><strong>subscriber</strong> (<em>Object</em><em> or </em><em>Account</em>) – The one subscribing.</p>
<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="reference internal"href="../_modules/evennia/comms/managers.html#ChannelDBManager.search_channel"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.comms.managers.ChannelDBManager.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>
<li><p><strong>tags</strong> (<aclass="reference internal"href="evennia.contrib.game_systems.barter.barter.html#evennia.contrib.game_systems.barter.barter.TradeHandler.list"title="evennia.contrib.game_systems.barter.barter.TradeHandler.list"><em>list</em></a>) – A list of tags or tuples <strong>(tag[,category[,data]])</strong>.</p></li>
<li><p><strong>attrs</strong> (<aclass="reference internal"href="evennia.contrib.game_systems.barter.barter.html#evennia.contrib.game_systems.barter.barter.TradeHandler.list"title="evennia.contrib.game_systems.barter.barter.TradeHandler.list"><em>list</em></a>) – List of attributes on form <strong>(name, value[,category[,lockstring]])</strong></p></li>
<codeclass="sig-name descname">channel_search</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.comms.managers.ChannelDBManager.channel_search"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>
</dd></dl>
<dlclass="py class">
<dtid="evennia.comms.managers.ChannelManager">
<emclass="property">class </em><codeclass="sig-prename descclassname">evennia.comms.managers.</code><codeclass="sig-name descname">ChannelManager</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">*</span><spanclass="n">args</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/comms/managers.html#ChannelManager"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.comms.managers.ChannelManager"title="Permalink to this definition">¶</a></dt>
