<h1><spanclass="section-number">6. </span>Overview of the Evennia library<aclass="headerlink"href="#overview-of-the-evennia-library"title="Permalink to this headline">¶</a></h1>
<p>API stands for <codeclass="docutils literal notranslate"><spanclass="pre">Application</span><spanclass="pre">Programming</span><spanclass="pre">Interface</span></code>, a description for how to access the resources of a program or library.</p>
<p>A good place to start exploring Evennia is the <aclass="reference internal"href="../../../Evennia-API.html"><spanclass="doc std std-doc">Evenia-API frontpage</span></a>.
This page sums up the main components of Evennia with a short description of each. Try clicking through
to a few entries - once you get deep enough you’ll see full descriptions
of each component along with their documentation. You can also click <codeclass="docutils literal notranslate"><spanclass="pre">[source]</span></code> to see the full Python source
for each thing.</p>
<p>You can also browse <aclass="reference external"href="https://github.com/evennia/evennia">the evennia repository on github</a>. This is exactly
what you can download from us. The github repo is also searchable.</p>
<p>Finally, you can clone the evennia repo to your own computer and read the sources locally. This is necessary
if you want to help with Evennia’s development itself. See the
<aclass="reference internal"href="../../../Setup/Installation-Git.html"><spanclass="doc std std-doc">extended install instructions</span></a> if you want to do this.</p>
<p>If you installed Evennia with <codeclass="docutils literal notranslate"><spanclass="pre">pip</span><spanclass="pre">install</span></code>, the library folder will be installed deep inside your Python
installation. If you cloned the repo there will be a folder <codeclass="docutils literal notranslate"><spanclass="pre">evennia</span></code> on your hard drive there.</p>
<p>If you cloned the repo or read the code on <codeclass="docutils literal notranslate"><spanclass="pre">github</span></code> you’ll find this being the outermost structure:</p>
<p>This outer layer is for Evennia’s installation and package distribution. That internal folder <codeclass="docutils literal notranslate"><spanclass="pre">evennia/evennia/</span></code> is
the <em>actual</em> library, the thing covered by the API auto-docs and what you get when you do <codeclass="docutils literal notranslate"><spanclass="pre">import</span><spanclass="pre">evennia</span></code>.</p>
<blockquote>
<div><p>The <codeclass="docutils literal notranslate"><spanclass="pre">evennia/docs/</span></code> folder contains the sources for this documentation. See
<aclass="reference internal"href="../../../Contributing-Docs.html"><spanclass="doc std std-doc">contributing to the docs</span></a> if you want to learn more about how this works.</p>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">contrib/</span></code> - Optional plugins too game-specific for core Evennia.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">game_template/</span></code> - Copied to become the “game directory” when using <codeclass="docutils literal notranslate"><spanclass="pre">evennia</span><spanclass="pre">--init</span></code>.</p></li>
<li><p><aclass="reference internal"href="../../../Components/Help-System.html"><spanclass="doc std std-doc"><codeclass="docutils literal notranslate"><spanclass="pre">help/</span></code></span></a> - Handles the storage and creation of help entries.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">locale/</span></code> - Language files (<aclass="reference internal"href="../../../Concepts/Internationalization.html"><spanclass="doc std std-doc">i18n</span></a>).</p></li>
<li><p><aclass="reference internal"href="../../../Components/Locks.html"><spanclass="doc std std-doc"><codeclass="docutils literal notranslate"><spanclass="pre">locks/</span></code></span></a> - Lock system for restricting access to in-game entities.</p></li>
<li><p><aclass="reference internal"href="../../../Components/Objects.html"><spanclass="doc std std-doc"><codeclass="docutils literal notranslate"><spanclass="pre">objects/</span></code></span></a> - In-game entities (all types of items and Characters).</p></li>
<li><p><aclass="reference internal"href="../../../Components/Prototypes.html"><spanclass="doc std std-doc"><codeclass="docutils literal notranslate"><spanclass="pre">prototypes/</span></code></span></a> - Object Prototype/spawning system and OLC menu</p></li>
<li><p><aclass="reference internal"href="../../../Concepts/Web-Features.html"><spanclass="doc std std-doc"><codeclass="docutils literal notranslate"><spanclass="pre">web/</span></code></span></a> - Web resources and webserver. Partly copied into game directory on initialization.</p></li>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">__init__.py</span></code> file is a special Python filename used to represent a Python ‘package’. When you import <codeclass="docutils literal notranslate"><spanclass="pre">evennia</span></code> on its own, you import this file. When you do <codeclass="docutils literal notranslate"><spanclass="pre">evennia.foo</span></code> Python will first look for a property <codeclass="docutils literal notranslate"><spanclass="pre">.foo</span></code> in <codeclass="docutils literal notranslate"><spanclass="pre">__init__.py</span></code> and then for a module or folder of that name in the same location.</p>
<p>While all the actual Evennia code is found in the various folders, the <codeclass="docutils literal notranslate"><spanclass="pre">__init__.py</span></code> represents the entire
package <codeclass="docutils literal notranslate"><spanclass="pre">evennia</span></code>. It contains “shortcuts” to code that is actually located elsewhere. Most of these shortcuts
are listed if you <aclass="reference internal"href="../../../Evennia-API.html"><spanclass="doc std std-doc">scroll down a bit</span></a> on the Evennia-API page.</p>
<h2><spanclass="section-number">6.2. </span>An example of exploring the library<aclass="headerlink"href="#an-example-of-exploring-the-library"title="Permalink to this headline">¶</a></h2>
<p>In the previous lesson we took a brief look at <codeclass="docutils literal notranslate"><spanclass="pre">mygame/typeclasses/objects</span></code> as an example of a Python module. Let’s
open it again. Inside is the <codeclass="docutils literal notranslate"><spanclass="pre">Object</span></code> class, which inherits from <codeclass="docutils literal notranslate"><spanclass="pre">DefaultObject</span></code>.
<p>We want to figure out just what this DefaultObject offers. Since this is imported directly from <codeclass="docutils literal notranslate"><spanclass="pre">evennia</span></code>, we
are actually importing from <codeclass="docutils literal notranslate"><spanclass="pre">evennia/__init__.py</span></code>.</p>
<p><aclass="reference external"href="https://github.com/evennia/evennia/blob/master/evennia/__init__.py#159">Look at Line 159</a> of <codeclass="docutils literal notranslate"><spanclass="pre">evennia/__init__.py</span></code> and you’ll find this line:</p>
<p>The first full-stop in <codeclass="docutils literal notranslate"><spanclass="pre">from</span><spanclass="pre">.objects.objects</span><spanclass="pre">...</span></code> means that we are importing from the current location. This is called a <codeclass="docutils literal notranslate"><spanclass="pre">relative</span><spanclass="pre">import</span></code>. By comparison, <codeclass="docutils literal notranslate"><spanclass="pre">from</span><spanclass="pre">evennia.objects.objects</span></code> is an <codeclass="docutils literal notranslate"><spanclass="pre">absolute</span><spanclass="pre">import</span></code>. In this particular case, the two would give the same result.</p>
<div><p>You can also look at <aclass="reference internal"href="../../../Evennia-API.html#typeclasses"><spanclass="std std-doc">the right section of the API frontpage</span></a> and click through
<p>The fact that <codeclass="docutils literal notranslate"><spanclass="pre">DefaultObject</span></code> is imported into <codeclass="docutils literal notranslate"><spanclass="pre">__init__.py</span></code> here is what makes it possible to also import
it as <codeclass="docutils literal notranslate"><spanclass="pre">from</span><spanclass="pre">evennia</span><spanclass="pre">import</span><spanclass="pre">DefaultObject</span></code> even though the code for the class is not actually here.</p>
<p>So to find the code for <codeclass="docutils literal notranslate"><spanclass="pre">DefaultObject</span></code> we need to look in <codeclass="docutils literal notranslate"><spanclass="pre">evennia/objects/objects.py</span></code>. Here’s how
<li><p>Locate the link to <aclass="reference internal"href="../../../api/evennia.objects.objects.html"><spanclass="doc std std-doc">evennia.objects.objects</span></a> and click on it.
3 You are now in the python module. Scroll down (or search in your web browser) to find the <codeclass="docutils literal notranslate"><spanclass="pre">DefaultObject</span></code> class.
4 You can now read what this does and what methods are on it. If you want to see the full source, click the
