mirror of
https://github.com/evennia/evennia.git
synced 2026-03-28 10:37:16 +01:00
Updated HTML docs
This commit is contained in:
Evennia docbuilder action
parent
bd82579bfa
commit
70b4caedb6
105 changed files with 2389 additions and 2138 deletions
|
|
@ -56,22 +56,35 @@
|
|||
</div>
|
||||
</div>
|
||||
<div class="literal-block-wrapper docutils container" id="id2">
|
||||
<div class="code-block-caption"><span class="caption-text">In-code</span><a class="headerlink" href="#id2" title="Permalink to this code">¶</a></div>
|
||||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">obj</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">foo</span> <span class="o">=</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span> <span class="s2">"bar"</span><span class="p">]</span>
|
||||
<div class="code-block-caption"><span class="caption-text">In-code, using the .db wrapper</span><a class="headerlink" href="#id2" title="Permalink to this code">¶</a></div>
|
||||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">obj</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">foo</span> <span class="o">=</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="s2">"bar"</span><span class="p">]</span>
|
||||
<span class="n">value</span> <span class="o">=</span> <span class="n">obj</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">foo</span>
|
||||
|
||||
<span class="n">obj</span><span class="o">.</span><span class="n">attributes</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">"myattr"</span><span class="p">,</span> <span class="mi">1234</span><span class="p">,</span> <span class="n">category</span><span class="o">=</span><span class="s2">"bar"</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="literal-block-wrapper docutils container" id="id3">
|
||||
<div class="code-block-caption"><span class="caption-text">In-code, using the .attributes handler</span><a class="headerlink" href="#id3" title="Permalink to this code">¶</a></div>
|
||||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">obj</span><span class="o">.</span><span class="n">attributes</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">"myattr"</span><span class="p">,</span> <span class="mi">1234</span><span class="p">,</span> <span class="n">category</span><span class="o">=</span><span class="s2">"bar"</span><span class="p">)</span>
|
||||
<span class="n">value</span> <span class="o">=</span> <span class="n">attributes</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">"myattr"</span><span class="p">,</span> <span class="n">category</span><span class="o">=</span><span class="s2">"bar"</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</div>
|
||||
<p><em>Attributes</em> allow you to to store arbitrary data on objects and make sure the data survives a
|
||||
server reboot. An Attribute can store pretty much any
|
||||
<div class="literal-block-wrapper docutils container" id="id4">
|
||||
<div class="code-block-caption"><span class="caption-text">In-code, using <code class="docutils literal notranslate"><span class="pre">AttributeProperty</span></code> at class level</span><a class="headerlink" href="#id4" title="Permalink to this code">¶</a></div>
|
||||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">evennia</span> <span class="kn">import</span> <span class="n">DefaultObject</span>
|
||||
<span class="kn">from</span> <span class="nn">evennia</span> <span class="kn">import</span> <span class="n">AttributeProperty</span>
|
||||
|
||||
<span class="k">class</span> <span class="nc">MyObject</span><span class="p">(</span><span class="n">DefaultObject</span><span class="p">):</span>
|
||||
<span class="n">foo</span> <span class="o">=</span> <span class="n">AttributeProperty</span><span class="p">(</span><span class="n">default</span><span class="o">=</span><span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="s2">"bar"</span><span class="p">])</span>
|
||||
<span class="n">myattr</span> <span class="o">=</span> <span class="n">AttributeProperty</span><span class="p">(</span><span class="mi">100</span><span class="p">,</span> <span class="n">category</span><span class="o">=</span><span class="s1">'bar'</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</div>
|
||||
<p><em>Attributes</em> allow you to to store arbitrary data on objects and make sure the data survives a server reboot. An Attribute can store pretty much any
|
||||
Python data structure and data type, like numbers, strings, lists, dicts etc. You can also
|
||||
store (references to) database objects like characters and rooms.</p>
|
||||
<ul class="simple">
|
||||
<li><p><a class="reference internal" href="#what-types-of-data-can-i-save-in-an-attribute"><span class="std std-doc">What can be stored in an Attribute</span></a> is a must-read
|
||||
also for experienced developers, to avoid getting surprised. Attributes can store <em>almost</em> everything
|
||||
<li><p><a class="reference internal" href="#what-types-of-data-can-i-save-in-an-attribute"><span class="std std-doc">What can be stored in an Attribute</span></a> is a must-read to avoid being surprised, also for experienced developers. Attributes can store <em>almost</em> everything
|
||||
but you need to know the quirks.</p></li>
|
||||
<li><p><a class="reference internal" href="#in-memory-attributes-nattributes"><span class="std std-doc">NAttributes</span></a> are the in-memory, non-persistent
|
||||
siblings of Attributes.</p></li>
|
||||
|
|
@ -81,7 +94,7 @@ siblings of Attributes.</p></li>
|
|||
<h2>Managing Attributes in Code<a class="headerlink" href="#managing-attributes-in-code" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Attributes are usually handled in code. All <a class="reference internal" href="Typeclasses.html"><span class="doc std std-doc">Typeclassed</span></a> entities
|
||||
(<a class="reference internal" href="Accounts.html"><span class="doc std std-doc">Accounts</span></a>, <a class="reference internal" href="Objects.html"><span class="doc std std-doc">Objects</span></a>, <a class="reference internal" href="Scripts.html"><span class="doc std std-doc">Scripts</span></a> and
|
||||
<a class="reference internal" href="Channels.html"><span class="doc std std-doc">Channels</span></a>) all can (and usually do) have Attributes associated with them. There
|
||||
<a class="reference internal" href="Channels.html"><span class="doc std std-doc">Channels</span></a>) can (and usually do) have Attributes associated with them. There
|
||||
are three ways to manage Attributes, all of which can be mixed.</p>
|
||||
<ul class="simple">
|
||||
<li><p><a class="reference internal" href="#using-db"><span class="std std-doc">Using the <code class="docutils literal notranslate"><span class="pre">.db</span></code> property shortcut</span></a></p></li>
|
||||
|
|
@ -90,8 +103,8 @@ are three ways to manage Attributes, all of which can be mixed.</p>
|
|||
</ul>
|
||||
<section id="using-db">
|
||||
<h3>Using .db<a class="headerlink" href="#using-db" title="Permalink to this headline">¶</a></h3>
|
||||
<p>The simplest way to get/set Attributes is to use the <code class="docutils literal notranslate"><span class="pre">.db</span></code> shortcut:</p>
|
||||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">evennia</span>
|
||||
<p>The simplest way to get/set Attributes is to use the <code class="docutils literal notranslate"><span class="pre">.db</span></code> shortcut. This allows for setting and getting Attributes that lack a <em>category</em> (having category <code class="docutils literal notranslate"><span class="pre">None</span></code>)</p>
|
||||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">evennia</span>
|
||||
|
||||
<span class="n">obj</span> <span class="o">=</span> <span class="n">evennia</span><span class="o">.</span><span class="n">create_object</span><span class="p">(</span><span class="n">key</span><span class="o">=</span><span class="s2">"Foo"</span><span class="p">)</span>
|
||||
|
||||
|
|
@ -104,10 +117,10 @@ are three ways to manage Attributes, all of which can be mixed.</p>
|
|||
<span class="n">rose</span> <span class="o">=</span> <span class="n">evennia</span><span class="o">.</span><span class="n">search_object</span><span class="p">(</span><span class="n">key</span><span class="o">=</span><span class="s2">"rose"</span><span class="p">)[</span><span class="mi">0</span><span class="p">]</span> <span class="c1"># returns a list, grab 0th element</span>
|
||||
<span class="n">rose</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">has_thorns</span> <span class="o">=</span> <span class="kc">True</span>
|
||||
|
||||
<span class="c1"># retrieving </span>
|
||||
<span class="c1"># retrieving</span>
|
||||
<span class="n">val1</span> <span class="o">=</span> <span class="n">obj</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">foo1</span>
|
||||
<span class="n">val2</span> <span class="o">=</span> <span class="n">obj</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">foo2</span>
|
||||
<span class="n">weap</span> <span class="o">=</span> <span class="n">obj</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">weapon</span>
|
||||
<span class="n">weap</span> <span class="o">=</span> <span class="n">obj</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">weapon</span>
|
||||
<span class="n">myself</span> <span class="o">=</span> <span class="n">obj</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">self_reference</span> <span class="c1"># retrieve reference from db, get object back</span>
|
||||
|
||||
<span class="n">is_ouch</span> <span class="o">=</span> <span class="n">rose</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">has_thorns</span>
|
||||
|
|
@ -115,8 +128,8 @@ are three ways to manage Attributes, all of which can be mixed.</p>
|
|||
<span class="c1"># this will return None, not AttributeError!</span>
|
||||
<span class="n">not_found</span> <span class="o">=</span> <span class="n">obj</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">jiwjpowiwwerw</span>
|
||||
|
||||
<span class="c1"># returns all Attributes on the object </span>
|
||||
<span class="n">obj</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">all</span>
|
||||
<span class="c1"># returns all Attributes on the object</span>
|
||||
<span class="n">obj</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">all</span>
|
||||
|
||||
<span class="c1"># delete an Attribute</span>
|
||||
<span class="k">del</span> <span class="n">obj</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">foo2</span>
|
||||
|
|
@ -129,11 +142,10 @@ default <code class="docutils literal notranslate"><span class="pre">all</span><
|
|||
</section>
|
||||
<section id="using-attributes">
|
||||
<h3>Using .attributes<a class="headerlink" href="#using-attributes" title="Permalink to this headline">¶</a></h3>
|
||||
<p>If you don’t know the name of the Attribute beforehand you can also use
|
||||
the <code class="docutils literal notranslate"><span class="pre">AttributeHandler</span></code>, available as <code class="docutils literal notranslate"><span class="pre">.attributes</span></code>. With no extra keywords this is identical
|
||||
to using the <code class="docutils literal notranslate"><span class="pre">.db</span></code> shortcut (<code class="docutils literal notranslate"><span class="pre">.db</span></code> is actually using the <code class="docutils literal notranslate"><span class="pre">AttributeHandler</span></code> internally):</p>
|
||||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">is_ouch</span> <span class="o">=</span> <span class="n">rose</span><span class="o">.</span><span class="n">attributes</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">"has_thorns"</span><span class="p">)</span>
|
||||
|
||||
<p>If you want to group your Attribute in a category, or don’t know the name of the Attribute beforehand, you can make use of
|
||||
the <a class="reference internal" href="../api/evennia.typeclasses.attributes.html#evennia.typeclasses.attributes.AttributeHandler" title="evennia.typeclasses.attributes.AttributeHandler"><span class="xref myst py py-class">AttributeHandler</span></a>, available as <code class="docutils literal notranslate"><span class="pre">.attributes</span></code> on all typeclassed entities. With no extra keywords, this is identical to using the <code class="docutils literal notranslate"><span class="pre">.db</span></code> shortcut (<code class="docutils literal notranslate"><span class="pre">.db</span></code> is actually using the <code class="docutils literal notranslate"><span class="pre">AttributeHandler</span></code> internally):</p>
|
||||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">is_ouch</span> <span class="o">=</span> <span class="n">rose</span><span class="o">.</span><span class="n">attributes</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">"has_thorns"</span><span class="p">)</span>
|
||||
|
||||
<span class="n">obj</span><span class="o">.</span><span class="n">attributes</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">"helmet"</span><span class="p">,</span> <span class="s2">"Knight's helmet"</span><span class="p">)</span>
|
||||
<span class="n">helmet</span> <span class="o">=</span> <span class="n">obj</span><span class="o">.</span><span class="n">attributes</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">"helmet"</span><span class="p">)</span>
|
||||
|
||||
|
|
@ -141,8 +153,7 @@ to using the <code class="docutils literal notranslate"><span class="pre">.db</s
|
|||
<span class="n">obj</span><span class="o">.</span><span class="n">attributes</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">"my game log"</span><span class="p">,</span> <span class="s2">"long text about ..."</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>With the <code class="docutils literal notranslate"><span class="pre">AttributeHandler</span></code> you can also give Attributes a <code class="docutils literal notranslate"><span class="pre">category</span></code>. By using a category you can
|
||||
separate same-named Attributes on the same object which can help organization:</p>
|
||||
<p>By using a category you can separate same-named Attributes on the same object to help organization.</p>
|
||||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># store (let's say we have gold_necklace and ringmail_armor from before)</span>
|
||||
<span class="n">obj</span><span class="o">.</span><span class="n">attributes</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">"neck"</span><span class="p">,</span> <span class="n">gold_necklace</span><span class="p">,</span> <span class="n">category</span><span class="o">=</span><span class="s2">"clothing"</span><span class="p">)</span>
|
||||
<span class="n">obj</span><span class="o">.</span><span class="n">attributes</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">"neck"</span><span class="p">,</span> <span class="n">ringmail_armor</span><span class="p">,</span> <span class="n">category</span><span class="o">=</span><span class="s2">"armor"</span><span class="p">)</span>
|
||||
|
|
@ -152,12 +163,7 @@ separate same-named Attributes on the same object which can help organization:</
|
|||
<span class="n">neck_armor</span> <span class="o">=</span> <span class="n">obj</span><span class="o">.</span><span class="n">attributes</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">"neck"</span><span class="p">,</span> <span class="n">category</span><span class="o">=</span><span class="s2">"armor"</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>If you don’t specify a category, the Attribute’s <code class="docutils literal notranslate"><span class="pre">category</span></code> will be <code class="docutils literal notranslate"><span class="pre">None</span></code>. Note that
|
||||
<code class="docutils literal notranslate"><span class="pre">None</span></code> is also considered a category of its own, so you won’t find <code class="docutils literal notranslate"><span class="pre">None</span></code>-category Attributes mixed
|
||||
with Attributes having categories.</p>
|
||||
<blockquote>
|
||||
<div><p>When using <code class="docutils literal notranslate"><span class="pre">.db</span></code>, you will always use the <code class="docutils literal notranslate"><span class="pre">None</span></code> category.</p>
|
||||
</div></blockquote>
|
||||
<p>If you don’t specify a category, the Attribute’s <code class="docutils literal notranslate"><span class="pre">category</span></code> will be <code class="docutils literal notranslate"><span class="pre">None</span></code> and can thus also be found via <code class="docutils literal notranslate"><span class="pre">.db</span></code>. <code class="docutils literal notranslate"><span class="pre">None</span></code> is considered a category of its own, so you won’t find <code class="docutils literal notranslate"><span class="pre">None</span></code>-category Attributes mixed with Attributes having categories.</p>
|
||||
<p>Here are the methods of the <code class="docutils literal notranslate"><span class="pre">AttributeHandler</span></code>. See
|
||||
the <a class="reference internal" href="../api/evennia.typeclasses.attributes.html#evennia.typeclasses.attributes.AttributeHandler" title="evennia.typeclasses.attributes.AttributeHandler"><span class="xref myst py py-class">AttributeHandler API</span></a> for more details.</p>
|
||||
<ul class="simple">
|
||||
|
|
@ -178,28 +184,27 @@ before performing the deletion. - <code class="docutils literal notranslate"><s
|
|||
</ul>
|
||||
<p>Examples:</p>
|
||||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">try</span><span class="p">:</span>
|
||||
<span class="c1"># raise error if Attribute foo does not exist </span>
|
||||
<span class="c1"># raise error if Attribute foo does not exist</span>
|
||||
<span class="n">val</span> <span class="o">=</span> <span class="n">obj</span><span class="o">.</span><span class="n">attributes</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">"foo"</span><span class="p">,</span> <span class="n">raise_exception</span><span class="o">=</span><span class="kc">True</span><span class="p">):</span>
|
||||
<span class="k">except</span> <span class="ne">AttributeError</span><span class="p">:</span>
|
||||
<span class="c1"># ...</span>
|
||||
|
||||
|
||||
<span class="c1"># return default value if foo2 doesn't exist</span>
|
||||
<span class="n">val2</span> <span class="o">=</span> <span class="n">obj</span><span class="o">.</span><span class="n">attributes</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">"foo2"</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="s2">"bar"</span><span class="p">])</span>
|
||||
<span class="n">val2</span> <span class="o">=</span> <span class="n">obj</span><span class="o">.</span><span class="n">attributes</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">"foo2"</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="s2">"bar"</span><span class="p">])</span>
|
||||
|
||||
<span class="c1"># delete foo if it exists (will silently fail if unset, unless</span>
|
||||
<span class="c1"># raise_exception is set)</span>
|
||||
<span class="n">obj</span><span class="o">.</span><span class="n">attributes</span><span class="o">.</span><span class="n">remove</span><span class="p">(</span><span class="s2">"foo"</span><span class="p">)</span>
|
||||
|
||||
|
||||
<span class="c1"># view all clothes on obj</span>
|
||||
<span class="n">all_clothes</span> <span class="o">=</span> <span class="n">obj</span><span class="o">.</span><span class="n">attributes</span><span class="o">.</span><span class="n">all</span><span class="p">(</span><span class="n">category</span><span class="o">=</span><span class="s2">"clothes"</span><span class="p">)</span>
|
||||
<span class="n">all_clothes</span> <span class="o">=</span> <span class="n">obj</span><span class="o">.</span><span class="n">attributes</span><span class="o">.</span><span class="n">all</span><span class="p">(</span><span class="n">category</span><span class="o">=</span><span class="s2">"clothes"</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</section>
|
||||
<section id="using-attributeproperty">
|
||||
<h3>Using AttributeProperty<a class="headerlink" href="#using-attributeproperty" title="Permalink to this headline">¶</a></h3>
|
||||
<p>There is a third way to set up an Attribute, and that is by setting up an <code class="docutils literal notranslate"><span class="pre">AttributeProperty</span></code>. This
|
||||
is done on the <em>class level</em> of your typeclass and allows you to treat Attributes a bit like Django
|
||||
database Fields.</p>
|
||||
<p>The third way to set up an Attribute is to use an <code class="docutils literal notranslate"><span class="pre">AttributeProperty</span></code>. This
|
||||
is done on the <em>class level</em> of your typeclass and allows you to treat Attributes a bit like Django database Fields. Unlike using <code class="docutils literal notranslate"><span class="pre">.db</span></code> and <code class="docutils literal notranslate"><span class="pre">.attributes</span></code>, an <code class="docutils literal notranslate"><span class="pre">AttributeProperty</span></code> can’t be created on the fly, you must assign it in the class code.</p>
|
||||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># mygame/typeclasses/characters.py</span>
|
||||
|
||||
<span class="kn">from</span> <span class="nn">evennia</span> <span class="kn">import</span> <span class="n">DefaultCharacter</span>
|
||||
|
|
@ -207,126 +212,55 @@ database Fields.</p>
|
|||
|
||||
<span class="k">class</span> <span class="nc">Character</span><span class="p">(</span><span class="n">DefaultCharacter</span><span class="p">):</span>
|
||||
|
||||
<span class="n">strength</span> <span class="o">=</span> <span class="n">AttributeProperty</span><span class="p">(</span><span class="n">default</span><span class="o">=</span><span class="mi">10</span><span class="p">,</span> <span class="n">category</span><span class="o">=</span><span class="s1">'stat'</span><span class="p">,</span> <span class="n">autocreate</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
|
||||
<span class="n">constitution</span> <span class="o">=</span> <span class="n">AttributeProperty</span><span class="p">(</span><span class="n">default</span><span class="o">=</span><span class="mi">10</span><span class="p">,</span> <span class="n">category</span><span class="o">=</span><span class="s1">'stat'</span><span class="p">,</span> <span class="n">autocreate</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
|
||||
<span class="n">agility</span> <span class="o">=</span> <span class="n">AttributeProperty</span><span class="p">(</span><span class="n">default</span><span class="o">=</span><span class="mi">10</span><span class="p">,</span> <span class="n">category</span><span class="o">=</span><span class="s1">'stat'</span><span class="p">,</span> <span class="n">autocreate</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
|
||||
<span class="n">magic</span> <span class="o">=</span> <span class="n">AttributeProperty</span><span class="p">(</span><span class="n">default</span><span class="o">=</span><span class="mi">10</span><span class="p">,</span> <span class="n">category</span><span class="o">=</span><span class="s1">'stat'</span><span class="p">,</span> <span class="n">autocreate</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
|
||||
|
||||
<span class="n">sleepy</span> <span class="o">=</span> <span class="n">AttributeProperty</span><span class="p">(</span><span class="n">default</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
|
||||
<span class="n">poisoned</span> <span class="o">=</span> <span class="n">AttributeProperty</span><span class="p">(</span><span class="n">default</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
|
||||
|
||||
<span class="k">def</span> <span class="nf">at_object_creation</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
|
||||
<span class="c1"># ... </span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>These “Attribute-properties” will be made available to all instances of the class.</p>
|
||||
<div class="admonition important">
|
||||
<p class="admonition-title">Important</p>
|
||||
<p>If you change the <code class="docutils literal notranslate"><span class="pre">default</span></code> of an <code class="docutils literal notranslate"><span class="pre">AttributeProperty</span></code> (and reload), it will
|
||||
change the default for <em>all</em> instances of that class (it will not override
|
||||
explicitly changed values).</p>
|
||||
</div>
|
||||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">char</span> <span class="o">=</span> <span class="n">evennia</span><span class="o">.</span><span class="n">search_object</span><span class="p">(</span><span class="n">Character</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="s2">"Bob"</span><span class="p">)[</span><span class="mi">0</span><span class="p">]</span> <span class="c1"># returns list, get 0th element</span>
|
||||
|
||||
<span class="c1"># get defaults </span>
|
||||
<span class="n">strength</span> <span class="o">=</span> <span class="n">char</span><span class="o">.</span><span class="n">strength</span> <span class="c1"># will get the default value 10</span>
|
||||
|
||||
<span class="c1"># assign new values (this will create/update new Attributes)</span>
|
||||
<span class="n">char</span><span class="o">.</span><span class="n">strength</span> <span class="o">=</span> <span class="mi">12</span>
|
||||
<span class="n">char</span><span class="o">.</span><span class="n">constitution</span> <span class="o">=</span> <span class="mi">16</span>
|
||||
<span class="n">char</span><span class="o">.</span><span class="n">agility</span> <span class="o">=</span> <span class="mi">8</span>
|
||||
<span class="n">char</span><span class="o">.</span><span class="n">magic</span> <span class="o">=</span> <span class="mi">2</span>
|
||||
|
||||
<span class="c1"># you can also do arithmetic etc </span>
|
||||
<span class="n">char</span><span class="o">.</span><span class="n">magic</span> <span class="o">+=</span> <span class="mi">2</span> <span class="c1"># char.magic is now 4</span>
|
||||
|
||||
<span class="c1"># check Attributes </span>
|
||||
<span class="n">strength</span> <span class="o">=</span> <span class="n">char</span><span class="o">.</span><span class="n">strength</span> <span class="c1"># this is now 12</span>
|
||||
<span class="n">is_sleepy</span> <span class="o">=</span> <span class="n">char</span><span class="o">.</span><span class="n">sleepy</span>
|
||||
<span class="n">is_poisoned</span> <span class="o">=</span> <span class="n">char</span><span class="o">.</span><span class="n">poisoned</span>
|
||||
|
||||
<span class="k">del</span> <span class="n">char</span><span class="o">.</span><span class="n">strength</span> <span class="c1"># wipes the Attribute</span>
|
||||
<span class="n">strength</span> <span class="o">=</span> <span class="n">char</span><span class="o">.</span><span class="n">strengh</span> <span class="c1"># back to the default (10) again</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>See the <a class="reference internal" href="../api/evennia.typeclasses.attributes.html#evennia.typeclasses.attributes.AttributeProperty" title="evennia.typeclasses.attributes.AttributeProperty"><span class="xref myst py py-class">AttributeProperty</span></a> docs for more
|
||||
details on arguments.</p>
|
||||
<p>An <code class="docutils literal notranslate"><span class="pre">AttributeProperty</span></code> will <em>not</em> create an <code class="docutils literal notranslate"><span class="pre">Attribute</span></code> by default. A new <code class="docutils literal notranslate"><span class="pre">Attribute</span></code> will be created
|
||||
(or an existing one retrieved/updated) will happen differently depending on how the <code class="docutils literal notranslate"><span class="pre">autocreate</span></code>
|
||||
keyword:</p>
|
||||
<ul class="simple">
|
||||
<li><p>If <code class="docutils literal notranslate"><span class="pre">autocreate=False</span></code> (default), an <code class="docutils literal notranslate"><span class="pre">Attribute</span></code> will be created only if the field is explicitly
|
||||
assigned a value (even if the value is the same as the default, such as <code class="docutils literal notranslate"><span class="pre">char.strength</span> <span class="pre">=</span> <span class="pre">10</span></code>).</p></li>
|
||||
<li><p>If <code class="docutils literal notranslate"><span class="pre">autocreate=True</span></code>, an <code class="docutils literal notranslate"><span class="pre">Attribute</span></code> will be created as soon as the field is <em>accessed</em> in
|
||||
any way (So both <code class="docutils literal notranslate"><span class="pre">strength</span> <span class="pre">=</span> <span class="pre">char.strength</span></code> and <code class="docutils literal notranslate"><span class="pre">char.strength</span> <span class="pre">=</span> <span class="pre">10</span></code> will both make sure that
|
||||
an <code class="docutils literal notranslate"><span class="pre">Attribute</span></code> exists.</p></li>
|
||||
</ul>
|
||||
<p>Example:</p>
|
||||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># in mygame/typeclasses/objects.py </span>
|
||||
|
||||
<span class="kn">from</span> <span class="nn">evennia</span> <span class="kn">import</span> <span class="n">create_object</span>
|
||||
<span class="kn">from</span> <span class="nn">evennia</span> <span class="kn">import</span> <span class="n">DefaultObject</span>
|
||||
<span class="kn">from</span> <span class="nn">evennia.typeclasses.attributes</span> <span class="kn">import</span> <span class="n">AttributeProperty</span>
|
||||
|
||||
<span class="k">class</span> <span class="nc">Object</span><span class="p">(</span><span class="n">DefaultObject</span><span class="p">):</span>
|
||||
|
||||
<span class="n">value_a</span> <span class="o">=</span> <span class="n">AttributeProperty</span><span class="p">(</span><span class="n">default</span><span class="o">=</span><span class="s2">"foo"</span><span class="p">)</span>
|
||||
<span class="n">value_b</span> <span class="o">=</span> <span class="n">AttributeProperty</span><span class="p">(</span><span class="n">default</span><span class="o">=</span><span class="s2">"bar"</span><span class="p">,</span> <span class="n">autocreate</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
|
||||
|
||||
<span class="n">obj</span> <span class="o">=</span> <span class="n">evennia</span><span class="o">.</span><span class="n">create_object</span><span class="p">(</span><span class="n">key</span><span class="o">=</span><span class="s2">"Dummy"</span><span class="p">)</span>
|
||||
|
||||
<span class="c1"># these will find NO Attributes! </span>
|
||||
<span class="n">obj</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">value_a</span>
|
||||
<span class="n">obj</span><span class="o">.</span><span class="n">attributes</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">"value_a"</span><span class="p">)</span>
|
||||
<span class="n">obj</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">value_b</span>
|
||||
<span class="n">obj</span><span class="o">.</span><span class="n">attributes</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">"value_b"</span><span class="p">)</span>
|
||||
|
||||
<span class="c1"># get data from attribute-properties</span>
|
||||
<span class="n">vala</span> <span class="o">=</span> <span class="n">obj</span><span class="o">.</span><span class="n">value_a</span> <span class="c1"># returns "foo"</span>
|
||||
<span class="n">valb</span> <span class="o">=</span> <span class="n">obj</span><span class="o">.</span><span class="n">value_b</span> <span class="c1"># return "bar" AND creates the Attribute (autocreate)</span>
|
||||
|
||||
<span class="c1"># the autocreate property will now be found </span>
|
||||
<span class="n">obj</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">value_a</span> <span class="c1"># still not found </span>
|
||||
<span class="n">obj</span><span class="o">.</span><span class="n">attributes</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">"value_a"</span><span class="p">)</span> <span class="c1"># ''</span>
|
||||
<span class="n">obj</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">value_b</span> <span class="c1"># now returns "bar" </span>
|
||||
<span class="n">obj</span><span class="o">.</span><span class="n">attributes</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">"value_b"</span><span class="p">)</span> <span class="c1"># ''</span>
|
||||
|
||||
<span class="c1"># assign new values </span>
|
||||
<span class="n">obj</span><span class="o">.</span><span class="n">value_a</span> <span class="o">=</span> <span class="mi">10</span> <span class="c1"># will now create a new Attribute </span>
|
||||
<span class="n">obj</span><span class="o">.</span><span class="n">value_b</span> <span class="o">=</span> <span class="mi">12</span> <span class="c1"># will update the existing Attribute </span>
|
||||
|
||||
<span class="c1"># both are now found as Attributes </span>
|
||||
<span class="n">obj</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">value_a</span> <span class="c1"># now returns 10</span>
|
||||
<span class="n">obj</span><span class="o">.</span><span class="n">attributes</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">"value_a"</span><span class="p">)</span> <span class="c1"># ''</span>
|
||||
<span class="n">obj</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">value_b</span> <span class="c1"># now returns 12</span>
|
||||
<span class="n">obj</span><span class="o">.</span><span class="n">attributes</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">"value_b"</span><span class="p">)</span> <span class="c1"># ''</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>If you always access your Attributes via the <code class="docutils literal notranslate"><span class="pre">AttributeProperty</span></code> this does not matter that much
|
||||
(it’s also a bit of an optimization to not create an actual database <code class="docutils literal notranslate"><span class="pre">Attribute</span></code> unless the value changed).
|
||||
But until an <code class="docutils literal notranslate"><span class="pre">Attribute</span></code> has been created, <code class="docutils literal notranslate"><span class="pre">AttributeProperty</span></code> fields will <em>not</em> show up with the
|
||||
<code class="docutils literal notranslate"><span class="pre">examine</span></code> command or by using the <code class="docutils literal notranslate"><span class="pre">.db</span></code> or <code class="docutils literal notranslate"><span class="pre">.attributes</span></code> handlers - so this is a bit inconsistent.
|
||||
If this is important, you need to ‘initialize’ them by accessing them at least once … something
|
||||
like this:</p>
|
||||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># ... </span>
|
||||
<span class="k">class</span> <span class="nc">Character</span><span class="p">(</span><span class="n">DefaultCharacter</span><span class="p">):</span>
|
||||
|
||||
<span class="n">strength</span> <span class="o">=</span> <span class="n">AttributeProperty</span><span class="p">(</span><span class="mi">12</span><span class="p">,</span> <span class="n">autocreate</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
|
||||
<span class="n">agility</span> <span class="o">=</span> <span class="n">AttributeProperty</span><span class="p">(</span><span class="mi">12</span><span class="p">,</span> <span class="n">autocreate</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
|
||||
<span class="n">strength</span> <span class="o">=</span> <span class="n">AttributeProperty</span><span class="p">(</span><span class="mi">10</span><span class="p">,</span> <span class="n">category</span><span class="o">=</span><span class="s1">'stat'</span><span class="p">)</span>
|
||||
<span class="n">constitution</span> <span class="o">=</span> <span class="n">AttributeProperty</span><span class="p">(</span><span class="mi">11</span><span class="p">,</span> <span class="n">category</span><span class="o">=</span><span class="s1">'stat'</span><span class="p">)</span>
|
||||
<span class="n">agility</span> <span class="o">=</span> <span class="n">AttributeProperty</span><span class="p">(</span><span class="mi">12</span><span class="p">,</span> <span class="n">category</span><span class="o">=</span><span class="s1">'stat'</span><span class="p">)</span>
|
||||
<span class="n">magic</span> <span class="o">=</span> <span class="n">AttributeProperty</span><span class="p">(</span><span class="mi">13</span><span class="p">,</span> <span class="n">category</span><span class="o">=</span><span class="s1">'stat'</span><span class="p">)</span>
|
||||
|
||||
<span class="n">sleepy</span> <span class="o">=</span> <span class="n">AttributeProperty</span><span class="p">(</span><span class="kc">False</span><span class="p">,</span> <span class="n">autocreate</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
|
||||
<span class="n">poisoned</span> <span class="o">=</span> <span class="n">AttributeProperty</span><span class="p">(</span><span class="kc">False</span><span class="p">,</span> <span class="n">autocreate</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
|
||||
|
||||
<span class="k">def</span> <span class="nf">at_object_creation</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
|
||||
<span class="c1"># initializing </span>
|
||||
<span class="bp">self</span><span class="o">.</span><span class="n">strength</span> <span class="c1"># by accessing it, the Attribute is auto-created</span>
|
||||
<span class="bp">self</span><span class="o">.</span><span class="n">agility</span> <span class="c1"># ''</span>
|
||||
<span class="c1"># ...</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="admonition important">
|
||||
<p class="admonition-title">Important</p>
|
||||
<p>If you created your <code class="docutils literal notranslate"><span class="pre">AttributeProperty</span></code> with a <code class="docutils literal notranslate"><span class="pre">category</span></code>, you <em>must</em> specify the
|
||||
category in <code class="docutils literal notranslate"><span class="pre">.attributes.get()</span></code> if you want to find it this way. Remember that
|
||||
<code class="docutils literal notranslate"><span class="pre">.db</span></code> always uses a <code class="docutils literal notranslate"><span class="pre">category</span></code> of <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
|
||||
<p>When a new instance of the class is created, new <code class="docutils literal notranslate"><span class="pre">Attributes</span></code> will be created with the value and category given.</p>
|
||||
<p>With <code class="docutils literal notranslate"><span class="pre">AttributeProperty</span></code>’s set up like this, one can access the underlying <code class="docutils literal notranslate"><span class="pre">Attribute</span></code> like a regular property on the created object:</p>
|
||||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">char</span> <span class="o">=</span> <span class="n">create_object</span><span class="p">(</span><span class="n">Character</span><span class="p">)</span>
|
||||
|
||||
<span class="n">char</span><span class="o">.</span><span class="n">strength</span> <span class="c1"># returns 10</span>
|
||||
<span class="n">char</span><span class="o">.</span><span class="n">agility</span> <span class="o">=</span> <span class="mi">15</span> <span class="c1"># assign a new value (category remains 'stat')</span>
|
||||
|
||||
<span class="n">char</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">magic</span> <span class="c1"># returns None (wrong category)</span>
|
||||
<span class="n">char</span><span class="o">.</span><span class="n">attributes</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">"agility"</span><span class="p">,</span> <span class="n">category</span><span class="o">=</span><span class="s2">"stat"</span><span class="p">)</span> <span class="c1"># returns 15</span>
|
||||
|
||||
<span class="n">char</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">sleepy</span> <span class="c1"># returns None because autocreate=False (see below)</span>
|
||||
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="admonition warning">
|
||||
<p class="admonition-title">Warning</p>
|
||||
<p>Be careful to not assign AttributeProperty’s to names of properties and methods already existing on the class, like ‘key’ or ‘at_object_creation’. That could lead to very confusing errors.</p>
|
||||
</div>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">autocreate=False</span></code> (default is <code class="docutils literal notranslate"><span class="pre">True</span></code>) used for <code class="docutils literal notranslate"><span class="pre">sleepy</span></code> and <code class="docutils literal notranslate"><span class="pre">poisoned</span></code> is worth a closer explanation. When <code class="docutils literal notranslate"><span class="pre">False</span></code>, <em>no</em> Attribute will be auto-created for these AttributProperties unless they are <em>explicitly</em> set.
|
||||
The advantage of not creating an Attribute is that the default value given to <code class="docutils literal notranslate"><span class="pre">AttributeProperty</span></code> is returned with no database access unless you change it. This also means that if you want to change the default later, all entities previously create will inherit the new default.
|
||||
The drawback is that without a database precense you can’t find the Attribute via <code class="docutils literal notranslate"><span class="pre">.db</span></code> and <code class="docutils literal notranslate"><span class="pre">.attributes.get</span></code> (or by querying for it in other ways in the database):</p>
|
||||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">char</span><span class="o">.</span><span class="n">sleepy</span> <span class="c1"># returns False, no db access</span>
|
||||
|
||||
<span class="n">char</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">sleepy</span> <span class="c1"># returns None - no Attribute exists</span>
|
||||
<span class="n">char</span><span class="o">.</span><span class="n">attributes</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">"sleepy"</span><span class="p">)</span> <span class="c1"># returns None too</span>
|
||||
|
||||
<span class="n">char</span><span class="o">.</span><span class="n">sleepy</span> <span class="o">=</span> <span class="kc">True</span> <span class="c1"># now an Attribute is created</span>
|
||||
<span class="n">char</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">sleepy</span> <span class="c1"># now returns True!</span>
|
||||
<span class="n">char</span><span class="o">.</span><span class="n">attributes</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">"sleepy"</span><span class="p">)</span> <span class="c1"># now returns True</span>
|
||||
|
||||
<span class="n">char</span><span class="o">.</span><span class="n">sleepy</span> <span class="c1"># now returns True, involves db access</span>
|
||||
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>You can e.g. <code class="docutils literal notranslate"><span class="pre">del</span> <span class="pre">char.strength</span></code> to set the value back to the default (the value defined
|
||||
in the <code class="docutils literal notranslate"><span class="pre">AttributeProperty</span></code>).</p>
|
||||
<p>See the <a class="reference internal" href="../api/evennia.typeclasses.attributes.html#evennia.typeclasses.attributes.AttributeProperty" title="evennia.typeclasses.attributes.AttributeProperty"><span class="xref myst py py-class">AttributeProperty API</span></a> for more details on how to create it with special options, like giving access-restrictions.</p>
|
||||
</section>
|
||||
</section>
|
||||
<section id="managing-attributes-in-game">
|
||||
|
|
@ -342,7 +276,7 @@ problem.</p>
|
|||
</pre></div>
|
||||
</div>
|
||||
<p>To view, do</p>
|
||||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>set myobj/foo
|
||||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>set myobj/foo
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>or see them together with all object-info with</p>
|
||||
|
|
@ -424,16 +358,16 @@ values into a string representation before storing it to the database. This is d
|
|||
<p>With a single object, we mean anything that is <em>not iterable</em>, like numbers, strings or custom class
|
||||
instances without the <code class="docutils literal notranslate"><span class="pre">__iter__</span></code> method.</p>
|
||||
<ul class="simple">
|
||||
<li><p>You can generally store any non-iterable Python entity that can be pickled.</p></li>
|
||||
<li><p>You can generally store any non-iterable Python entity that can be <em>pickled</em>.</p></li>
|
||||
<li><p>Single database objects/typeclasses can be stored, despite them normally not being possible
|
||||
to pickle. Evennia wil convert them to an internal representation using their classname,
|
||||
to pickle. Evennia will convert them to an internal representation using theihr classname,
|
||||
database-id and creation-date with a microsecond precision. When retrieving, the object
|
||||
instance will be re-fetched from the database using this information.</p></li>
|
||||
<li><p>To convert the database object, Evennia must know it’s there. If you <em>hide</em> a database object
|
||||
inside a non-iterable class, you will run into errors - this is not supported!</p></li>
|
||||
<li><p>If you ‘hide’ a db-obj as a property on a custom class, Evennia will not be
|
||||
able to find it to serialize it. For that you need to help it out (see below).</p></li>
|
||||
</ul>
|
||||
<div class="literal-block-wrapper docutils container" id="id3">
|
||||
<div class="code-block-caption"><span class="caption-text">Valid assignments</span><a class="headerlink" href="#id3" title="Permalink to this code">¶</a></div>
|
||||
<div class="literal-block-wrapper docutils container" id="id5">
|
||||
<div class="code-block-caption"><span class="caption-text">Valid assignments</span><a class="headerlink" href="#id5" title="Permalink to this code">¶</a></div>
|
||||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Examples of valid single-value attribute data:</span>
|
||||
<span class="n">obj</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">test1</span> <span class="o">=</span> <span class="mi">23</span>
|
||||
<span class="n">obj</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">test1</span> <span class="o">=</span> <span class="kc">False</span>
|
||||
|
|
@ -442,15 +376,51 @@ inside a non-iterable class, you will run into errors - this is not supported!</
|
|||
</pre></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="literal-block-wrapper docutils container" id="id4">
|
||||
<div class="code-block-caption"><span class="caption-text">Invalid, ‘hidden’ dbobject</span><a class="headerlink" href="#id4" title="Permalink to this code">¶</a></div>
|
||||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># example of an invalid, "hidden" dbobject</span>
|
||||
<p>As mentioned, Evennia will not be able to automatically serialize db-objects
|
||||
‘hidden’ in arbitrary properties on an object. This will lead to an error
|
||||
when saving the Attribute.</p>
|
||||
<div class="literal-block-wrapper docutils container" id="id6">
|
||||
<div class="code-block-caption"><span class="caption-text">Invalid, ‘hidden’ dbobject</span><a class="headerlink" href="#id6" title="Permalink to this code">¶</a></div>
|
||||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># example of storing an invalid, "hidden" dbobject in Attribute</span>
|
||||
<span class="k">class</span> <span class="nc">Container</span><span class="p">:</span>
|
||||
<span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">mydbobj</span><span class="p">):</span>
|
||||
<span class="c1"># no way for Evennia to know this is a database object!</span>
|
||||
<span class="bp">self</span><span class="o">.</span><span class="n">mydbobj</span> <span class="o">=</span> <span class="n">mydbobj</span>
|
||||
|
||||
<span class="c1"># let's assume myobj is a db-object</span>
|
||||
<span class="n">container</span> <span class="o">=</span> <span class="n">Container</span><span class="p">(</span><span class="n">myobj</span><span class="p">)</span>
|
||||
<span class="n">obj</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">invalid</span> <span class="o">=</span> <span class="n">container</span> <span class="c1"># will cause error!</span>
|
||||
<span class="n">obj</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">mydata</span> <span class="o">=</span> <span class="n">container</span> <span class="c1"># will raise error!</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</div>
|
||||
<p>By adding two methods <code class="docutils literal notranslate"><span class="pre">__serialize_dbobjs__</span></code> and <code class="docutils literal notranslate"><span class="pre">__deserialize_dbobjs__</span></code> to the
|
||||
object you want to save, you can pre-serialize and post-deserialize all ‘hidden’
|
||||
objects before Evennia’s main serializer gets to work. Inside these methods, use Evennia’s
|
||||
<a class="reference internal" href="../api/evennia.utils.dbserialize.html#evennia.utils.dbserialize.dbserialize" title="evennia.utils.dbserialize.dbserialize"><span class="xref myst py py-func">evennia.utils.dbserialize.dbserialize</span></a> and
|
||||
<a class="reference internal" href="../api/evennia.utils.dbserialize.html#evennia.utils.dbserialize.dbunserialize" title="evennia.utils.dbserialize.dbunserialize"><span class="xref myst py py-func">dbunserialize</span></a> functions to safely
|
||||
serialize the db-objects you want to store.</p>
|
||||
<div class="literal-block-wrapper docutils container" id="id7">
|
||||
<div class="code-block-caption"><span class="caption-text">Fixing an invalid ‘hidden’ dbobj for storing in Attribute</span><a class="headerlink" href="#id7" title="Permalink to this code">¶</a></div>
|
||||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">evennia.utils</span> <span class="kn">import</span> <span class="n">dbserialize</span> <span class="c1"># important</span>
|
||||
|
||||
<span class="k">class</span> <span class="nc">Container</span><span class="p">:</span>
|
||||
<span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">mydbobj</span><span class="p">):</span>
|
||||
<span class="c1"># A 'hidden' db-object</span>
|
||||
<span class="bp">self</span><span class="o">.</span><span class="n">mydbobj</span> <span class="o">=</span> <span class="n">mydbobj</span>
|
||||
|
||||
<span class="k">def</span> <span class="nf">__serialize_dbobjs__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
|
||||
<span class="sd">"""This is called before serialization and allows</span>
|
||||
<span class="sd"> us to custom-handle those 'hidden' dbobjs"""</span>
|
||||
<span class="bp">self</span><span class="o">.</span><span class="n">mydbobj</span> <span class="o">=</span> <span class="n">dbserialize</span><span class="o">.</span><span class="n">dbserialize</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">mydbobj</span>
|
||||
|
||||
<span class="k">def</span> <span class="nf">__deserialize_dbobjs__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
|
||||
<span class="sd">"""This is called after deserialization and allows you to</span>
|
||||
<span class="sd"> restore the 'hidden' dbobjs you serialized before"""</span>
|
||||
<span class="bp">self</span><span class="o">.</span><span class="n">mydbobj</span> <span class="o">=</span> <span class="n">dbserialize</span><span class="o">.</span><span class="n">dbunserialize</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">mydbobj</span><span class="p">)</span>
|
||||
|
||||
<span class="c1"># let's assume myobj is a db-object</span>
|
||||
<span class="n">container</span> <span class="o">=</span> <span class="n">Container</span><span class="p">(</span><span class="n">myobj</span><span class="p">)</span>
|
||||
<span class="n">obj</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">mydata</span> <span class="o">=</span> <span class="n">container</span> <span class="c1"># will now work fine!</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</div>
|
||||
|
|
@ -499,6 +469,10 @@ process but for efficiency you may want to avoid too deeply nested structures if
|
|||
<span class="c1"># test8 is now [4,2,{"test":5}]</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Note that if make some advanced iterable object, and store an db-object on it in
|
||||
a way such that it is <em>not</em> returned by iterating over it, you have created a
|
||||
‘hidden’ db-object. See <a class="reference internal" href="#storing-single-objects"><span class="std std-doc">the previous section</span></a> for how
|
||||
to tell Evennia how to serialize such hidden objects safely.</p>
|
||||
</section>
|
||||
<section id="retrieving-mutable-objects">
|
||||
<h3>Retrieving Mutable objects<a class="headerlink" href="#retrieving-mutable-objects" title="Permalink to this headline">¶</a></h3>
|
||||
|
|
@ -525,14 +499,14 @@ variable, e.g. <code class="docutils literal notranslate"><span class="pre">myli
|
|||
of the variable. If you update the snapshot, it will save to the database, but this change <em>will not propagate to
|
||||
any other snapshots you may have done previously</em>.</p>
|
||||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">obj</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">mylist</span> <span class="o">=</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">]</span>
|
||||
<span class="n">mylist1</span> <span class="o">=</span> <span class="n">obj</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">mylist</span>
|
||||
<span class="n">mylist2</span> <span class="o">=</span> <span class="n">obj</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">mylist</span>
|
||||
<span class="n">mylist1</span><span class="p">[</span><span class="mi">3</span><span class="p">]</span> <span class="o">=</span> <span class="mi">5</span>
|
||||
<span class="n">mylist1</span> <span class="o">=</span> <span class="n">obj</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">mylist</span>
|
||||
<span class="n">mylist2</span> <span class="o">=</span> <span class="n">obj</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">mylist</span>
|
||||
<span class="n">mylist1</span><span class="p">[</span><span class="mi">3</span><span class="p">]</span> <span class="o">=</span> <span class="mi">5</span>
|
||||
|
||||
<span class="nb">print</span><span class="p">(</span><span class="n">mylist1</span><span class="p">)</span> <span class="c1"># this is now [1, 2, 3, 5]</span>
|
||||
<span class="nb">print</span><span class="p">(</span><span class="n">obj</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">mylist</span><span class="p">)</span> <span class="c1"># also updated to [1, 2, 3, 5] </span>
|
||||
<span class="nb">print</span><span class="p">(</span><span class="n">obj</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">mylist</span><span class="p">)</span> <span class="c1"># also updated to [1, 2, 3, 5]</span>
|
||||
|
||||
<span class="nb">print</span><span class="p">(</span><span class="n">mylist2</span><span class="p">)</span> <span class="c1"># still [1, 2, 3, 4] ! </span>
|
||||
<span class="nb">print</span><span class="p">(</span><span class="n">mylist2</span><span class="p">)</span> <span class="c1"># still [1, 2, 3, 4] !</span>
|
||||
|
||||
</pre></div>
|
||||
</div>
|
||||
|
|
@ -546,7 +520,7 @@ back the results as needed.</p>
|
|||
<p>You can also choose to “disconnect” the Attribute entirely from the
|
||||
database with the help of the <code class="docutils literal notranslate"><span class="pre">.deserialize()</span></code> method:</p>
|
||||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">obj</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">mylist</span> <span class="o">=</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="p">{</span><span class="mi">1</span><span class="p">:</span> <span class="mi">2</span><span class="p">}]</span>
|
||||
<span class="n">mylist</span> <span class="o">=</span> <span class="n">obj</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">mylist</span><span class="o">.</span><span class="n">deserialize</span><span class="p">()</span>
|
||||
<span class="n">mylist</span> <span class="o">=</span> <span class="n">obj</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">mylist</span><span class="o">.</span><span class="n">deserialize</span><span class="p">()</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>The result of this operation will be a structure only consisting of normal Python mutables (<code class="docutils literal notranslate"><span class="pre">list</span></code>
|
||||
|
|
|
|||
|
|
@ -57,15 +57,16 @@ the return from the function.</p>
|
|||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">evennia.utils.funcparser</span> <span class="kn">import</span> <span class="n">FuncParser</span>
|
||||
|
||||
<span class="k">def</span> <span class="nf">_power_callable</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
|
||||
<span class="sd">"""This will be callable as $square(number, power=<num>) in string"""</span>
|
||||
<span class="sd">"""This will be callable as $pow(number, power=<num>) in string"""</span>
|
||||
<span class="nb">pow</span> <span class="o">=</span> <span class="nb">int</span><span class="p">(</span><span class="n">kwargs</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'power'</span><span class="p">,</span> <span class="mi">2</span><span class="p">))</span>
|
||||
<span class="k">return</span> <span class="nb">float</span><span class="p">(</span><span class="n">args</span><span class="p">[</span><span class="mi">0</span><span class="p">])</span> <span class="o">**</span> <span class="nb">pow</span>
|
||||
|
||||
<span class="c1"># create a parser and tell it that '$pow' means using _power_callable</span>
|
||||
<span class="n">parser</span> <span class="o">=</span> <span class="n">FuncParser</span><span class="p">({</span><span class="s2">"pow"</span><span class="p">:</span> <span class="n">_power_callable</span><span class="p">})</span>
|
||||
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Next, just pass a string into the parser, optionally containing <code class="docutils literal notranslate"><span class="pre">$func(...)</span></code> markers:</p>
|
||||
<p>Next, just pass a string into the parser, containing <code class="docutils literal notranslate"><span class="pre">$func(...)</span></code> markers:</p>
|
||||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">parser</span><span class="o">.</span><span class="n">parse</span><span class="p">(</span><span class="s2">"We have that 4 x 4 x 4 is $pow(4, power=3)."</span><span class="p">)</span>
|
||||
<span class="s2">"We have that 4 x 4 x 4 is 64."</span>
|
||||
</pre></div>
|
||||
|
|
@ -111,7 +112,7 @@ Evennia expects you to do in a proper text editor, outside of the game, not from
|
|||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">evennia.utils</span> <span class="kn">import</span> <span class="n">funcparser</span>
|
||||
|
||||
<span class="n">parser</span> <span class="o">=</span> <span class="n">FuncParser</span><span class="p">(</span><span class="n">callables</span><span class="p">,</span> <span class="o">**</span><span class="n">default_kwargs</span><span class="p">)</span>
|
||||
<span class="n">parsed_string</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parser</span><span class="p">(</span><span class="n">input_string</span><span class="p">,</span> <span class="n">raise_errors</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span>
|
||||
<span class="n">parsed_string</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse</span><span class="p">(</span><span class="n">input_string</span><span class="p">,</span> <span class="n">raise_errors</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span>
|
||||
<span class="n">escape</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="n">strip</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span>
|
||||
<span class="n">return_str</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="o">**</span><span class="n">reserved_kwargs</span><span class="p">)</span>
|
||||
|
||||
|
|
@ -131,8 +132,12 @@ If no such variable is defined, <em>every</em> top-level function in the module
|
|||
an underscore <code class="docutils literal notranslate"><span class="pre">_</span></code>) will be considered a suitable callable. The name of the function will be the <code class="docutils literal notranslate"><span class="pre">$funcname</span></code>
|
||||
by which it can be called.</p></li>
|
||||
<li><p>A <code class="docutils literal notranslate"><span class="pre">list</span></code> of modules/paths. This allows you to pull in modules from many sources for your parsing.</p></li>
|
||||
<li><p>The <code class="docutils literal notranslate"><span class="pre">**default</span></code> kwargs are optional kwargs that will be passed to <em>all</em>
|
||||
callables every time this parser is used - unless the user overrides it explicitly in
|
||||
their call. This is great for providing sensible standards that the user can
|
||||
tweak as needed.</p></li>
|
||||
</ul>
|
||||
<p>The other arguments to the parser:</p>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">FuncParser.parse</span></code> takes further arguments, and can vary for every string parsed.</p>
|
||||
<ul class="simple">
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">raise_errors</span></code> - By default, any errors from a callable will be quietly ignored and the result
|
||||
will be that the failing function call will show verbatim. If <code class="docutils literal notranslate"><span class="pre">raise_errors</span></code> is set,
|
||||
|
|
@ -143,12 +148,14 @@ this properly.</p></li>
|
|||
<li><p><code class="docutils literal notranslate"><span class="pre">return_str</span></code> - When <code class="docutils literal notranslate"><span class="pre">True</span></code> (default), <code class="docutils literal notranslate"><span class="pre">parser</span></code> always returns a string. If <code class="docutils literal notranslate"><span class="pre">False</span></code>, it may return
|
||||
the return value of a single function call in the string. This is the same as using the <code class="docutils literal notranslate"><span class="pre">.parse_to_any</span></code>
|
||||
method.</p></li>
|
||||
<li><p>The <code class="docutils literal notranslate"><span class="pre">**default/reserved_keywords</span></code> are optional and allow you to pass custom data into <em>every</em> function
|
||||
call. This is great for including things like the current session or config options. Defaults can be
|
||||
replaced if the user gives the same-named kwarg in the string’s function call. Reserved kwargs are always passed,
|
||||
ignoring defaults or what the user passed. In addition, the <code class="docutils literal notranslate"><span class="pre">funcparser</span></code> and <code class="docutils literal notranslate"><span class="pre">raise_errors</span></code>
|
||||
reserved kwargs are always passed - the first is a back-reference to the <code class="docutils literal notranslate"><span class="pre">FuncParser</span></code> instance and the second
|
||||
is the <code class="docutils literal notranslate"><span class="pre">raise_errors</span></code> boolean passed into <code class="docutils literal notranslate"><span class="pre">FuncParser.parse</span></code>.</p></li>
|
||||
<li><p>The <code class="docutils literal notranslate"><span class="pre">**reserved_keywords</span></code> are <em>always</em> passed to every callable in the string.
|
||||
They override any <code class="docutils literal notranslate"><span class="pre">**defaults</span></code> given when instantiating the parser and cannot
|
||||
be overridden by the user - if they enter the same kwarg it will be ignored.
|
||||
This is great for providing the current session, settings etc.</p></li>
|
||||
<li><p>The <code class="docutils literal notranslate"><span class="pre">funcparser</span></code> and <code class="docutils literal notranslate"><span class="pre">raise_errors</span></code>
|
||||
are always added as reserved keywords - the first is a
|
||||
back-reference to the <code class="docutils literal notranslate"><span class="pre">FuncParser</span></code> instance and the second
|
||||
is the <code class="docutils literal notranslate"><span class="pre">raise_errors</span></code> boolean given to <code class="docutils literal notranslate"><span class="pre">FuncParser.parse</span></code>.</p></li>
|
||||
</ul>
|
||||
<p>Here’s an example of using the default/reserved keywords:</p>
|
||||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">_test</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
|
||||
|
|
@ -193,7 +200,8 @@ of the string and may or may not raise the exception depending on what you set <
|
|||
created the parser.</p>
|
||||
<p>However, if you <em>nest</em> functions, the return of the innermost function may be something other than
|
||||
a string. Let’s introduce the <code class="docutils literal notranslate"><span class="pre">$eval</span></code> function, which evaluates simple expressions using
|
||||
Python’s <code class="docutils literal notranslate"><span class="pre">literal_eval</span></code> and/or <code class="docutils literal notranslate"><span class="pre">simple_eval</span></code>.</p>
|
||||
Python’s <code class="docutils literal notranslate"><span class="pre">literal_eval</span></code> and/or <code class="docutils literal notranslate"><span class="pre">simple_eval</span></code>. It returns whatever data type it
|
||||
evaluates to.</p>
|
||||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>"There's a $toint($eval(10 * 2.2))% chance of survival."
|
||||
</pre></div>
|
||||
</div>
|
||||
|
|
@ -210,21 +218,67 @@ will be a string:</p>
|
|||
<span class="s2">"There's a 22</span><span class="si">% c</span><span class="s2">hance of survival."</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>However, if you use the <code class="docutils literal notranslate"><span class="pre">parse_to_any</span></code> (or <code class="docutils literal notranslate"><span class="pre">parse(...,</span> <span class="pre">return_str=True)</span></code>) and <em>don’t add any extra string around the outermost function call</em>,
|
||||
<p>However, if you use the <code class="docutils literal notranslate"><span class="pre">parse_to_any</span></code> (or <code class="docutils literal notranslate"><span class="pre">parse(...,</span> <span class="pre">return_str=False)</span></code>) and
|
||||
<em>don’t add any extra string around the outermost function call</em>,
|
||||
you’ll get the return type of the outermost callable back:</p>
|
||||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">parser</span><span class="o">.</span><span class="n">parse_to_any</span><span class="p">(</span><span class="s2">"$toint($eval(10 * 2.2)%"</span><span class="p">)</span>
|
||||
<span class="s2">"22%"</span>
|
||||
<span class="n">parser</span><span class="o">.</span><span class="n">parse_to_any</span><span class="p">(</span><span class="s2">"$toint($eval(10 * 2.2)"</span><span class="p">)</span>
|
||||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">parser</span><span class="o">.</span><span class="n">parse_to_any</span><span class="p">(</span><span class="s2">"$toint($eval(10 * 2.2)"</span><span class="p">)</span>
|
||||
<span class="mi">22</span>
|
||||
<span class="n">parser</span><span class="o">.</span><span class="n">parse_to_any</span><span class="p">(</span><span class="s2">"the number $toint($eval(10 * 2.2)."</span><span class="p">)</span>
|
||||
<span class="s2">"the number 22"</span>
|
||||
<span class="n">parser</span><span class="o">.</span><span class="n">parse_to_any</span><span class="p">(</span><span class="s2">"$toint($eval(10 * 2.2)%"</span><span class="p">)</span>
|
||||
<span class="s2">"22%"</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<section id="escaping-special-character">
|
||||
<h3>Escaping special character<a class="headerlink" href="#escaping-special-character" title="Permalink to this headline">¶</a></h3>
|
||||
<p>When entering funcparser callables in strings, it looks like a regular
|
||||
function call inside a string:</p>
|
||||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="s2">"This is a $myfunc(arg1, arg2, kwarg=foo)."</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Commas (<code class="docutils literal notranslate"><span class="pre">,</span></code>) and equal-signs (<code class="docutils literal notranslate"><span class="pre">=</span></code>) are considered to separate the arguments and
|
||||
kwargs. In the same way, the right parenthesis (<code class="docutils literal notranslate"><span class="pre">)</span></code>) closes the argument list.
|
||||
Sometimes you want to include commas in the argument without it breaking the
|
||||
argument list.</p>
|
||||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="s2">"There is a $format(beautiful meadow, with dandelions) to the west."</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>You can escape in various ways.</p>
|
||||
<ul>
|
||||
<li><p>Prepending with the escape character <code class="docutils literal notranslate"><span class="pre">\</span></code></p>
|
||||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> ```python
|
||||
"There is a $format(beautiful meadow\, with dandelions) to the west."
|
||||
```
|
||||
</pre></div>
|
||||
</div>
|
||||
</li>
|
||||
<li><p>Wrapping your strings in quotes. This works like Python, and you can nest
|
||||
double and single quotes inside each other if so needed. The result will
|
||||
be a verbatim string that contains everything but the outermost quotes.</p>
|
||||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> ```python
|
||||
"There is a $format('beautiful meadow, with dandelions') to the west."
|
||||
```
|
||||
</pre></div>
|
||||
</div>
|
||||
</li>
|
||||
<li><p>If you want verbatim quotes in your string, you can escape them too.</p>
|
||||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> ```python
|
||||
"There is a $format('beautiful meadow, with \'dandelions\'') to the west."
|
||||
```
|
||||
</pre></div>
|
||||
</div>
|
||||
</li>
|
||||
</ul>
|
||||
</section>
|
||||
<section id="safe-convertion-of-inputs">
|
||||
<h3>Safe convertion of inputs<a class="headerlink" href="#safe-convertion-of-inputs" title="Permalink to this headline">¶</a></h3>
|
||||
<p>Since you don’t know in which order users may use your callables, they should always check the types
|
||||
of its inputs and convert to the type the callable needs. Note also that when converting from strings,
|
||||
there are limits what inputs you can support. This is because FunctionParser strings are often used by
|
||||
non-developer players/builders and some things (such as complex classes/callables etc) are just not
|
||||
safe/possible to convert from string representation.</p>
|
||||
<p>Since you don’t know in which order users may use your callables, they should
|
||||
always check the types of its inputs and convert to the type the callable needs.
|
||||
Note also that when converting from strings, there are limits what inputs you
|
||||
can support. This is because FunctionParser strings can be used by
|
||||
non-developer players/builders and some things (such as complex
|
||||
classes/callables etc) are just not safe/possible to convert from string
|
||||
representation.</p>
|
||||
<p>In <code class="docutils literal notranslate"><span class="pre">evennia.utils.utils</span></code> is a helper called
|
||||
<a class="reference internal" href="../api/evennia.utils.utils.html#evennia.utils.utils.safe_convert_to_types" title="evennia.utils.utils.safe_convert_to_types"><span class="xref myst py py-func">safe_convert_to_types</span></a>. This function
|
||||
automates the conversion of simple data types in a safe way:</p>
|
||||
|
|
@ -232,26 +286,28 @@ automates the conversion of simple data types in a safe way:</p>
|
|||
|
||||
<span class="k">def</span> <span class="nf">_process_callable</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
|
||||
<span class="sd">"""</span>
|
||||
<span class="sd"> A callable with a lot of custom options</span>
|
||||
|
||||
<span class="sd"> $process(expression, local, extra=34, extra2=foo)</span>
|
||||
<span class="sd"> $process(expression, local, extra1=34, extra2=foo)</span>
|
||||
|
||||
<span class="sd"> """</span>
|
||||
<span class="n">args</span><span class="p">,</span> <span class="n">kwargs</span> <span class="o">=</span> <span class="n">safe_convert_to_type</span><span class="p">(</span>
|
||||
<span class="p">((</span><span class="s1">'py'</span><span class="p">,</span> <span class="s1">'py'</span><span class="p">),</span> <span class="p">{</span><span class="s1">'extra1'</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span> <span class="s1">'extra2'</span><span class="p">:</span> <span class="nb">str</span><span class="p">}),</span>
|
||||
<span class="p">((</span><span class="s1">'py'</span><span class="p">,</span> <span class="nb">str</span><span class="p">),</span> <span class="p">{</span><span class="s1">'extra1'</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span> <span class="s1">'extra2'</span><span class="p">:</span> <span class="nb">str</span><span class="p">}),</span>
|
||||
<span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
|
||||
|
||||
<span class="c1"># args/kwargs should be correct types now</span>
|
||||
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>In other words, in the callable <code class="docutils literal notranslate"><span class="pre">$process(expression,</span> <span class="pre">local,</span> <span class="pre">extra1=..,</span> <span class="pre">extra2=...)</span></code>, the first argument will be handled by the ‘py’ converter
|
||||
(described below), the second will passed through regular Python <code class="docutils literal notranslate"><span class="pre">str</span></code>,
|
||||
kwargs will be handled by <code class="docutils literal notranslate"><span class="pre">int</span></code> and <code class="docutils literal notranslate"><span class="pre">str</span></code> respectively. You can supply
|
||||
your own converter function as long as it takes one argument and returns
|
||||
the converted result.</p>
|
||||
<p>In other words,</p>
|
||||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">args</span><span class="p">,</span> <span class="n">kwargs</span> <span class="o">=</span> <span class="n">safe_convert_to_type</span><span class="p">(</span>
|
||||
<span class="p">(</span><span class="n">tuple_of_arg_converters</span><span class="p">,</span> <span class="n">dict_of_kwarg_converters</span><span class="p">),</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Each converter should be a callable taking one argument - this will be the arg/kwarg-value to convert. The
|
||||
special converter <code class="docutils literal notranslate"><span class="pre">"py"</span></code> will try to convert a string argument to a Python structure with the help of the
|
||||
<p>The special converter <code class="docutils literal notranslate"><span class="pre">"py"</span></code> will try to convert a string argument to a Python structure with the help of the
|
||||
following tools (which you may also find useful to experiment with on your own):</p>
|
||||
<ul class="simple">
|
||||
<li><p><a class="reference external" href="https://docs.python.org/3.8/library/ast.html#ast.literal_eval">ast.literal_eval</a> is an in-built Python
|
||||
|
|
@ -439,6 +495,7 @@ all the defaults (like <code class="docutils literal notranslate"><span class="p
|
|||
<li><a class="reference internal" href="#uses-in-default-evennia">Uses in default Evennia</a></li>
|
||||
<li><a class="reference internal" href="#using-the-funcparser">Using the FuncParser</a></li>
|
||||
<li><a class="reference internal" href="#defining-custom-callables">Defining custom callables</a><ul>
|
||||
<li><a class="reference internal" href="#escaping-special-character">Escaping special character</a></li>
|
||||
<li><a class="reference internal" href="#safe-convertion-of-inputs">Safe convertion of inputs</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
|
|
|
|||
|
|
@ -62,11 +62,10 @@ hierarchies. It is set by the <code class="docutils literal notranslate"><span c
|
|||
<code class="docutils literal notranslate"><span class="pre">settings.PERMISSION_ACCOUNT_DEFAULT</span></code>.</p>
|
||||
<section id="managing-permissions">
|
||||
<h2>Managing Permissions<a class="headerlink" href="#managing-permissions" title="Permalink to this headline">¶</a></h2>
|
||||
<p>In-game, you use the <code class="docutils literal notranslate"><span class="pre">perm</span></code> command to add and remove permissions</p>
|
||||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> perm/account Tommy = Builders
|
||||
perm/account/del Tommy = Builders
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>In-game, you use the <code class="docutils literal notranslate"><span class="pre">perm</span></code> command to add and remove permissions
|
||||
j
|
||||
perm/account Tommy = Builders
|
||||
perm/account/del Tommy = Builders</p>
|
||||
<p>Note the use of the <code class="docutils literal notranslate"><span class="pre">/account</span></code> switch. It means you assign the permission to the
|
||||
<a class="reference internal" href="Accounts.html"><span class="doc std std-doc">Accounts</span></a> Tommy instead of any <a class="reference internal" href="Objects.html"><span class="doc std std-doc">Character</span></a> that also
|
||||
happens to be named “Tommy”.</p>
|
||||
|
|
|
|||
|
|
@ -49,18 +49,33 @@
|
|||
|
||||
<section class="tex2jax_ignore mathjax_ignore" id="tags">
|
||||
<h1>Tags<a class="headerlink" href="#tags" title="Permalink to this headline">¶</a></h1>
|
||||
<p>A common task of a game designer is to organize and find groups of objects and do operations on
|
||||
them. A classic example is to have a weather script affect all “outside” rooms. Another would be for
|
||||
a player casting a magic spell that affects every location “in the dungeon”, but not those
|
||||
“outside”. Another would be to quickly find everyone joined with a particular guild or everyone
|
||||
currently dead.</p>
|
||||
<p><em>Tags</em> are short text labels that you attach to objects so as to easily be able to retrieve and
|
||||
group them. An Evennia entity can be tagged with any number of Tags. On the database side, Tag
|
||||
entities are <em>shared</em> between all objects with that tag. This makes them very efficient but also
|
||||
fundamentally different from <a class="reference internal" href="Attributes.html"><span class="doc std std-doc">Attributes</span></a>, each of which always belongs to one <em>single</em>
|
||||
object.</p>
|
||||
<p>In Evennia, Tags are technically also used to implement <code class="docutils literal notranslate"><span class="pre">Aliases</span></code> (alternative names for objects)
|
||||
and <code class="docutils literal notranslate"><span class="pre">Permissions</span></code> (simple strings for <a class="reference internal" href="Locks.html"><span class="doc std std-doc">Locks</span></a> to check for).</p>
|
||||
<div class="literal-block-wrapper docutils container" id="id1">
|
||||
<div class="code-block-caption"><span class="caption-text">In game</span><a class="headerlink" href="#id1" title="Permalink to this code">¶</a></div>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">></span> <span class="n">tag</span> <span class="n">obj</span> <span class="o">=</span> <span class="n">tagname</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="literal-block-wrapper docutils container" id="id2">
|
||||
<div class="code-block-caption"><span class="caption-text">In code, using .tags (TagHandler)</span><a class="headerlink" href="#id2" title="Permalink to this code">¶</a></div>
|
||||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">obj</span><span class="o">.</span><span class="n">tags</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">"mytag"</span><span class="p">,</span> <span class="n">category</span><span class="o">=</span><span class="s2">"foo"</span><span class="p">)</span>
|
||||
<span class="n">obj</span><span class="o">.</span><span class="n">tags</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">"mytag"</span><span class="p">,</span> <span class="n">category</span><span class="o">=</span><span class="s2">"foo"</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="literal-block-wrapper docutils container" id="id3">
|
||||
<div class="code-block-caption"><span class="caption-text">In code, using TagProperty (auto-assign tag to all instances of the class)</span><a class="headerlink" href="#id3" title="Permalink to this code">¶</a></div>
|
||||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">evennia</span> <span class="kn">import</span> <span class="n">DefaultObject</span>
|
||||
<span class="kn">from</span> <span class="nn">evennia</span> <span class="kn">import</span> <span class="n">TagProperty</span>
|
||||
<span class="k">class</span> <span class="nc">Sword</span><span class="p">(</span><span class="n">DefaultObject</span><span class="p">):</span>
|
||||
<span class="n">can_be_wielded</span> <span class="o">=</span> <span class="n">TagProperty</span><span class="p">(</span><span class="n">category</span><span class="o">=</span><span class="s1">'combat'</span><span class="p">)</span>
|
||||
<span class="n">has_sharp_edge</span> <span class="o">=</span> <span class="n">TagProperty</span><span class="p">(</span><span class="n">category</span><span class="o">=</span><span class="s1">'combat'</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</div>
|
||||
<p><em>Tags</em> are short text lables one can ‘hang’ on objects in order to organize, group and quickly find out their properties. An Evennia entity can be tagged by any number of tags. They are more efficient than <a class="reference internal" href="Attributes.html"><span class="doc std std-doc">Attributes</span></a> since on the database-side, Tags are <em>shared</em> between all objects with that particular tag. A tag does not carry a value in itself; it either sits on the entity</p>
|
||||
<p>Above, the tags inform us that the <code class="docutils literal notranslate"><span class="pre">Sword</span></code> is both sharp and can be wielded. If that’s all they do, they could just be a normal Python flag. When tags become important is if there are a lot of objects with different combinations of tags. Maybe you have a magical spell that dulls <em>all</em> sharp-edged objects in the castle - whether sword, dagger, spear or kitchen knife! You can then just grab all objects with the <code class="docutils literal notranslate"><span class="pre">has_sharp_edge</span></code> tag.
|
||||
Another example would be a weather script affecting all rooms tagged as <code class="docutils literal notranslate"><span class="pre">outdoors</span></code> or finding all characters tagged with <code class="docutils literal notranslate"><span class="pre">belongs_to_fighter_guild</span></code>.</p>
|
||||
<p>In Evennia, Tags are technically also used to implement <code class="docutils literal notranslate"><span class="pre">Aliases</span></code> (alternative names for objects) and <code class="docutils literal notranslate"><span class="pre">Permissions</span></code> (simple strings for <a class="reference internal" href="Locks.html"><span class="doc std std-doc">Locks</span></a> to check for).</p>
|
||||
<section id="properties-of-tags-and-aliases-and-permissions">
|
||||
<h2>Properties of Tags (and Aliases and Permissions)<a class="headerlink" href="#properties-of-tags-and-aliases-and-permissions" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Tags are <em>unique</em>. This means that there is only ever one Tag object with a given key and category.</p>
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue