Andreas/evennia
1
0
Fork 0
mirror of https://github.com/evennia/evennia.git synced 2026-03-19 06:16:31 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

Updated HTML docs.

Browse source
This commit is contained in:
Evennia docbuilder action 2023-01-28 13:56:40 +00:00
parent 46958ab64f
commit be3ce6ca81
34 changed files with 241 additions and 177 deletions
Download patch file Download diff file Expand all files Collapse all files

111
docs/1.0/Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Python-classes-and-objects.html
View file

@ -69,6 +69,7 @@
<li><a class="reference internal" href="#classes-and-instances">5.2.1. Classes and instances</a></li>
<li><a class="reference internal" href="#whats-so-good-about-objects">5.2.2. What’s so good about objects?</a></li>
<li><a class="reference internal" href="#classes-can-have-children">5.2.3. Classes can have children</a></li>
<li><a class="reference internal" href="#a-look-at-multiple-inheritance">5.2.4. A look at multiple inheritance</a></li>
</ul>
</li>
<li><a class="reference internal" href="#summary">5.3. Summary</a></li>
@ -195,8 +196,7 @@ 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><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 <a class="reference internal" href="Beginner-Tutorial-Python-basic-introduction.html"><span class="doc std std-doc">the basic intro to Python</span></a> we learned how to open the in-game
multi-line interpreter.</p>
@ -219,25 +219,23 @@ Hello World!
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>
<aside class="sidebar">
<p class="sidebar-title">Alternative to py </p>
<p>If you find entering multiple lines in the <code class="docutils literal notranslate"><span class="pre">py</span></code> command clunky (a traditional mud client is pretty limited for this kind of thing) you can also <code class="docutils literal notranslate"><span class="pre">cd</span></code> to your <code class="docutils literal notranslate"><span class="pre">mygame</span></code> folder and run <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">shell</span></code>. You will end up in a python shell where Evennia is available. If you do <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">ipython</span></code> you’ll get an even more modern python shell to use. This works outside the game but <code class="docutils literal notranslate"><span class="pre">print</span></code> will show in the same way.</p>
</aside>
<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>
<section id="on-classes-and-objects">
<h2><span class="section-number">5.2. </span>On classes and objects<a class="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 <code class="docutils literal notranslate"><span class="pre">mygame/typeclasses/objects.py</span></code> in your text editor of choice.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="sd">&quot;&quot;&quot;</span>
<p>Open <code class="docutils literal notranslate"><span class="pre">mygame/typeclasses/scripts.py</span></code> in your text editor of choice.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># mygame/typeclasses/script.py</span>
<span class="sd">&quot;&quot;&quot;</span>
<span class="sd">module docstring</span>
<span class="sd">&quot;&quot;&quot;</span>
<span class="kn">from</span> <span class="nn">evennia</span> <span class="kn">import</span> <span class="n">DefaultObject</span>
<span class="kn">from</span> <span class="nn">evennia</span> <span class="kn">import</span> <span class="n">DefaultScript</span>
<span class="k">class</span> <span class="nc">ObjectParent</span><span class="p">:</span>
<span class="w"> </span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> class docstring </span>
<span class="sd"> &quot;&quot;&quot;</span>
<span class="k">pass</span>
<span class="k">class</span> <span class="nc">Object</span><span class="p">(</span><span class="n">DefaultObject</span><span class="p">):</span>
<span class="k">class</span> <span class="nc">Script</span><span class="p">(</span><span class="n">DefaultScript</span><span class="p">):</span>
<span class="w"> </span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> class docstring</span>
<span class="sd"> &quot;&quot;&quot;</span>
@ -248,15 +246,12 @@ imports at the top, resources that are then used by all code in that module.</p>
<p class="sidebar-title">Docstrings vs Comments</p>
<p>A docstring is not the same as a comment (created by <code class="docutils literal notranslate"><span class="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 <a class="reference internal" href="../../../Evennia-API.html"><span class="doc std std-doc">API documentation</span></a>; we could not do that with comments.</p>
</aside>
<p>The real file is much longer but we can ignore the multi-line strings (<code class="docutils literal notranslate"><span class="pre">&quot;&quot;&quot;</span> <span class="pre">...</span> <span class="pre">&quot;&quot;&quot;</span></code>). These serve
as documentation-strings, or <em>docstrings</em> for the module (at the top) and the <code class="docutils literal notranslate"><span class="pre">class</span></code> below.</p>
<p>Below the module doc string we have the import. In this case we are importing a resource
<p>The real file is much longer but we can ignore the multi-line strings (<code class="docutils literal notranslate"><span class="pre">&quot;&quot;&quot;</span> <span class="pre">...</span> <span class="pre">&quot;&quot;&quot;</span></code>). These serve as documentation-strings, or <em>docstrings</em> for the module (at the top) and the <code class="docutils literal notranslate"><span class="pre">class</span></code> below.</p>
<p>Below the module doc string we have the <em>import</em>. In this case we are importing a resource
from the core <code class="docutils literal notranslate"><span class="pre">evennia</span></code> library itself. We will dive into this later, for now we just treat this
as a black box.</p>
<p>Next we have an empty <code class="docutils literal notranslate"><span class="pre">class</span></code> named <code class="docutils literal notranslate"><span class="pre">ObjectParent</span></code>. It doesn’t do anything, its only code (except the docstring) is <code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">class</span></code> named <code class="docutils literal notranslate"><span class="pre">Object</span></code>_ inherits_ from <code class="docutils literal notranslate"><span class="pre">ObjectParent</span></code> and <code class="docutils literal notranslate"><span class="pre">DefaultObject</span></code>. Since we see that <code class="docutils literal notranslate"><span class="pre">ObjectParent</span></code> is empty, what is interesting is <code class="docutils literal notranslate"><span class="pre">DefaultObject</span></code>. Again, the <code class="docutils literal notranslate"><span class="pre">Object</span></code> class doesn’t
actually do anything on its own right now, but because of it being a child of <code class="docutils literal notranslate"><span class="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 <a class="reference internal" href="Beginner-Tutorial-Learning-Typeclasses.html"><span class="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>The <code class="docutils literal notranslate"><span class="pre">class</span></code> named <code class="docutils literal notranslate"><span class="pre">Script</span></code> _ inherits_ from <code class="docutils literal notranslate"><span class="pre">DefaultScript</span></code>. As you can see <code class="docutils literal notranslate"><span class="pre">Script</span></code> is pretty much empty. All the useful code is actually in <code class="docutils literal notranslate"><span class="pre">DefaultScript</span></code> (<code class="docutils literal notranslate"><span class="pre">Script</span></code> <em>inherits</em> that code unless it <em>overrides</em> it with same-named code of its own).</p>
<p>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>
<aside class="sidebar">
<p class="sidebar-title">OOP</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>
@ -278,8 +273,7 @@ actually do anything on its own right now, but because of it being a child of <c
<p>Above we have defined a <code class="docutils literal notranslate"><span class="pre">Monster</span></code> class with one variable <code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">self</span></code> although you could in principle use
another name), which is a reference back to itself. So when we print <code class="docutils literal notranslate"><span class="pre">self.key</span></code> we are referring
back to the <code class="docutils literal notranslate"><span class="pre">key</span></code> on the class.</p>
another name), which is a reference back to itself. So when we print <code class="docutils literal notranslate"><span class="pre">self.key</span></code> we are referring back to the <code class="docutils literal notranslate"><span class="pre">key</span></code> on the class.</p>
<aside class="sidebar">
<p class="sidebar-title">Terms</p>
<ul class="simple">
@ -293,7 +287,7 @@ by <em>calling</em> the class, much like you would a function:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>fluffy = Monster()
</pre></div>
</div>
<p>Let’s try it in-game (we use multi-line mode, it’s easier)</p>
<p>Let’s try it in-game (we use <code class="docutils literal notranslate"><span class="pre">py</span></code> multi-line mode, it’s easier)</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>&gt; py
&gt; from typeclasses.monsters import Monster
&gt; fluffy = Monster()
@ -304,9 +298,7 @@ Monster is moving!
<p>We created an <em>instance</em> of <code class="docutils literal notranslate"><span class="pre">Monster</span></code>, which we stored in the variable <code class="docutils literal notranslate"><span class="pre">fluffy</span></code>. We then
called the <code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">fluffy.move_around(self)</span></code>. While the <code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">self</span></code> for us automatically behind the scenes).</p>
<div><p>Note how we <em>didn’t</em> call the method as <code class="docutils literal notranslate"><span class="pre">fluffy.move_around(self)</span></code>. While the <code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">self</span></code> for us automatically behind the scenes).</p>
</div></blockquote>
<p>Let’s create the sibling of Fluffy, Cuddly:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>&gt; cuddly = Monster()
@ -314,8 +306,8 @@ will add the correct <code class="docutils literal notranslate"><span class="pre
Monster is moving!
</pre></div>
</div>
<p>We now have two dragons and they’ll hang around until with call <code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">key</span></code> is always fixed as “Monster”.</p>
<p>We now have two monsters and they’ll hang around until with call <code class="docutils literal notranslate"><span class="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 monsters we create, they will all show the same printout since <code class="docutils literal notranslate"><span class="pre">key</span></code> is always fixed as “Monster”.</p>
<p>Let’s make the class a little more flexible:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span>
<span class="k">class</span> <span class="nc">Monster</span><span class="p">:</span>
@ -328,10 +320,8 @@ instance. We can have them move as many times as we want. But no matter how many
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">key</span></code> that we store on <code class="docutils literal notranslate"><span class="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
way:</p>
<p>The <code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">key</span></code> that we store on <code class="docutils literal notranslate"><span class="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 way:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>&gt; quit()
Python Console is closing.
&gt; reload
@ -362,16 +352,13 @@ Fluffy is moving!
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;</span><span class="si">{</span><span class="n">key</span><span class="si">}</span><span class="s2"> is moving!&quot;</span><span class="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 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>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>&gt; fluffy.key = &quot;Fluffy, the red dragon&quot;
&gt; fluffy.move_around()
Fluffy, the red dragon is moving!
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">fluffy</span></code> object’s <code class="docutils literal notranslate"><span class="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
objects in turn. Some examples:</p>
<p>The <code class="docutils literal notranslate"><span class="pre">fluffy</span></code> object’s <code class="docutils literal notranslate"><span class="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 objects in turn. Some examples:</p>
<ul class="simple">
<li><p>A player character with all its stats</p></li>
<li><p>A monster with HP</p></li>
@ -417,11 +404,10 @@ objects in turn. Some examples:</p>
</pre></div>
</div>
<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 <code class="docutils literal notranslate"><span class="pre">firebreath</span></code> method.</p>
<p>We created the new class <code class="docutils literal notranslate"><span class="pre">Dragon</span></code> but we also specified that <code class="docutils literal notranslate"><span class="pre">Monster</span></code> is the <em>parent</em> of <code class="docutils literal notranslate"><span class="pre">Dragon</span></code> but adding
the parent in parenthesis. <code class="docutils literal notranslate"><span class="pre">class</span> <span class="pre">Classname(Parent)</span></code> is the way to do this.</p>
<p>We created the new class <code class="docutils literal notranslate"><span class="pre">Dragon</span></code> but we also specified that <code class="docutils literal notranslate"><span class="pre">Monster</span></code> is the <em>parent</em> of <code class="docutils literal notranslate"><span class="pre">Dragon</span></code> but adding the parent in parenthesis. <code class="docutils literal notranslate"><span class="pre">class</span> <span class="pre">Classname(Parent)</span></code> is the way to do this.</p>
<aside class="sidebar">
<p class="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 <code class="docutils literal notranslate"><span class="pre">really</span></code> know what you are doing. A single parent will be enough for almost every case you’ll need.</p>
<p>It’s possible to add more comma-separated parents to a class. We show an example of such ‘multiple inheritance’ last in this lesson. You should usually avoid yourself setting up multiple inheritance until you know what you are doing. A single parent will be enough for almost every case you’ll need.</p>
</aside>
<p>Let’s try out our new class. First <code class="docutils literal notranslate"><span class="pre">reload</span></code> the server and then:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>&gt; py
@ -462,6 +448,49 @@ The world trembles.
<p>We can see that <code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="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>
</section>
<section id="a-look-at-multiple-inheritance">
<h3><span class="section-number">5.2.4. </span>A look at multiple inheritance<a class="headerlink" href="#a-look-at-multiple-inheritance" title="Permalink to this headline"></a></h3>
<p>Open <code class="docutils literal notranslate"><span class="pre">mygame/typeclasses/objects.py</span></code> in your text editor of choice.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd">module docstring</span>
<span class="sd">&quot;&quot;&quot;</span>
<span class="kn">from</span> <span class="nn">evennia</span> <span class="kn">import</span> <span class="n">DefaultObject</span>
<span class="k">class</span> <span class="nc">ObjectParent</span><span class="p">:</span>
<span class="w"> </span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> class docstring </span>
<span class="sd"> &quot;&quot;&quot;</span>
<span class="k">pass</span>
<span class="k">class</span> <span class="nc">Object</span><span class="p">(</span><span class="n">ObjectParent</span><span class="p">,</span> <span class="n">DefaultObject</span><span class="p">):</span>
<span class="w"> </span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> class docstring</span>
<span class="sd"> &quot;&quot;&quot;</span>
<span class="k">pass</span>
</pre></div>
</div>
<p>In this module we have an empty <code class="docutils literal notranslate"><span class="pre">class</span></code> named <code class="docutils literal notranslate"><span class="pre">ObjectParent</span></code>. It doesn’t do anything, its only code (except the docstring) is <code class="docutils literal notranslate"><span class="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.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">class</span></code> named <code class="docutils literal notranslate"><span class="pre">Object</span></code>_ inherits_ from <code class="docutils literal notranslate"><span class="pre">ObjectParent</span></code> and <code class="docutils literal notranslate"><span class="pre">DefaultObject</span></code>. Normally a class only has one parent, but here there are two. We already learned that a child inherits everything from a parent unless it overrides it. When there are more than one parents (“multiple inheritance”), inheritance happens from left to right.</p>
<p>So if <code class="docutils literal notranslate"><span class="pre">obj</span></code> is an instance of <code class="docutils literal notranslate"><span class="pre">Object</span></code> and we try to access <code class="docutils literal notranslate"><span class="pre">obj.foo</span></code>, Python will first check if the <code class="docutils literal notranslate"><span class="pre">Object</span></code> class has a property/method <code class="docutils literal notranslate"><span class="pre">foo</span></code>. Next it will check if <code class="docutils literal notranslate"><span class="pre">ObjectParent</span></code> has it. Finally, it will check in <code class="docutils literal notranslate"><span class="pre">DefaultObject</span></code>. If neither have it, you get an error.</p>
<p>Why has Evennia set up an empty class parent like this? To answer, let’s check out another module, <code class="docutils literal notranslate"><span class="pre">mygame/typeclasses/rooms.py</span></code>:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd">...</span>
<span class="sd">&quot;&quot;&quot;</span>
<span class="kn">from</span> <span class="nn">evennia.objects.objects</span> <span class="kn">import</span> <span class="n">DefaultRoom</span>
<span class="kn">from</span> <span class="nn">.objects</span> <span class="kn">import</span> <span class="n">ObjectParent</span>
<span class="k">class</span> <span class="nc">Room</span><span class="p">(</span><span class="n">ObjectParent</span><span class="p">,</span> <span class="n">DefaultRoom</span><span class="p">):</span>
<span class="w"> </span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> ...</span>
<span class="sd"> &quot;&quot;&quot;</span>
<span class="k">pass</span>
</pre></div>
</div>
<p>Here we see that a <code class="docutils literal notranslate"><span class="pre">Room</span></code> inherits from the same <code class="docutils literal notranslate"><span class="pre">ObjectParent</span></code> (imported from <code class="docutils literal notranslate"><span class="pre">objects.py</span></code>) along with a <code class="docutils literal notranslate"><span class="pre">DefaultRoom</span></code> parent from the <code class="docutils literal notranslate"><span class="pre">evennia</span></code> library. You’ll find the same is true for <code class="docutils literal notranslate"><span class="pre">Character</span></code> and <code class="docutils literal notranslate"><span class="pre">Exit</span></code> as well. These are all examples of ‘in-game objects’, so they could well have a lot in common. The precense of <code class="docutils literal notranslate"><span class="pre">ObjectParent</span></code> gives you an (optional) way to add code that <em>should be the same for all those in-game entities</em>. Just put that code in <code class="docutils literal notranslate"><span class="pre">ObjectParent</span></code> and all the objects, characters, rooms and exits will automatically have it as well!</p>
<p>We will get back to the <code class="docutils literal notranslate"><span class="pre">objects.py</span></code> module in the <a class="reference internal" href="Beginner-Tutorial-Learning-Typeclasses.html"><span class="doc std std-doc">next lesson</span></a>.</p>
</section>
</section>
<section id="summary">
<h2><span class="section-number">5.3. </span>Summary<a class="headerlink" href="#summary" title="Permalink to this headline"></a></h2>