evennia/docs/1.0-dev/API-refactoring.html


<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta charset="utf-8" />
    <title>API refactoring &#8212; Evennia 1.0-dev documentation</title>
    <link rel="stylesheet" href="_static/nature.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
    <script src="_static/jquery.js"></script>
    <script src="_static/underscore.js"></script>
    <script src="_static/doctools.js"></script>
    <script src="_static/language_data.js"></script>
    <link rel="shortcut icon" href="_static/favicon.ico"/>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" /> 
  </head><body>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="nav-item nav-item-0"><a href="index.html">Evennia 1.0-dev documentation</a> &#187;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <div class="section" id="api-refactoring">
<h1>API refactoring<a class="headerlink" href="#api-refactoring" title="Permalink to this headline">¶</a></h1>
<p>Building up to Evennia 1.0 and beyond, it’s time to comb through the Evennia API for old cruft. This whitepage is for anyone interested to contribute with their views on what part of the API needs refactoring, cleanup or clarification (or extension!)</p>
<p>Note that this is not a forum. To keep things clean, each opinion text should ideally present a clear argument or lay out a suggestion. Asking for clarification and any side-discussions should be held in chat or forum.</p>
<hr class="docutils" />
<div class="section" id="griatch-aug-13-2019">
<h2>Griatch (Aug 13, 2019)<a class="headerlink" href="#griatch-aug-13-2019" title="Permalink to this headline">¶</a></h2>
<p>This is how to enter an opinion. Use any markdown needed but stay within your section. Also remember to copy your text to the clipboard before saving since if someone else edited the wiki in the meantime you’ll have to start over.</p>
</div>
<div class="section" id="griatch-sept-2-2019">
<h2>Griatch (Sept 2, 2019)<a class="headerlink" href="#griatch-sept-2-2019" title="Permalink to this headline">¶</a></h2>
<p>I don’t agree with removing explicit keywords as suggested by <a class="reference external" href="/API-refactoring.html#reduce-usage-of-optionalpositional-arguments-aug-29-2019">Johnny on Aug 29 below</a>. Overriding such a method can still be done by <code class="docutils literal notranslate"><span class="pre">get(self,</span> <span class="pre">**kwargs)</span></code> if so desired, making the kwargs explicit helps IMO readability of the API. If just giving a generic <code class="docutils literal notranslate"><span class="pre">**kwargs</span></code>, one must read the docstring or even the code to see which keywords are valid.</p>
<p>On the other hand, I think it makes sense to as a standard offer an extra <code class="docutils literal notranslate"><span class="pre">**kwargs</span></code> at the end of arg-lists for common methods that are expected to be over-ridden. This make the API more flexible by hinting to the dev that they could expand their own over-ridden implementation with their own keyword arguments if so desired.</p>
</div>
<hr class="docutils" />
<div class="section" id="johnny">
<h2>Johnny<a class="headerlink" href="#johnny" title="Permalink to this headline">¶</a></h2>
<div class="section" id="reduce-usage-of-optional-positional-arguments-aug-29-2019">
<h3>Reduce usage of optional/positional arguments (Aug 29, 2019)<a class="headerlink" href="#reduce-usage-of-optional-positional-arguments-aug-29-2019" title="Permalink to this headline">¶</a></h3>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># AttributeHandler</span>
<span class="k">def</span> <span class="nf">get</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">category</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">return_obj</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span>
            <span class="n">strattr</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="n">raise_exception</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="n">accessing_obj</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
            <span class="n">default_access</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">return_list</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>
</pre></div>
</div>
<p>Many classes have methods requiring lengthy positional argument lists, which are tedious and error-prone to extend and override especially in cases where not all arguments are even required. It would be useful if arguments were reserved for required inputs and anything else relegated to kwargs for easier passthrough on extension.</p>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
            <p class="logo"><a href="index.html">
              <img class="logo" src="_static/evennia_logo.png" alt="Logo"/>
            </a></p>
<div id="searchbox" style="display: none" role="search">
  <h3 id="searchlabel">Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" />
      <input type="submit" value="Go" />
    </form>
    </div>
</div>
<script>$('#searchbox').show(0);</script>
<p><h3><a href="index.html">Table of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">API refactoring</a><ul>
<li><a class="reference internal" href="#griatch-aug-13-2019">Griatch (Aug 13, 2019)</a></li>
<li><a class="reference internal" href="#griatch-sept-2-2019">Griatch (Sept 2, 2019)</a></li>
<li><a class="reference internal" href="#johnny">Johnny</a><ul>
<li><a class="reference internal" href="#reduce-usage-of-optional-positional-arguments-aug-29-2019">Reduce usage of optional/positional arguments (Aug 29, 2019)</a></li>
</ul>
</li>
</ul>
</li>
</ul>

  <div role="note" aria-label="source link">
    <!--h3>This Page</h3-->
    <ul class="this-page-menu">
      <li><a href="_sources/API-refactoring.md.txt"
            rel="nofollow">Show Page Source</a></li>
    </ul>
   </div>
<h3>Versions</h3>
<ul>
  <li><a href="API-refactoring.html">1.0-dev (develop branch)</a></li>
  <li><a href="../0.9.1/API-refactoring.html">0.9.1 (master branch)</a></li>
</ul>

        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="nav-item nav-item-0"><a href="index.html">Evennia 1.0-dev documentation</a> &#187;</li> 
      </ul>
    </div>
    <div class="footer" role="contentinfo">
        &#169; Copyright 2020, The Evennia developer community.
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 2.4.4.
    </div>
  </body>
</html>