<h1><spanclass="section-number">5. </span>Introduction to Python classes and objects<aclass="headerlink"href="#introduction-to-python-classes-and-objects"title="Permalink to this headline">¶</a></h1>
<p>We have now learned how to run some simple Python code from inside (and outside) your game server.
We have also taken a look at what our game dir looks and what is where. Now we’ll start to use it.</p>
<sectionid="importing-things">
<h2><spanclass="section-number">5.1. </span>Importing things<aclass="headerlink"href="#importing-things"title="Permalink to this headline">¶</a></h2>
<p>In a <aclass="reference internal"href="Beginner-Tutorial-Python-basic-introduction.html#importing-code-from-other-modules"><spanclass="std std-doc">previous lesson</span></a> we already learned how to import resources into our code. Now we’ll dive a little deeper.</p>
<p>No one writes something as big as an online game in one single huge file. Instead one breaks up the code into separate files (modules). Each module is dedicated to different purposes. Not only does it make things cleaner, organized and easier to understand.</p>
<p>Splitting code also makes it easier to re-use - you just import the resources you need and know you only get just what you requested. This makes it easier to spot errors and to know what code is good and which has issues.</p>
<p>If you followed earlier tutorial lessons, the <codeclass="docutils literal notranslate"><spanclass="pre">mygame/world/test.py</span></code> file should look like this (if
<pclass="sidebar-title">Whitespace matters in Python!</p>
<ulclass="simple">
<li><p>Indentation matters in Python</p></li>
<li><p>So does capitalization</p></li>
<li><p>Use 4 <codeclass="docutils literal notranslate"><spanclass="pre">spaces</span></code> to indent, not tabs</p></li>
<li><p>Empty lines are fine</p></li>
<li><p>Anything on a line after a <codeclass="docutils literal notranslate"><spanclass="pre">#</span></code> is a <codeclass="docutils literal notranslate"><spanclass="pre">comment</span></code>, ignored by Python</p></li>
<p>To reiterate, the <em>python_path</em> describes the relation between Python resources, both between and inside Python <em>modules</em> (that is, files ending with .py). Paths use <codeclass="docutils literal notranslate"><spanclass="pre">.</span></code> and always skips the <codeclass="docutils literal notranslate"><spanclass="pre">.py</span></code> file endings. Also, Evennia already knows to start looking for python resources inside <codeclass="docutils literal notranslate"><spanclass="pre">mygame/</span></code> so this should never be included.</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">import</span></code> Python instruction loads <codeclass="docutils literal notranslate"><spanclass="pre">world.test</span></code> so you have it available. You can now go “into”
<p>Using <codeclass="docutils literal notranslate"><spanclass="pre">import</span></code> like this means that you have to specify the full <codeclass="docutils literal notranslate"><spanclass="pre">world.test</span></code> every time you want
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">from</span><spanclass="pre">...</span><spanclass="pre">import</span><spanclass="pre">...</span></code> is very, very common as long as you want to get something with a longer
python path. It imports <codeclass="docutils literal notranslate"><spanclass="pre">hello_world</span></code> directly, so you can use it right away!</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>> py from world.test import hello_world ; hello_world(me)
Hello World!
</pre></div>
</div>
<p>Let’s say your <codeclass="docutils literal notranslate"><spanclass="pre">test.py</span></code> module had a bunch of interesting functions. You could then import them
<p>If there were <em>a lot</em> of functions, you could instead just import <codeclass="docutils literal notranslate"><spanclass="pre">test</span></code> and get the function
from there when you need (without having to give the full <codeclass="docutils literal notranslate"><spanclass="pre">world.test</span></code> every time):</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>> from world import test ; test.hello_world(me
Hello World!
</pre></div>
</div>
<p>You can also <em>rename</em> stuff you import. Say for example that the module you import to already
has a function <codeclass="docutils literal notranslate"><spanclass="pre">hello_world</span></code> but we also want to use the one from <codeclass="docutils literal notranslate"><spanclass="pre">world/test.py</span></code>:</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>from world.test import hello_world as test_hello_world
</pre></div>
</div>
<p>The form <codeclass="docutils literal notranslate"><spanclass="pre">from</span><spanclass="pre">...</span><spanclass="pre">import</span><spanclass="pre">...</span><spanclass="pre">as</span><spanclass="pre">...</span></code> renames the import.</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>> from world.test import hello_world as hw ; hw(me)
Hello World!
</pre></div>
</div>
<blockquote>
<div><p>Avoid renaming unless it’s to avoid a name-collistion like above - you want to make things as
easy to read as possible, and renaming adds another layer of potential confusion.</p>
</div></blockquote>
<p>In <aclass="reference internal"href="Beginner-Tutorial-Python-basic-introduction.html"><spanclass="doc std std-doc">the basic intro to Python</span></a> we learned how to open the in-game
<p>You now only need to import once to use the imported function over and over.</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>> from world.test import hello_world
> hello_world()
Hello World!
> hello_world()
Hello World!
> hello_world()
Hello World!
> quit()
Closing the Python console.
</pre></div>
</div>
<p>The same goes when writing code in a module - in most Python modules you will see a bunch of
imports at the top, resources that are then used by all code in that module.</p>
</section>
<sectionid="on-classes-and-objects">
<h2><spanclass="section-number">5.2. </span>On classes and objects<aclass="headerlink"href="#on-classes-and-objects"title="Permalink to this headline">¶</a></h2>
<p>Now that we know about imports, let look at a real Evennia module and try to understand it.</p>
<p>Open <codeclass="docutils literal notranslate"><spanclass="pre">mygame/typeclasses/objects.py</span></code> in your text editor of choice.</p>
<p>A docstring is not the same as a comment (created by <codeclass="docutils literal notranslate"><spanclass="pre">#</span></code>). A docstring is not ignored by Python but is an integral part of the thing it is documenting (the module and the class in this case). For example, we read docstrings to help text for <aclass="reference internal"href="../../../Evennia-API.html"><spanclass="doc std std-doc">API documentation</span></a>; we could not do that with comments.</p>
<p>The real file is much longer but we can ignore the multi-line strings (<codeclass="docutils literal notranslate"><spanclass="pre">"""</span><spanclass="pre">...</span><spanclass="pre">"""</span></code>). These serve
as documentation-strings, or <em>docstrings</em> for the module (at the top) and the <codeclass="docutils literal notranslate"><spanclass="pre">class</span></code> below.</p>
<p>Below the module doc string we have the import. In this case we are importing a resource
from the core <codeclass="docutils literal notranslate"><spanclass="pre">evennia</span></code> library itself. We will dive into this later, for now we just treat this
<p>Next we have an empty <codeclass="docutils literal notranslate"><spanclass="pre">class</span></code> named <codeclass="docutils literal notranslate"><spanclass="pre">ObjectParent</span></code>. It doesn’t do anything, its only code (except the docstring) is <codeclass="docutils literal notranslate"><spanclass="pre">pass</span></code> which means, well, to pass and don’t do anything. Since it also doesn’t <em>inherit</em> from anything, it’s just an empty container. We will not concern ourselves with it for this tutorial.</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">class</span></code> named <codeclass="docutils literal notranslate"><spanclass="pre">Object</span></code>_ inherits_ from <codeclass="docutils literal notranslate"><spanclass="pre">ObjectParent</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">DefaultObject</span></code>. Since we see that <codeclass="docutils literal notranslate"><spanclass="pre">ObjectParent</span></code> is empty, what is interesting is <codeclass="docutils literal notranslate"><spanclass="pre">DefaultObject</span></code>. Again, the <codeclass="docutils literal notranslate"><spanclass="pre">Object</span></code> class doesn’t
actually do anything on its own right now, but because of it being a child of <codeclass="docutils literal notranslate"><spanclass="pre">DefaultObject</span></code>, it’s actually providing a lot of functionality! If this is confusing, read on.</p>
<p>We will get back to this module in the <aclass="reference internal"href="Beginner-Tutorial-Learning-Typeclasses.html"><spanclass="doc std std-doc">next lesson</span></a>. First we need to do a little detour to understand what a ‘class’, an ‘object’ or ‘instance’ is. These are fundamental things to understand before you can use Evennia efficiently.</p>
<p>Classes, objects, instances and inheritance are fundamental to Python. This and some other concepts are often clumped together under the term Object-Oriented-Programming (OOP).</p>
</aside>
<sectionid="classes-and-instances">
<h3><spanclass="section-number">5.2.1. </span>Classes and instances<aclass="headerlink"href="#classes-and-instances"title="Permalink to this headline">¶</a></h3>
<p>A ‘class’ can be seen as a ‘template’ for a ‘type’ of object. The class describes the basic functionality of everyone of that class. For example, we could have a class <codeclass="docutils literal notranslate"><spanclass="pre">Monster</span></code> which has resources for moving itself from room to room.</p>
<p>Open a new file <codeclass="docutils literal notranslate"><spanclass="pre">mygame/typeclasses/monsters.py</span></code>. Add the following simple class:</p>
<spanclass="nb">print</span><spanclass="p">(</span><spanclass="sa">f</span><spanclass="s2">"</span><spanclass="si">{</span><spanclass="bp">self</span><spanclass="o">.</span><spanclass="n">key</span><spanclass="si">}</span><spanclass="s2"> is moving!"</span><spanclass="p">)</span>
</pre></div>
</div>
<p>Above we have defined a <codeclass="docutils literal notranslate"><spanclass="pre">Monster</span></code> class with one variable <codeclass="docutils literal notranslate"><spanclass="pre">key</span></code> (that is, the name) and one
<em>method</em> on it. A method is like a function except it sits “on” the class. It also always has
at least one argument (almost always written as <codeclass="docutils literal notranslate"><spanclass="pre">self</span></code> although you could in principle use
another name), which is a reference back to itself. So when we print <codeclass="docutils literal notranslate"><spanclass="pre">self.key</span></code> we are referring
back to the <codeclass="docutils literal notranslate"><spanclass="pre">key</span></code> on the class.</p>
<asideclass="sidebar">
<pclass="sidebar-title">Terms</p>
<ulclass="simple">
<li><p>A <codeclass="docutils literal notranslate"><spanclass="pre">class</span></code> is a code template describing a ‘type’ of something</p></li>
<li><p>An <codeclass="docutils literal notranslate"><spanclass="pre">object</span></code> is an <codeclass="docutils literal notranslate"><spanclass="pre">instance</span></code> of a <codeclass="docutils literal notranslate"><spanclass="pre">class</span></code>. Like using a mold to cast tin soldiers, one class can be <codeclass="docutils literal notranslate"><spanclass="pre">instantiated</span></code> into any number of object-instances. Each instance does not need to be identical (much like each tin soldier can be painted differently).</p></li>
<codeclass="docutils literal notranslate"><spanclass="pre">Monster</span></code> is a class, then an instance is <codeclass="docutils literal notranslate"><spanclass="pre">Fluffy</span></code>, a specific dragon individual. You instantiate
<p>We created an <em>instance</em> of <codeclass="docutils literal notranslate"><spanclass="pre">Monster</span></code>, which we stored in the variable <codeclass="docutils literal notranslate"><spanclass="pre">fluffy</span></code>. We then
called the <codeclass="docutils literal notranslate"><spanclass="pre">move_around</span></code> method on fluffy to get the printout.</p>
<blockquote>
<div><p>Note how we <em>didn’t</em> call the method as <codeclass="docutils literal notranslate"><spanclass="pre">fluffy.move_around(self)</span></code>. While the <codeclass="docutils literal notranslate"><spanclass="pre">self</span></code> has to be
there when defining the method, we <em>never</em> add it explicitly when we call the method (Python
will add the correct <codeclass="docutils literal notranslate"><spanclass="pre">self</span></code> for us automatically behind the scenes).</p>
</div></blockquote>
<p>Let’s create the sibling of Fluffy, Cuddly:</p>
<p>We now have two dragons and they’ll hang around until with call <codeclass="docutils literal notranslate"><spanclass="pre">quit()</span></code> to exit this Python
instance. We can have them move as many times as we want. But no matter how many dragons we create, they will all show the same printout since <codeclass="docutils literal notranslate"><spanclass="pre">key</span></code> is always fixed as “Monster”.</p>
<spanclass="nb">print</span><spanclass="p">(</span><spanclass="sa">f</span><spanclass="s2">"</span><spanclass="si">{</span><spanclass="bp">self</span><spanclass="o">.</span><spanclass="n">key</span><spanclass="si">}</span><spanclass="s2"> is moving!"</span><spanclass="p">)</span>
</pre></div>
</div>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">__init__</span></code> is a special method that Python recognizes. If given, this handles extra arguments
when you instantiate a new Monster. We have it add an argument <codeclass="docutils literal notranslate"><spanclass="pre">key</span></code> that we store on <codeclass="docutils literal notranslate"><spanclass="pre">self</span></code>.</p>
<p>Now, for Evennia to see this code change, we need to reload the server. You can either do it this
<p>Or you can use a separate terminal and restart from outside the game:</p>
<asideclass="sidebar">
<pclass="sidebar-title">On reloading</p>
<p>Reloading with the python mode gets a little annoying since you need to redo everything after every reload. Just keep in mind that during regular development you will not be working this way. The in-game python mode is practical for quick fixes and experiments like this, but actual code is normally written externally, in python modules.</p>
<p>Now we passed <codeclass="docutils literal notranslate"><spanclass="pre">"Fluffy"</span></code> as an argument to the class. This went into <codeclass="docutils literal notranslate"><spanclass="pre">__init__</span></code> and set <codeclass="docutils literal notranslate"><spanclass="pre">self.key</span></code>, which we later used to print with the right name!</p>
<h3><spanclass="section-number">5.2.2. </span>What’s so good about objects?<aclass="headerlink"href="#whats-so-good-about-objects"title="Permalink to this headline">¶</a></h3>
<p>So far all we’ve seen a class do is to behave like our first <codeclass="docutils literal notranslate"><spanclass="pre">hello_world</span></code> function but being more complex. We could just have made a function:</p>
<spanclass="nb">print</span><spanclass="p">(</span><spanclass="sa">f</span><spanclass="s2">"</span><spanclass="si">{</span><spanclass="n">key</span><spanclass="si">}</span><spanclass="s2"> is moving!"</span><spanclass="p">)</span>
</pre></div>
</div>
<p>The difference between the function and an instance of a class (the object), is that the
object retains <em>state</em>. Once you called the function it forgets everything about what you called
it with last time. The object, on the other hand, remembers changes:</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">fluffy</span></code> object’s <codeclass="docutils literal notranslate"><spanclass="pre">key</span></code> was changed for as long as it’s around. This makes objects extremely useful for representing and remembering collections of data - some of which can be other
<li><p>A player character with all its stats</p></li>
<li><p>A monster with HP</p></li>
<li><p>A chest with a number of gold coins in it</p></li>
<li><p>A room with other objects inside it</p></li>
<li><p>The current policy positions of a political party</p></li>
<li><p>A rule with methods for resolving challenges or roll dice</p></li>
<li><p>A multi-dimenstional data-point for a complex economic simulation</p></li>
<li><p>And so much more!</p></li>
</ul>
</section>
<sectionid="classes-can-have-children">
<h3><spanclass="section-number">5.2.3. </span>Classes can have children<aclass="headerlink"href="#classes-can-have-children"title="Permalink to this headline">¶</a></h3>
<p>Classes can <em>inherit</em> from each other. A “child” class will inherit everything from its “parent” class. But if the child adds something with the same name as its parent, it will <em>override</em> whatever it got from its parent.</p>
<spanclass="nb">print</span><spanclass="p">(</span><spanclass="sa">f</span><spanclass="s2">"</span><spanclass="si">{</span><spanclass="bp">self</span><spanclass="o">.</span><spanclass="n">key</span><spanclass="si">}</span><spanclass="s2"> is moving!"</span><spanclass="p">)</span>
<spanclass="nb">print</span><spanclass="p">(</span><spanclass="sa">f</span><spanclass="s2">"</span><spanclass="si">{</span><spanclass="bp">self</span><spanclass="o">.</span><spanclass="n">key</span><spanclass="si">}</span><spanclass="s2"> flies through the air high above!"</span><spanclass="p">)</span>
<p>We added some docstrings for clarity. It’s always a good idea to add doc strings; you can do so also for methods, as exemplified for the new <codeclass="docutils literal notranslate"><spanclass="pre">firebreath</span></code> method.</p>
<p>We created the new class <codeclass="docutils literal notranslate"><spanclass="pre">Dragon</span></code> but we also specified that <codeclass="docutils literal notranslate"><spanclass="pre">Monster</span></code> is the <em>parent</em> of <codeclass="docutils literal notranslate"><spanclass="pre">Dragon</span></code> but adding
the parent in parenthesis. <codeclass="docutils literal notranslate"><spanclass="pre">class</span><spanclass="pre">Classname(Parent)</span></code> is the way to do this.</p>
<asideclass="sidebar">
<pclass="sidebar-title">Multi-inheritance</p>
<p>It’s possible to add more comma-separated parents to a class. You should usually avoid this until you <codeclass="docutils literal notranslate"><spanclass="pre">really</span></code> know what you are doing. A single parent will be enough for almost every case you’ll need.</p>
<p>Because we didn’t (re)implement <codeclass="docutils literal notranslate"><spanclass="pre">__init__</span></code> in <codeclass="docutils literal notranslate"><spanclass="pre">Dragon</span></code>, we got the one from <codeclass="docutils literal notranslate"><spanclass="pre">Monster</span></code>. We did implement our own <codeclass="docutils literal notranslate"><spanclass="pre">move_around</span></code> in <codeclass="docutils literal notranslate"><spanclass="pre">Dragon</span></code>, so it <em>overrides</em> the one in <codeclass="docutils literal notranslate"><spanclass="pre">Monster</span></code>. And <codeclass="docutils literal notranslate"><spanclass="pre">firebreath</span></code> is only available for <codeclass="docutils literal notranslate"><spanclass="pre">Dragon</span></code>s. Having that on <codeclass="docutils literal notranslate"><spanclass="pre">Monster</span></code> would not have made much sense, since not every monster can breathe fire.</p>
<p>One can also force a class to use resources from the parent even if you are overriding some of it. This is done with the <codeclass="docutils literal notranslate"><spanclass="pre">super()</span></code> method. Modify your <codeclass="docutils literal notranslate"><spanclass="pre">Dragon</span></code> class as follows:</p>
<div><p>Keep <codeclass="docutils literal notranslate"><spanclass="pre">Monster</span></code> and the <codeclass="docutils literal notranslate"><spanclass="pre">firebreath</span></code> method. The <codeclass="docutils literal notranslate"><spanclass="pre">#</span><spanclass="pre">...</span></code> above indicates the rest of the code is unchanged.</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">super().move_around()</span></code> line means that we are calling <codeclass="docutils literal notranslate"><spanclass="pre">move_around()</span></code> on the parent of the class. So in this case, we will call <codeclass="docutils literal notranslate"><spanclass="pre">Monster.move_around</span></code> first, before doing our own thing.</p>
<p>To see, <codeclass="docutils literal notranslate"><spanclass="pre">reload</span></code> the server and then:</p>
<p>We can see that <codeclass="docutils literal notranslate"><spanclass="pre">Monster.move_around()</span></code> is called first and prints “Smaug is moving!”, followed by the extra bit about the trembling world from the <codeclass="docutils literal notranslate"><spanclass="pre">Dragon</span></code> class.</p>
<p>Inheritance is a powerful concept. It allows you to organize and re-use code while only adding the special things you want to change. Evennia uses this a lot.</p>
<p>We have created our first dragons from classes. We have learned a little about how you <em>instantiate</em> a class into an <em>object</em>. We have seen some examples of <em>inheritance</em> and we tested to <em>override</em> a method in the parent with one in the child class. We also used <codeclass="docutils literal notranslate"><spanclass="pre">super()</span></code> to good effect.</p>
<p>We have used pretty much raw Python so far. In the coming lessons we’ll start to look at the extra bits that Evennia provides. But first we need to learn just where to find everything.</p>
