Updated HTML docs

docs/1.0-dev/api/evennia.objects.objects.html

@@ -29,6 +29,7 @@
         <li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
         <li class="nav-item nav-item-this"><a href="">evennia.objects.objects</a></li> 
       </ul>
+        <div class="develop">develop branch</div>
     </div>  
 
     <div class="document">
@@ -42,6 +43,7 @@
 <strong>DefaultCharacter</strong>, <strong>DefaultAccount</strong>, <strong>DefaultRoom</strong> and <strong>DefaultExit</strong>.
 These are the (default) starting points for all in-game visible
 entities.</p>
+<p>This is the v1.0 develop version (for ref in doc building).</p>
 <dl class="py class">
 <dt id="evennia.objects.objects.ObjectSessionHandler">
 <em class="property">class </em><code class="sig-prename descclassname">evennia.objects.objects.</code><code class="sig-name descname">ObjectSessionHandler</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">obj</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/objects/objects.html#ObjectSessionHandler"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.objects.objects.ObjectSessionHandler" title="Permalink to this definition">¶</a></dt>
@@ -197,21 +199,26 @@ currently connected to this object.</p>
 
 <dl class="py method">
 <dt id="evennia.objects.objects.DefaultObject.contents_get">
-<code class="sig-name descname">contents_get</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">exclude</span><span class="o">=</span><span class="default_value">None</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/objects/objects.html#DefaultObject.contents_get"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.objects.objects.DefaultObject.contents_get" title="Permalink to this definition">¶</a></dt>
+<code class="sig-name descname">contents_get</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">exclude</span><span class="o">=</span><span class="default_value">None</span></em>, <em class="sig-param"><span class="n">content_type</span><span class="o">=</span><span class="default_value">None</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/objects/objects.html#DefaultObject.contents_get"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.objects.objects.DefaultObject.contents_get" title="Permalink to this definition">¶</a></dt>
 <dd><p>Returns the contents of this object, i.e. all
 objects that has this object set as its location.
 This should be publically available.</p>
 <dl class="field-list simple">
 <dt class="field-odd">Parameters</dt>
-<dd class="field-odd"><p><strong>exclude</strong> (<em>Object</em>) – Object to exclude from returned
-contents list</p>
+<dd class="field-odd"><ul class="simple">
+<li><p><strong>exclude</strong> (<em>Object</em>) – Object to exclude from returned
+contents list</p></li>
+<li><p><strong>content_type</strong> (<em>str</em>) – A content_type to filter by. None for no
+filtering.</p></li>
+</ul>
 </dd>
 <dt class="field-even">Returns</dt>
 <dd class="field-even"><p><em>contents (list)</em> – List of contents of this Object.</p>
 </dd>
 </dl>
 <p class="rubric">Notes</p>
-<p>Also available as the <strong>contents</strong> property.</p>
+<p>Also available as the <strong>contents</strong> property, minus exclusion
+and filtering.</p>
 </dd></dl>
 
 <dl class="py method">
@@ -228,15 +235,20 @@ objects that has this object set as its location.
 This should be publically available.</p>
 <dl class="field-list simple">
 <dt class="field-odd">Parameters</dt>
-<dd class="field-odd"><p><strong>exclude</strong> (<em>Object</em>) – Object to exclude from returned
-contents list</p>
+<dd class="field-odd"><ul class="simple">
+<li><p><strong>exclude</strong> (<em>Object</em>) – Object to exclude from returned
+contents list</p></li>
+<li><p><strong>content_type</strong> (<em>str</em>) – A content_type to filter by. None for no
+filtering.</p></li>
+</ul>
 </dd>
 <dt class="field-even">Returns</dt>
 <dd class="field-even"><p><em>contents (list)</em> – List of contents of this Object.</p>
 </dd>
 </dl>
 <p class="rubric">Notes</p>
-<p>Also available as the <strong>contents</strong> property.</p>
+<p>Also available as the <strong>contents</strong> property, minus exclusion
+and filtering.</p>
 </dd></dl>
 
 <dl class="py method">
@@ -300,7 +312,7 @@ plural (str): The determined plural form of the key, including the count.</p>
 
 <dl class="py method">
 <dt id="evennia.objects.objects.DefaultObject.search">
