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

Updated HTML docs.

Browse source
This commit is contained in:
Evennia docbuilder action 2022-11-20 00:44:59 +00:00
parent c758f0d402
commit 57f411a6fa
95 changed files with 1370 additions and 2035 deletions
Download patch file Download diff file Expand all files Collapse all files

58
docs/1.0-dev/Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Python-basic-introduction.html
View file

@ -198,7 +198,7 @@ This is a good idea!
<aside class="sidebar">
<p class="sidebar-title">Functions and Methods</p>
<ul class="simple">
<li><p>Function: Something that performs and action when you <code class="docutils literal notranslate"><span class="pre">call</span></code> it with zero or more <code class="docutils literal notranslate"><span class="pre">arguments</span></code>. A function is stand-alone in a python module, like <code class="docutils literal notranslate"><span class="pre">print()</span></code></p></li>
<li><p>Function: Something that performs and action when you call it with zero or more <code class="docutils literal notranslate"><span class="pre">arguments</span></code>. A function is stand-alone in a python module, like <code class="docutils literal notranslate"><span class="pre">print()</span></code></p></li>
<li><p>Method: A function that sits “on” an object, like <code class="docutils literal notranslate"><span class="pre">obj.msg()</span></code>.</p></li>
</ul>
</aside>
@ -242,21 +242,24 @@ trouble, use the Evennia web client.</p>
</div>
<p>What happened here was that we <em>assigned</em> the string <code class="docutils literal notranslate"><span class="pre">&quot;awesome</span> <span class="pre">sauce&quot;</span></code> to a <em>variable</em> we chose
to name <code class="docutils literal notranslate"><span class="pre">a</span></code>. In the next statement, Python remembered what <code class="docutils literal notranslate"><span class="pre">a</span></code> was and we passed that into <code class="docutils literal notranslate"><span class="pre">format()</span></code>
to get the output. If you replaced the value of <code class="docutils literal notranslate"><span class="pre">a</span></code> with something else in between, <em>that</em> would be printed
instead.</p>
to get the output. If you replaced the value of <code class="docutils literal notranslate"><span class="pre">a</span></code> with something else in between, <em>that</em> would be printed instead.</p>
<p>Here’s the stat-example again, moving the stats to variables (here we just set them, but in a real
game they may be changed over time, or modified by circumstance):</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>&gt; py stren, dext, intel = 13, 14, 8 ; print(&quot;STR: {}, DEX: {}, INT: {}&quot;.format(stren, dext, intel))
STR: 13, DEX: 14, INT: 8
</pre></div>
</div>
<p>The point is that even if the values of the stats change, the print() statement would not change - it just keeps
pretty-printing whatever is given to it.</p>
<p>The point is that even if the values of the stats change, the print() statement would not change - it just keeps pretty-printing whatever is given to it.</p>
<p>You can also use named markers, like this:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> &gt; py print(&quot;STR: {stren}, INT: {intel}, STR again: {stren}&quot;.format(dext=10, intel=18, stren=9))
STR: 9, INT: 18, Str again: 9
</pre></div>
</div>
<p>the <code class="docutils literal notranslate"><span class="pre">key=value</span></code> pairs we add are called <em>keyword arguments</em> for the <code class="docutils literal notranslate"><span class="pre">format()</span></code> method. Each named argument will go to the matching <code class="docutils literal notranslate"><span class="pre">{key}</span></code> in the string. When using keywords, the order we add them doesn’t matter. We have no <code class="docutils literal notranslate"><span class="pre">{dext}</span></code> and two <code class="docutils literal notranslate"><span class="pre">{stren}</span></code> in the string, and that works fine.</p>
</section>
<section id="f-strings">
<h3><span class="section-number">3.2.2. </span>f-strings<a class="headerlink" href="#f-strings" title="Permalink to this headline"></a></h3>
<p>Using <code class="docutils literal notranslate"><span class="pre">.format()</span></code> is convenient (and there is a <a class="reference external" href="https://www.w3schools.com/python/ref_string_format.asp">lot more</a>
you can do with it). But the <em>f-string</em> can be even more convenient. An
<p>Using <code class="docutils literal notranslate"><span class="pre">.format()</span></code> is convenient (and there is a <a class="reference external" href="https://www.w3schools.com/python/ref_string_format.asp">lot more</a> you can do with it). But the <em>f-string</em> can be even more convenient. An
f-string looks like a normal string … except there is an <code class="docutils literal notranslate"><span class="pre">f</span></code> front of it, like this:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>f&quot;this is now an f-string.&quot;
</pre></div>
@ -266,7 +269,7 @@ f-string looks like a normal string … except there is an <code class="docutils
This is awesome sauce!
</pre></div>
</div>
<p>We could just insert that <code class="docutils literal notranslate"><span class="pre">a</span></code> variable directly into the f-string using <code class="docutils literal notranslate"><span class="pre">{a}</span></code>. Fewer parentheses to
<p>We insert that <code class="docutils literal notranslate"><span class="pre">a</span></code> variable directly into the f-string using <code class="docutils literal notranslate"><span class="pre">{a}</span></code>. Fewer parentheses to
remember and arguable easier to read as well.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>&gt; py stren, dext, intel = 13, 14, 8 ; print(f&quot;STR: {stren}, DEX: {dext}, INT: {intel}&quot;)
STR: 13, DEX: 14, INT: 8
@ -291,7 +294,7 @@ gives the normal text color. You can also use RGB (Red-Green-Blue) values from 0
<div><p>If you don’t see the expected color, your client or terminal may not support Xterm256 (or
color at all). Use the Evennia webclient.</p>
</div></blockquote>
<p>Use the commands <code class="docutils literal notranslate"><span class="pre">color</span> <span class="pre">ansi</span></code> or <code class="docutils literal notranslate"><span class="pre">color</span> <span class="pre">xterm</span></code> to see which colors are available. Experiment!</p>
<p>Use the commands <code class="docutils literal notranslate"><span class="pre">color</span> <span class="pre">ansi</span></code> or <code class="docutils literal notranslate"><span class="pre">color</span> <span class="pre">xterm</span></code> to see which colors are available. Experiment! You can also read a lot more in the <a class="reference internal" href="../../../Concepts/Colors.html"><span class="doc std std-doc">Colors</span></a> documentation.</p>
</section>
</section>
<section id="importing-code-from-other-modules">
@ -326,21 +329,15 @@ Hello World
<p>If you make some error (we’ll cover how to handle errors below), fix the error in the module and
run the <code class="docutils literal notranslate"><span class="pre">reload</span></code> command in-game for your changes to take effect.</p>
<p>So importing <code class="docutils literal notranslate"><span class="pre">world.test</span></code> actually means importing <code class="docutils literal notranslate"><span class="pre">world/test.py</span></code>. Think of the period <code class="docutils literal notranslate"><span class="pre">.</span></code> as
replacing <code class="docutils literal notranslate"><span class="pre">/</span></code> (or <code class="docutils literal notranslate"><span class="pre">\</span></code> for Windows) in your path. The <code class="docutils literal notranslate"><span class="pre">.py</span></code> ending of <code class="docutils literal notranslate"><span class="pre">test.py</span></code> is also never
included in this “Python-path”, but <em>only</em> files with that ending can be imported this way.
Where is <code class="docutils literal notranslate"><span class="pre">mygame</span></code> in that Python-path? The answer is that Evennia has already told Python that
your <code class="docutils literal notranslate"><span class="pre">mygame</span></code> folder is a good place to look for imports. So we don’t include <code class="docutils literal notranslate"><span class="pre">mygame</span></code> in the
path - Evennia handles this for us.</p>
replacing <code class="docutils literal notranslate"><span class="pre">/</span></code> (or <code class="docutils literal notranslate"><span class="pre">\</span></code> for Windows) in your path.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">.py</span></code> ending of <code class="docutils literal notranslate"><span class="pre">test.py</span></code> is never included in this “Python-path”, but <em>only</em> files with that ending can be imported this way. Where is <code class="docutils literal notranslate"><span class="pre">mygame</span></code> in that Python-path? The answer is that Evennia has already told Python that your <code class="docutils literal notranslate"><span class="pre">mygame</span></code> folder is a good place to look for imports. So we should not include <code class="docutils literal notranslate"><span class="pre">mygame</span></code> in the path - Evennia handles this for us.</p>
<p>When you import the module, the top “level” of it will execute. In this case, it will immediately
print “Hello World”.</p>
<p>Now try to run this a second time:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>&gt; py import world.test
</pre></div>
</div>
<p>You will <em>not</em> see any output this second time or any subsequent times! This is not a bug. Rather
it is because of how Python importing works - it stores all imported modules and will
avoid importing them more than once. So your <code class="docutils literal notranslate"><span class="pre">print</span></code> will only run the first time, when the module
is first imported.</p>
<p>You will <em>not</em> see any output this or any subsequent times! This is not a bug. Rather it is because of how Python importing works - it stores all imported modules and will avoid importing them more than once. So your <code class="docutils literal notranslate"><span class="pre">print</span></code> will only run the first time, when the module is first imported.</p>
<p>Try this:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>&gt; reload
</pre></div>
@ -354,8 +351,7 @@ Hello World!
import it anew. You’d have to do this every time you wanted the print to show though, which is
not very useful.</p>
<blockquote>
<div><p>We’ll get back to more advanced ways to import code in later tutorial sections - this is an
important topic. But for now, let’s press on and resolve this particular problem.</p>
<div><p>We’ll get back to more advanced ways to import code in <a class="reference internal" href="Beginner-Tutorial-Python-classes-and-objects.html#importing-things"><span class="std std-doc">a later lesson</span></a> - this is an important topic. But for now, let’s press on and resolve this particular problem.</p>
</div></blockquote>
<section id="our-first-own-function">
<h3><span class="section-number">3.3.1. </span>Our first own function<a class="headerlink" href="#our-first-own-function" title="Permalink to this headline"></a></h3>
@ -528,8 +524,8 @@ the room it is in.</p>
<aside class="sidebar">
<p class="sidebar-title">Creating objects</p>
<p>The <code class="docutils literal notranslate"><span class="pre">create</span></code> command was first used to create boxes in the
<code class="docutils literal notranslate"><span class="pre">Building</span> <span class="pre">Stuff</span> <span class="pre">&lt;Building-Quickstart&gt;</span></code>_ tutorial. Note how it
uses a “python-path” to describe where to load the mirror’s code from.</p>
<a class="reference internal" href="Beginner-Tutorial-Building-Quickstart.html"><span class="doc std std-doc">Building Stuff</span></a> tutorial. You should now recognize
that it uses a “python-path” to tell Evennia where to load the mirror’s code from.</p>
</aside>
<p>A mirror should appear in your location.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>&gt; look mirror
@ -585,7 +581,7 @@ when you want to do some quick testing. But you can also start a full multi-line
inside Evennia.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>&gt; py
Evennia Interactive Python mode
Python 3.7.1 (default, Oct 22 2018, 11:21:55)
Python 3.11.0 (default, Nov 22 2022, 11:21:55)
[GCC 8.2.0] on Linux
[py mode - quit() to exit]
</pre></div>
@ -600,14 +596,12 @@ Hello World
[py mode - quit() to exit]
</pre></div>
</div>
<p>Note that we didn’t need to put <code class="docutils literal notranslate"><span class="pre">py</span></code> in front now. The system will also echo your input (that’s the bit after
the <code class="docutils literal notranslate"><span class="pre">&gt;&gt;&gt;</span></code>). For brevity in this tutorual we’ll turn the echo off. First exit <code class="docutils literal notranslate"><span class="pre">py</span></code> and then start again with the
<code class="docutils literal notranslate"><span class="pre">/noecho</span></code> flag.</p>
<p>Note that we didn’t need to put <code class="docutils literal notranslate"><span class="pre">py</span></code> in front now. The system will also echo your input (that’s the bit after the <code class="docutils literal notranslate"><span class="pre">&gt;&gt;&gt;</span></code>). For brevity in this tutorual we’ll turn the echo off. First exit <code class="docutils literal notranslate"><span class="pre">py</span></code> and then start again with the <code class="docutils literal notranslate"><span class="pre">/noecho</span></code> flag.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>&gt; quit()
Closing the Python console.
&gt; py/noecho
Evennia Interactive Python mode (no echoing of prompts)
Python 3.7.1 (default, Oct 22 2018, 11:21:55)
Python 3.11.0 (default, Nov 22 2022, 11:21:56)
[GCC 8.2.0] on Linux
[py mode - quit() to exit]
</pre></div>
@ -617,13 +611,13 @@ Python 3.7.1 (default, Oct 22 2018, 11:21:55)
<ul class="simple">
<li><p>Start with <code class="docutils literal notranslate"><span class="pre">py</span></code>.</p></li>
<li><p>Use <code class="docutils literal notranslate"><span class="pre">py/noecho</span></code> if you don’t want your input to be echoed for every line.</p></li>
<li><p>All your inputs will now be interpreted as Python code.</p></li>
<li><p><em>All</em> your inputs will now be interpreted as Python code.</p></li>
<li><p>Exit with <code class="docutils literal notranslate"><span class="pre">quit()</span></code>.</p></li>
</ul>
</aside>
<p>We can now enter multi-line Python code:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>&gt; a = &quot;Test&quot;
&gt; print(f&quot;This is a {a}.&quot;}
&gt; print(f&quot;This is a {a}.&quot;)
This is a Test.
</pre></div>
</div>
@ -643,8 +637,7 @@ of the block with indention. So the next line must be manually indented (4 space
for Python to know it’s part of the function body.</p></li>
<li><p>We expand the <code class="docutils literal notranslate"><span class="pre">hello_world</span></code> function with another argument <code class="docutils literal notranslate"><span class="pre">txt</span></code>. This allows us to send any text, not just
“Hello World” over and over.</p></li>
<li><p>To tell <code class="docutils literal notranslate"><span class="pre">py</span></code> that no more lines will be added to the function body, we end with an empty input. When
the normal prompt on how to exit returns, we know we are done.</p></li>
<li><p>To tell <code class="docutils literal notranslate"><span class="pre">py</span></code> that no more lines will be added to the function body, we end with an empty input. When the normal prompt returns, we know we are done.</p></li>
</ul>
<p>Now we have defined a new function. Let’s try it out:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>&gt; hello_world(me, &quot;Hello world to me!&quot;)
@ -731,8 +724,7 @@ Python code, we need to save it in a Python module, like we did for <code class=
first function, fixed an error and even searched and talked to a mirror! Being able to access
python inside and outside of the game is an important skill for testing and debugging, but in
practice you will be writing most your code in Python modules.</p>
<p>To that end we also created a first new Python module in the <code class="docutils literal notranslate"><span class="pre">mygame/</span></code> game dir, then imported and used it.
Now let’s look at the rest of the stuff you’ve got going on inside that <code class="docutils literal notranslate"><span class="pre">mygame/</span></code> folder …</p>
<p>To that end we also created a first new Python module in the <code class="docutils literal notranslate"><span class="pre">mygame/</span></code> game dir, then imported and used it. Now let’s look at the rest of the stuff you’ve got going on inside that <code class="docutils literal notranslate"><span class="pre">mygame/</span></code> folder …</p>
</section>
</section>