Updated HTML docs

This commit is contained in:
Griatch 2020-10-19 08:58:16 +02:00
parent 88483fc3fa
commit 8936980973
297 changed files with 5517 additions and 23708 deletions

View file

@ -53,7 +53,7 @@
<span class="kn">from</span> <span class="nn">django.conf</span> <span class="k">import</span> <span class="n">settings</span>
<span class="kn">from</span> <span class="nn">evennia.typeclasses.models</span> <span class="k">import</span> <span class="n">TypeclassBase</span>
<span class="kn">from</span> <span class="nn">evennia.typeclasses.attributes</span> <span class="k">import</span> <span class="n">NickHandler</span><span class="p">,</span> <span class="n">ModelAttributeBackend</span>
<span class="kn">from</span> <span class="nn">evennia.typeclasses.attributes</span> <span class="k">import</span> <span class="n">NickHandler</span>
<span class="kn">from</span> <span class="nn">evennia.objects.manager</span> <span class="k">import</span> <span class="n">ObjectManager</span>
<span class="kn">from</span> <span class="nn">evennia.objects.models</span> <span class="k">import</span> <span class="n">ObjectDB</span>
<span class="kn">from</span> <span class="nn">evennia.scripts.scripthandler</span> <span class="k">import</span> <span class="n">ScriptHandler</span>
@ -245,9 +245,6 @@
<span class="sd"> &quot;&quot;&quot;</span>
<span class="c1"># Used for sorting / filtering in inventories / room contents.</span>
<span class="n">_content_types</span> <span class="o">=</span> <span class="p">(</span><span class="s2">&quot;object&quot;</span><span class="p">,)</span>
<span class="c1"># lockstring of newly created objects, for easy overloading.</span>
<span class="c1"># Will be formatted with the appropriate attributes.</span>
<span class="n">lockstring</span> <span class="o">=</span> <span class="s2">&quot;control:id(</span><span class="si">{account_id}</span><span class="s2">) or perm(Admin);delete:id(</span><span class="si">{account_id}</span><span class="s2">) or perm(Admin)&quot;</span>
@ -266,7 +263,7 @@
<div class="viewcode-block" id="DefaultObject.nicks"><a class="viewcode-back" href="../../../api/evennia.objects.objects.html#evennia.objects.objects.DefaultObject.nicks">[docs]</a> <span class="nd">@lazy_property</span>
<span class="k">def</span> <span class="nf">nicks</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="k">return</span> <span class="n">NickHandler</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">ModelAttributeBackend</span><span class="p">)</span></div>
<span class="k">return</span> <span class="n">NickHandler</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span></div>
<div class="viewcode-block" id="DefaultObject.sessions"><a class="viewcode-back" href="../../../api/evennia.objects.objects.html#evennia.objects.objects.DefaultObject.sessions">[docs]</a> <span class="nd">@lazy_property</span>
<span class="k">def</span> <span class="nf">sessions</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
@ -301,7 +298,7 @@
<span class="ow">and</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="n">db_account</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">&quot;_quell&quot;</span><span class="p">)</span>
<span class="p">)</span>
<div class="viewcode-block" id="DefaultObject.contents_get"><a class="viewcode-back" href="../../../api/evennia.objects.objects.html#evennia.objects.objects.DefaultObject.contents_get">[docs]</a> <span class="k">def</span> <span class="nf">contents_get</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">exclude</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">content_type</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
<div class="viewcode-block" id="DefaultObject.contents_get"><a class="viewcode-back" href="../../../api/evennia.objects.objects.html#evennia.objects.objects.DefaultObject.contents_get">[docs]</a> <span class="k">def</span> <span class="nf">contents_get</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">exclude</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
<span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> Returns the contents of this object, i.e. all</span>
<span class="sd"> objects that has this object set as its location.</span>
@ -310,18 +307,17 @@
<span class="sd"> Args:</span>
<span class="sd"> exclude (Object): Object to exclude from returned</span>
<span class="sd"> contents list</span>
<span class="sd"> content_type (str): A content_type to filter by. None for no</span>
<span class="sd"> filtering.</span>
<span class="sd"> Returns:</span>
<span class="sd"> contents (list): List of contents of this Object.</span>
<span class="sd"> Notes:</span>
<span class="sd"> Also available as the `contents` property, minus exclusion</span>
<span class="sd"> and filtering.</span>
<span class="sd"> Also available as the `contents` property.</span>
<span class="sd"> &quot;&quot;&quot;</span>
<span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">contents_cache</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">exclude</span><span class="o">=</span><span class="n">exclude</span><span class="p">,</span> <span class="n">content_type</span><span class="o">=</span><span class="n">content_type</span><span class="p">)</span></div>
<span class="n">con</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">contents_cache</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">exclude</span><span class="o">=</span><span class="n">exclude</span><span class="p">)</span>
<span class="c1"># print &quot;contents_get:&quot;, self, con, id(self), calledby() # DEBUG</span>
<span class="k">return</span> <span class="n">con</span></div>
<div class="viewcode-block" id="DefaultObject.contents_set"><a class="viewcode-back" href="../../../api/evennia.objects.objects.html#evennia.objects.objects.DefaultObject.contents_set">[docs]</a> <span class="k">def</span> <span class="nf">contents_set</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">):</span>
<span class="s2">&quot;You cannot replace this property&quot;</span>
@ -417,7 +413,6 @@
<span class="n">nofound_string</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
<span class="n">multimatch_string</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
<span class="n">use_dbref</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
<span class="n">stacked</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span>
<span class="p">):</span>
<span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> Returns an Object matching a search string/condition</span>
@ -473,19 +468,10 @@
<span class="sd"> will be treated like a normal string. If `None` (default), the ability to query by</span>
<span class="sd"> #dbref is turned on if `self` has the permission &#39;Builder&#39; and is turned off</span>
<span class="sd"> otherwise.</span>
<span class="sd"> stacked (int, optional): If &gt; 0, multimatches will be analyzed to determine if they</span>
<span class="sd"> only contains identical objects; these are then assumed &#39;stacked&#39; and no multi-match</span>
<span class="sd"> error will be generated, instead `stacked` number of matches will be returned. If</span>
<span class="sd"> `stacked` is larger than number of matches, returns that number of matches. If</span>
<span class="sd"> the found stack is a mix of objects, return None and handle the multi-match</span>
<span class="sd"> error depending on the value of `quiet`.</span>
<span class="sd"> Returns:</span>
<span class="sd"> Object: If finding a match an `quiet=False`</span>
<span class="sd"> None: If not finding a unique match and `quiet=False`.</span>
<span class="sd"> list: With 0, 1 or more matching objects if `quiet=True`</span>
<span class="sd"> list: With 2 or more matching objects if `stacked` is a positive integer and</span>
<span class="sd"> the matched stack has only object-copies.</span>
<span class="sd"> match (Object, None or list): will return an Object/None if `quiet=False`,</span>
<span class="sd"> otherwise it will return a list of 0, 1 or more matches.</span>
<span class="sd"> Notes:</span>
<span class="sd"> To find Accounts, use eg. `evennia.account_search`. If</span>
@ -553,29 +539,8 @@
<span class="n">use_dbref</span><span class="o">=</span><span class="n">use_dbref</span><span class="p">,</span>
<span class="p">)</span>
<span class="n">nresults</span> <span class="o">=</span> <span class="nb">len</span><span class="p">(</span><span class="n">results</span><span class="p">)</span>
<span class="k">if</span> <span class="n">stacked</span> <span class="o">&gt;</span> <span class="mi">0</span> <span class="ow">and</span> <span class="n">nresults</span> <span class="o">&gt;</span> <span class="mi">1</span><span class="p">:</span>
<span class="c1"># handle stacks, disable multimatch errors</span>
<span class="n">nstack</span> <span class="o">=</span> <span class="n">nresults</span>
<span class="k">if</span> <span class="ow">not</span> <span class="n">exact</span><span class="p">:</span>
<span class="c1"># we re-run exact match agains one of the matches to</span>
<span class="c1"># make sure we were not catching partial matches not belonging</span>
<span class="c1"># to the stack</span>
<span class="n">nstack</span> <span class="o">=</span> <span class="nb">len</span><span class="p">(</span><span class="n">ObjectDB</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">get_objs_with_key_or_alias</span><span class="p">(</span>
<span class="n">results</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">key</span><span class="p">,</span>
<span class="n">exact</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
<span class="n">candidates</span><span class="o">=</span><span class="nb">list</span><span class="p">(</span><span class="n">results</span><span class="p">),</span>
<span class="n">typeclasses</span><span class="o">=</span><span class="p">[</span><span class="n">typeclass</span><span class="p">]</span> <span class="k">if</span> <span class="n">typeclass</span> <span class="k">else</span> <span class="kc">None</span>
<span class="p">))</span>
<span class="k">if</span> <span class="n">nstack</span> <span class="o">==</span> <span class="n">nresults</span><span class="p">:</span>
<span class="c1"># a valid stack, return multiple results</span>
<span class="k">return</span> <span class="nb">list</span><span class="p">(</span><span class="n">results</span><span class="p">)[:</span><span class="n">stacked</span><span class="p">]</span>
<span class="k">if</span> <span class="n">quiet</span><span class="p">:</span>
<span class="c1"># don&#39;t auto-handle error messaging</span>
<span class="k">return</span> <span class="nb">list</span><span class="p">(</span><span class="n">results</span><span class="p">)</span>
<span class="c1"># handle error messages</span>
<span class="k">return</span> <span class="n">_AT_SEARCH_RESULT</span><span class="p">(</span>
<span class="n">results</span><span class="p">,</span>
<span class="bp">self</span><span class="p">,</span>
@ -1732,26 +1697,20 @@
<span class="sd"> **kwargs (dict): Arbitrary, optional arguments for users</span>
<span class="sd"> overriding the call (unused by default).</span>
<span class="sd"> &quot;&quot;&quot;</span>
<span class="k">def</span> <span class="nf">filter_visible</span><span class="p">(</span><span class="n">obj_list</span><span class="p">):</span>
<span class="c1"># Helper method to determine if objects are visible to the looker.</span>
<span class="k">return</span> <span class="p">[</span><span class="n">obj</span> <span class="k">for</span> <span class="n">obj</span> <span class="ow">in</span> <span class="n">obj_list</span> <span class="k">if</span> <span class="n">obj</span> <span class="o">!=</span> <span class="n">looker</span> <span class="ow">and</span> <span class="n">obj</span><span class="o">.</span><span class="n">access</span><span class="p">(</span><span class="n">looker</span><span class="p">,</span> <span class="s2">&quot;view&quot;</span><span class="p">)]</span>
<span class="k">if</span> <span class="ow">not</span> <span class="n">looker</span><span class="p">:</span>
<span class="k">return</span> <span class="s2">&quot;&quot;</span>
<span class="c1"># get and identify all objects</span>
<span class="n">exits_list</span> <span class="o">=</span> <span class="n">filter_visible</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">contents_get</span><span class="p">(</span><span class="n">content_type</span><span class="o">=</span><span class="s2">&quot;exit&quot;</span><span class="p">))</span>
<span class="n">users_list</span> <span class="o">=</span> <span class="n">filter_visible</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">contents_get</span><span class="p">(</span><span class="n">content_type</span><span class="o">=</span><span class="s2">&quot;character&quot;</span><span class="p">))</span>
<span class="n">things_list</span> <span class="o">=</span> <span class="n">filter_visible</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">contents_get</span><span class="p">(</span><span class="n">content_type</span><span class="o">=</span><span class="s2">&quot;object&quot;</span><span class="p">))</span>
<span class="n">things</span> <span class="o">=</span> <span class="n">defaultdict</span><span class="p">(</span><span class="nb">list</span><span class="p">)</span>
<span class="k">for</span> <span class="n">thing</span> <span class="ow">in</span> <span class="n">things_list</span><span class="p">:</span>
<span class="n">things</span><span class="p">[</span><span class="n">thing</span><span class="o">.</span><span class="n">key</span><span class="p">]</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">thing</span><span class="p">)</span>
<span class="n">users</span> <span class="o">=</span> <span class="p">[</span><span class="n">f</span><span class="s2">&quot;|c</span><span class="si">{user.key}</span><span class="s2">|n&quot;</span> <span class="k">for</span> <span class="n">user</span> <span class="ow">in</span> <span class="n">users_list</span><span class="p">]</span>
<span class="n">exits</span> <span class="o">=</span> <span class="p">[</span><span class="n">ex</span><span class="o">.</span><span class="n">key</span> <span class="k">for</span> <span class="n">ex</span> <span class="ow">in</span> <span class="n">exits_list</span><span class="p">]</span>
<span class="n">visible</span> <span class="o">=</span> <span class="p">(</span><span class="n">con</span> <span class="k">for</span> <span class="n">con</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">contents</span> <span class="k">if</span> <span class="n">con</span> <span class="o">!=</span> <span class="n">looker</span> <span class="ow">and</span> <span class="n">con</span><span class="o">.</span><span class="n">access</span><span class="p">(</span><span class="n">looker</span><span class="p">,</span> <span class="s2">&quot;view&quot;</span><span class="p">))</span>
<span class="n">exits</span><span class="p">,</span> <span class="n">users</span><span class="p">,</span> <span class="n">things</span> <span class="o">=</span> <span class="p">[],</span> <span class="p">[],</span> <span class="n">defaultdict</span><span class="p">(</span><span class="nb">list</span><span class="p">)</span>
<span class="k">for</span> <span class="n">con</span> <span class="ow">in</span> <span class="n">visible</span><span class="p">:</span>
<span class="n">key</span> <span class="o">=</span> <span class="n">con</span><span class="o">.</span><span class="n">get_display_name</span><span class="p">(</span><span class="n">looker</span><span class="p">)</span>
<span class="k">if</span> <span class="n">con</span><span class="o">.</span><span class="n">destination</span><span class="p">:</span>
<span class="n">exits</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">key</span><span class="p">)</span>
<span class="k">elif</span> <span class="n">con</span><span class="o">.</span><span class="n">has_account</span><span class="p">:</span>
<span class="n">users</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s2">&quot;|c</span><span class="si">%s</span><span class="s2">|n&quot;</span> <span class="o">%</span> <span class="n">key</span><span class="p">)</span>
<span class="k">else</span><span class="p">:</span>
<span class="c1"># things can be pluralized</span>
<span class="n">things</span><span class="p">[</span><span class="n">key</span><span class="p">]</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">con</span><span class="p">)</span>
<span class="c1"># get description, build string</span>
<span class="n">string</span> <span class="o">=</span> <span class="s2">&quot;|c</span><span class="si">%s</span><span class="s2">|n</span><span class="se">\n</span><span class="s2">&quot;</span> <span class="o">%</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_display_name</span><span class="p">(</span><span class="n">looker</span><span class="p">)</span>
<span class="n">desc</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">desc</span>
@ -2109,9 +2068,6 @@
<span class="sd"> &quot;&quot;&quot;</span>
<span class="c1"># Tuple of types used for indexing inventory contents. Characters generally wouldn&#39;t be in</span>
<span class="c1"># anyone&#39;s inventory, but this also governs displays in room contents.</span>
<span class="n">_content_types</span> <span class="o">=</span> <span class="p">(</span><span class="s2">&quot;character&quot;</span><span class="p">,)</span>
<span class="c1"># lockstring of newly created rooms, for easy overloading.</span>
<span class="c1"># Will be formatted with the appropriate attributes.</span>
<span class="n">lockstring</span> <span class="o">=</span> <span class="p">(</span>
@ -2151,13 +2107,6 @@
<span class="c1"># If no typeclass supplied, use this class</span>
<span class="n">kwargs</span><span class="p">[</span><span class="s2">&quot;typeclass&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">kwargs</span><span class="o">.</span><span class="n">pop</span><span class="p">(</span><span class="s2">&quot;typeclass&quot;</span><span class="p">,</span> <span class="bp">cls</span><span class="p">)</span>
<span class="c1"># Normalize to latin characters and validate, if necessary, the supplied key</span>
<span class="n">key</span> <span class="o">=</span> <span class="bp">cls</span><span class="o">.</span><span class="n">normalize_name</span><span class="p">(</span><span class="n">key</span><span class="p">)</span>
<span class="k">if</span> <span class="ow">not</span> <span class="bp">cls</span><span class="o">.</span><span class="n">validate_name</span><span class="p">(</span><span class="n">key</span><span class="p">):</span>
<span class="n">errors</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s2">&quot;Invalid character name.&quot;</span><span class="p">)</span>
<span class="k">return</span> <span class="n">obj</span><span class="p">,</span> <span class="n">errors</span>
<span class="c1"># Set the supplied key as the name of the intended object</span>
<span class="n">kwargs</span><span class="p">[</span><span class="s2">&quot;key&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">key</span>
@ -2207,38 +2156,6 @@
<span class="k">return</span> <span class="n">obj</span><span class="p">,</span> <span class="n">errors</span></div>
<div class="viewcode-block" id="DefaultCharacter.normalize_name"><a class="viewcode-back" href="../../../api/evennia.objects.objects.html#evennia.objects.objects.DefaultCharacter.normalize_name">[docs]</a> <span class="nd">@classmethod</span>
<span class="k">def</span> <span class="nf">normalize_name</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span>
<span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> Normalize the character name prior to creating. Note that this should be refactored</span>
<span class="sd"> to support i18n for non-latin scripts, but as we (currently) have no bug reports requesting better</span>
<span class="sd"> support of non-latin character sets, requiring character names to be latinified is an acceptable option.</span>
<span class="sd"> Args:</span>
<span class="sd"> name (str) : The name of the character</span>
<span class="sd"> Returns:</span>
<span class="sd"> latin_name (str) : A valid name.</span>
<span class="sd"> &quot;&quot;&quot;</span>
<span class="kn">from</span> <span class="nn">evennia.utils.utils</span> <span class="k">import</span> <span class="n">latinify</span>
<span class="n">latin_name</span> <span class="o">=</span> <span class="n">latinify</span><span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="s2">&quot;X&quot;</span><span class="p">)</span>
<span class="k">return</span> <span class="n">latin_name</span></div>
<div class="viewcode-block" id="DefaultCharacter.validate_name"><a class="viewcode-back" href="../../../api/evennia.objects.objects.html#evennia.objects.objects.DefaultCharacter.validate_name">[docs]</a> <span class="nd">@classmethod</span>
<span class="k">def</span> <span class="nf">validate_name</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span>
<span class="sd">&quot;&quot;&quot; Validate the character name prior to creating. Overload this function to add custom validators</span>
<span class="sd"> Args:</span>
<span class="sd"> name (str) : The name of the character</span>
<span class="sd"> Returns:</span>
<span class="sd"> valid (bool) : True if character creation should continue; False if it should fail</span>
<span class="sd"> &quot;&quot;&quot;</span>
<span class="k">return</span> <span class="kc">True</span> <span class="c1"># Default validator does not perform any operations</span></div>
<div class="viewcode-block" id="DefaultCharacter.basetype_setup"><a class="viewcode-back" href="../../../api/evennia.objects.objects.html#evennia.objects.objects.DefaultCharacter.basetype_setup">[docs]</a> <span class="k">def</span> <span class="nf">basetype_setup</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> Setup character-specific security.</span>
@ -2367,10 +2284,6 @@
<span class="sd"> location is always `None`.</span>
<span class="sd"> &quot;&quot;&quot;</span>
<span class="c1"># A tuple of strings used for indexing this object inside an inventory.</span>
<span class="c1"># Generally, a room isn&#39;t expected to HAVE a location, but maybe in some games?</span>
<span class="n">_content_types</span> <span class="o">=</span> <span class="p">(</span><span class="s2">&quot;room&quot;</span><span class="p">,)</span>
<span class="c1"># lockstring of newly created rooms, for easy overloading.</span>
<span class="c1"># Will be formatted with the {id} of the creating object.</span>
<span class="n">lockstring</span> <span class="o">=</span> <span class="p">(</span>
@ -2530,7 +2443,6 @@
<span class="sd"> &quot;&quot;&quot;</span>
<span class="n">_content_types</span> <span class="o">=</span> <span class="p">(</span><span class="s2">&quot;exit&quot;</span><span class="p">,)</span>
<span class="n">exit_command</span> <span class="o">=</span> <span class="n">ExitCommand</span>
<span class="n">priority</span> <span class="o">=</span> <span class="mi">101</span>