-<code class="sig-name descname">search</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">searchdata</span></em>, <em class="sig-param"><span class="n">global_search</span><span class="o">=</span><span class="default_value">False</span></em>, <em class="sig-param"><span class="n">use_nicks</span><span class="o">=</span><span class="default_value">True</span></em>, <em class="sig-param"><span class="n">typeclass</span><span class="o">=</span><span class="default_value">None</span></em>, <em class="sig-param"><span class="n">location</span><span class="o">=</span><span class="default_value">None</span></em>, <em class="sig-param"><span class="n">attribute_name</span><span class="o">=</span><span class="default_value">None</span></em>, <em class="sig-param"><span class="n">quiet</span><span class="o">=</span><span class="default_value">False</span></em>, <em class="sig-param"><span class="n">exact</span><span class="o">=</span><span class="default_value">False</span></em>, <em class="sig-param"><span class="n">candidates</span><span class="o">=</span><span class="default_value">None</span></em>, <em class="sig-param"><span class="n">nofound_string</span><span class="o">=</span><span class="default_value">None</span></em>, <em class="sig-param"><span class="n">multimatch_string</span><span class="o">=</span><span class="default_value">None</span></em>, <em class="sig-param"><span class="n">use_dbref</span><span class="o">=</span><span class="default_value">None</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/objects/objects.html#DefaultObject.search"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.objects.objects.DefaultObject.search" title="Permalink to this definition">¶</a></dt>
+<code class="sig-name descname">search</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">searchdata</span></em>, <em class="sig-param"><span class="n">global_search</span><span class="o">=</span><span class="default_value">False</span></em>, <em class="sig-param"><span class="n">use_nicks</span><span class="o">=</span><span class="default_value">True</span></em>, <em class="sig-param"><span class="n">typeclass</span><span class="o">=</span><span class="default_value">None</span></em>, <em class="sig-param"><span class="n">location</span><span class="o">=</span><span class="default_value">None</span></em>, <em class="sig-param"><span class="n">attribute_name</span><span class="o">=</span><span class="default_value">None</span></em>, <em class="sig-param"><span class="n">quiet</span><span class="o">=</span><span class="default_value">False</span></em>, <em class="sig-param"><span class="n">exact</span><span class="o">=</span><span class="default_value">False</span></em>, <em class="sig-param"><span class="n">candidates</span><span class="o">=</span><span class="default_value">None</span></em>, <em class="sig-param"><span class="n">nofound_string</span><span class="o">=</span><span class="default_value">None</span></em>, <em class="sig-param"><span class="n">multimatch_string</span><span class="o">=</span><span class="default_value">None</span></em>, <em class="sig-param"><span class="n">use_dbref</span><span class="o">=</span><span class="default_value">None</span></em>, <em class="sig-param"><span class="n">stacked</span><span class="o">=</span><span class="default_value">0</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/objects/objects.html#DefaultObject.search"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.objects.objects.DefaultObject.search" title="Permalink to this definition">¶</a></dt>
 <dd><p>Returns an Object matching a search string/condition</p>
 <p>Perform a standard object search in the database, handling
 multiple results and lack thereof gracefully. By default, only
@@ -335,7 +347,9 @@ for a broader search.</p></li>
 to search. Note that this is used to query the <em>contents</em> of a
 location and will not match for the location itself -
 if you want that, don’t set this or use <strong>candidates</strong> to specify
