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


<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta charset="utf-8" />
    <title>Evennia API &#8212; Evennia 1.0-dev documentation</title>
    <link rel="stylesheet" href="_static/alabaster.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="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
   
  <link rel="stylesheet" href="_static/custom.css" type="text/css" />
  
  
  <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />

  </head><body>
  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          

          <div class="body" role="main">
            
  <div class="section" id="evennia-api">
<h1>Evennia API<a class="headerlink" href="#evennia-api" title="Permalink to this headline">¶</a></h1>
<p>Evennia makes much of its programming tools available directly from the top-level <code class="docutils literal notranslate"><span class="pre">evennia</span></code> package. This is often referred to as Evennia’s “flat” <a class="reference external" href="https://en.wikipedia.org/wiki/Application_programming_interface">Application Programming Interface</a> (API). The flat API tries to collect and bring the most commonly used resources to the front in a way where everything is available at a glance (in a flat display), making it a good place to start to learn Evennia.</p>
<blockquote>
<div><p>Evennia’s flat (and full) API can be perused through the auto-generated <a class="reference external" href="https://github.com/evennia/evennia/blob/master/evennia">API Library refence</a>.</p>
</div></blockquote>
<p>A good, interactive way to explore the flat API is to use <a class="reference external" href="http://ipython.org/">IPython</a>, a more flexible version of the default Python shell. Inside your virtual environment you can install IPython simply by</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="n">ipython</span>
</pre></div>
</div>
<p>Windows users should also install <a class="reference external" href="http://ipython.org/pyreadline.html">PyReadline</a>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="n">pyreadline</span>
</pre></div>
</div>
<p>With IPython installed, go to your game directory and run</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span> <span class="n">shell</span>
</pre></div>
</div>
<p>This should give you the IPython shell automatically. Inside IPython
you then do</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">evennia</span>
</pre></div>
</div>
<p>Followed by</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span><span class="o">.&lt;</span><span class="n">TAB</span><span class="o">&gt;</span>
</pre></div>
</div>
<p>That is, write <code class="docutils literal notranslate"><span class="pre">evennia.</span></code> and press the TAB key. What pops up is the contents of the <code class="docutils literal notranslate"><span class="pre">evennia</span></code> top-level package - in other words <a class="reference external" href="https://github.com/evennia/evennia/blob/master/evennia#the-flat-api">the “flat” API</a>.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>evennia.DefaultObject?
</pre></div>
</div>
<p>Starting to write the name of an API entity and pressing <code class="docutils literal notranslate"><span class="pre">&lt;TAB&gt;</span></code> will auto-complete the name. Adding a question mark (<code class="docutils literal notranslate"><span class="pre">?</span></code>) to its name will show you its documentation. Append <code class="docutils literal notranslate"><span class="pre">??</span></code> to get the actual source code. This way you can quickly explore Evennia and see what is available.</p>
<div class="section" id="to-remember-when-importing-from-evennia">
<h2>To remember when importing from <code class="docutils literal notranslate"><span class="pre">evennia</span></code><a class="headerlink" href="#to-remember-when-importing-from-evennia" title="Permalink to this headline">¶</a></h2>
<p>Properties on the root of the <code class="docutils literal notranslate"><span class="pre">evennia</span></code> package are <em>not</em> modules in their own right. They are just  shortcut properties stored in the <code class="docutils literal notranslate"><span class="pre">evennia/__init__.py</span></code> module. That means that you cannot use dot-notation to <code class="docutils literal notranslate"><span class="pre">import</span></code> nested module-names over <code class="docutils literal notranslate"><span class="pre">evennia</span></code>. The rule of thumb is that you cannot use <code class="docutils literal notranslate"><span class="pre">import</span></code> for more than one level down. Hence you can do</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
2</pre></div></td><td class="code"><div class="highlight"><pre><span></span>    <span class="kn">import</span> <span class="nn">evennia</span>
    <span class="k">print</span><span class="p">(</span><span class="n">evennia</span><span class="o">.</span><span class="n">default_cmds</span><span class="o">.</span><span class="n">CmdLook</span><span class="p">)</span>
</pre></div>
</td></tr></table></div>
<p>or import one level down</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
2</pre></div></td><td class="code"><div class="highlight"><pre><span></span>    <span class="kn">from</span> <span class="nn">evennia</span> <span class="kn">import</span> <span class="n">default_cmds</span>
    <span class="k">print</span><span class="p">(</span><span class="n">default_cmds</span><span class="o">.</span><span class="n">CmdLook</span><span class="p">)</span>
</pre></div>
</td></tr></table></div>
<p>but you <em>cannot</em> import two levels down</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1</pre></div></td><td class="code"><div class="highlight"><pre><span></span>     <span class="kn">from</span> <span class="nn">evennia.default_cmds</span> <span class="kn">import</span> <span class="n">CmdLook</span> <span class="c1"># error!</span>
</pre></div>
</td></tr></table></div>
<p>This will give you an <code class="docutils literal notranslate"><span class="pre">ImportError</span></code> telling you that the module <code class="docutils literal notranslate"><span class="pre">default_cmds</span></code> cannot be found - this is becasue <code class="docutils literal notranslate"><span class="pre">default_cmds</span></code> is just a <em>variable</em> stored in <code class="docutils literal notranslate"><span class="pre">evennia.__init__.py</span></code>; this cannot be imported from. If you really want full control over which level of package you import you can always bypass the root package and import directly from from the real location. For example <code class="docutils literal notranslate"><span class="pre">evennia.DefaultObject</span></code> is a shortcut to <code class="docutils literal notranslate"><span class="pre">evennia.objects.objects.DefaultObject</span></code>. Using this full path will have the import mechanism work normally. See <code class="docutils literal notranslate"><span class="pre">evennia/__init__.py</span></code> to see where the package imports from.</p>
</div>
</div>


          </div>
          
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
<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="#">Evennia API</a><ul>
<li><a class="reference internal" href="#to-remember-when-importing-from-evennia">To remember when importing from <code class="docutils literal notranslate"><span class="pre">evennia</span></code></a></li>
</ul>
</li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
  <li><a href="index.html">Documentation overview</a><ul>
  </ul></li>
</ul>
</div>
  <div role="note" aria-label="source link">
    <!--h3>This Page</h3-->
    <ul class="this-page-menu">
      <li><a href="_sources/Evennia-API.md.txt"
            rel="nofollow">Show Page Source</a></li>
    </ul>
   </div>
<h3>Versions</h3>
<ul>
  <li><a href="Evennia-API.html">1.0-dev (develop branch)</a></li>
  <li><a href="../0.9.1/index.html">0.9.1 (master branch)</a></li>
</ul>

        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="footer">
      &copy;2020, The Evennia developer community.
      
      |
      Powered by <a href="http://sphinx-doc.org/">Sphinx 2.4.4</a>
      &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
      
      |
      <a href="_sources/Evennia-API.md.txt"
          rel="nofollow">Page source</a>
    </div>

    
  </body>
</html>