-exactly which objects should be searched.</p></li>
+exactly which objects should be searched. If this nor candidates are
+given, candidates will include caller’s inventory, current location and
+all objects in the current location.</p></li>
 <li><p><strong>attribute_name</strong> (<em>str</em>) – Define which property to search. If set, no
 key+alias search will be performed. This can be used
 to search database fields (<a href="#id1"><span class="problematic" id="id2">db_</span></a> will be automatically
@@ -363,14 +377,22 @@ to find an object (globally) by its database-id 123. If <strong>False</strong>,
 will be treated like a normal string. If <strong>None</strong> (default), the ability to query by
 #dbref is turned on if <strong>self</strong> has the permission ‘Builder’ and is turned off
 otherwise.</p></li>
+<li><p><strong>stacked</strong> (<em>int</em><em>, </em><em>optional</em>) – If &gt; 0, multimatches will be analyzed to determine if they
+only contains identical objects; these are then assumed ‘stacked’ and no multi-match
+error will be generated, instead <strong>stacked</strong> number of matches will be returned. If
+<strong>stacked</strong> is larger than number of matches, returns that number of matches. If
+the found stack is a mix of objects, return None and handle the multi-match
+error depending on the value of <strong>quiet</strong>.</p></li>
 </ul>
 </dd>
 <dt class="field-even">Returns</dt>
-<dd class="field-even"><p><p><em>match (Object, None or list)</em> –</p>
-<dl class="simple">
-<dt>will return an Object/None if <strong>quiet=False</strong>,</dt><dd><p>otherwise it will return a list of 0, 1 or more matches.</p>
-</dd>
-</dl>
+<dd class="field-even"><p><p><em>Object</em> – If finding a match an <strong>quiet=False</strong>
+None: If not finding a unique match and <strong>quiet=False</strong>.
+list: With 0, 1 or more matching objects if <strong>quiet=True</strong>
+list: With 2 or more matching objects if <strong>stacked</strong> is a positive integer and</p>
+<blockquote>
+<div><p>the matched stack has only object-copies.</p>
+</div></blockquote>
 </p>
 </dd>
 </dl>
@@ -1494,6 +1516,36 @@ errors (list): A list of errors in string form, if any.</p>
 </dl>
 </dd></dl>
 
+<dl class="py method">
+<dt id="evennia.objects.objects.DefaultCharacter.normalize_name">
+<em class="property">classmethod </em><code class="sig-name descname">normalize_name</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">name</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/objects/objects.html#DefaultCharacter.normalize_name"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.objects.objects.DefaultCharacter.normalize_name" title="Permalink to this definition">¶</a></dt>
+<dd><p>Normalize the character name prior to creating. Note that this should be refactored
+to support i18n for non-latin scripts, but as we (currently) have no bug reports requesting better
+support of non-latin character sets, requiring character names to be latinified is an acceptable option.</p>
+<dl class="field-list simple">
+<dt class="field-odd">Parameters</dt>
+<dd class="field-odd"><p><strong>name</strong> (<em>str</em>) – The name of the character</p>
+</dd>
+<dt class="field-even">Returns</dt>
+<dd class="field-even"><p><em>latin_name (str)</em> – A valid name.</p>
+</dd>
+</dl>
+</dd></dl>
+
+<dl class="py method">
+<dt id="evennia.objects.objects.DefaultCharacter.validate_name">
+<em class="property">classmethod </em><code class="sig-name descname">validate_name</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">name</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/objects/objects.html#DefaultCharacter.validate_name"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.objects.objects.DefaultCharacter.validate_name" title="Permalink to this definition">¶</a></dt>
+<dd><p>Validate the character name prior to creating. Overload this function to add custom validators</p>
+<dl class="field-list simple">
+<dt class="field-odd">Parameters</dt>
+<dd class="field-odd"><p><strong>name</strong> (<em>str</em>) – The name of the character</p>
+</dd>
+<dt class="field-even">Returns</dt>
+<dd class="field-even"><p><em>valid (bool)</em> – True if character creation should continue; False if it should fail</p>
+</dd>
+</dl>
+</dd></dl>
+
 <dl class="py method">
 <dt id="evennia.objects.objects.DefaultCharacter.basetype_setup">
 <code class="sig-name descname">basetype_setup</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/objects/objects.html#DefaultCharacter.basetype_setup"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.objects.objects.DefaultCharacter.basetype_setup" title="Permalink to this definition">¶</a></dt>
@@ -1723,6 +1775,11 @@ overriding the call (unused by default).</p></li>
 <code class="sig-name descname">lock_storage</code><em class="property"> = 'cmd:all();'</em><a class="headerlink" href="#evennia.objects.objects.ExitCommand.lock_storage" title="Permalink to this definition">¶</a></dt>
 <dd></dd></dl>
 
+<dl class="py attribute">
+<dt id="evennia.objects.objects.ExitCommand.search_index_entry">
+<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': '', 'category': 'general', 'key': 'command', 'tags': '', 'text': '\n    This is a command that simply cause the caller to traverse\n    the object it is attached to.\n\n    '}</em><a class="headerlink" href="#evennia.objects.objects.ExitCommand.search_index_entry" title="Permalink to this definition">¶</a></dt>
+<dd></dd></dl>
+
 </dd></dl>
 
 <dl class="py class">
@@ -1922,7 +1979,6 @@ read for an error string instead.</p>
   <li><a href="../../0.9.5/api/evennia.objects.objects.html">0.9.5 (v0.9.5 branch)</a></li>
 </ul>
 
-
         </div>
       </div>
       <div class="clearer"></div>
@@ -1939,6 +1995,7 @@ read for an error string instead.</p>
         <li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
         <li class="nav-item nav-item-this"><a href="">evennia.objects.objects</a></li> 
       </ul>
+        <div class="develop">develop branch</div>
     </div>
     <div class="footer" role="contentinfo">
         &#169; Copyright 2020, The Evennia developer community.