mirror of
https://github.com/evennia/evennia.git
synced 2026-03-19 06:16:31 +01:00
189 lines
No EOL
16 KiB
HTML
189 lines
No EOL
16 KiB
HTML
|
||
<!DOCTYPE html>
|
||
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<title>Execute Python Code — Evennia 0.9.1 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="execute-python-code">
|
||
<h1>Execute Python Code<a class="headerlink" href="#execute-python-code" title="Permalink to this headline">¶</a></h1>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">@py</span></code> command supplied with the default command set of Evennia allows you to execute Python commands directly from inside the game. An alias to <code class="docutils literal notranslate"><span class="pre">@py</span></code> is simply “<code class="docutils literal notranslate"><span class="pre">!</span></code>”. <em>Access to the <code class="docutils literal notranslate"><span class="pre">@py</span></code> command should be severely restricted</em>. This is no joke - being able to execute arbitrary Python code on the server is not something you should entrust to just anybody.</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@py</span> <span class="mi">1</span><span class="o">+</span><span class="mi">2</span>
|
||
<span class="o"><<<</span> <span class="mi">3</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="section" id="available-variables">
|
||
<h2>Available variables<a class="headerlink" href="#available-variables" title="Permalink to this headline">¶</a></h2>
|
||
<p>A few local variables are made available when running <code class="docutils literal notranslate"><span class="pre">@py</span></code>. These offer entry into the running system.</p>
|
||
<ul class="simple">
|
||
<li><p><strong>self</strong> / <strong>me</strong> - the calling object (i.e. you)</p></li>
|
||
<li><p><strong>here</strong> - the current caller’s location</p></li>
|
||
<li><p><strong>obj</strong> - a dummy <a class="reference internal" href="Objects.html"><span class="doc">Object</span></a> instance</p></li>
|
||
<li><p><strong>evennia</strong> - Evennia’s <a class="reference internal" href="Evennia-API.html"><span class="doc">flat API</span></a> - through this you can access all of Evennia.</p></li>
|
||
</ul>
|
||
<p>For accessing other objects in the same room you need to use <code class="docutils literal notranslate"><span class="pre">self.search(name)</span></code>. For objects in other locations, use one of the <code class="docutils literal notranslate"><span class="pre">evennia.search_*</span></code> methods. See <a class="reference external" href="/Execute-Python-Code.html#finding-objects">below</a>.</p>
|
||
</div>
|
||
<div class="section" id="returning-output">
|
||
<h2>Returning output<a class="headerlink" href="#returning-output" title="Permalink to this headline">¶</a></h2>
|
||
<p>This is an example where we import and test one of Evennia’s utilities found in <code class="docutils literal notranslate"><span class="pre">src/utils/utils.py</span></code>, but also accessible through <code class="docutils literal notranslate"><span class="pre">ev.utils</span></code>:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@py</span> <span class="kn">from</span> <span class="nn">ev</span> <span class="k">import</span> <span class="n">utils</span><span class="p">;</span> <span class="n">utils</span><span class="o">.</span><span class="n">time_format</span><span class="p">(</span><span class="mi">33333</span><span class="p">)</span>
|
||
<span class="o"><<<</span> <span class="n">Done</span><span class="o">.</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Note that we didn’t get any return value, all we where told is that the code finished executing without error. This is often the case in more complex pieces of code which has no single obvious return value. To see the output from the <code class="docutils literal notranslate"><span class="pre">time_format()</span></code> function we need to tell the system to echo it to us explicitly with <code class="docutils literal notranslate"><span class="pre">self.msg()</span></code>.</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@py</span> <span class="kn">from</span> <span class="nn">ev</span> <span class="k">import</span> <span class="n">utils</span><span class="p">;</span> <span class="bp">self</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span><span class="nb">str</span><span class="p">(</span><span class="n">utils</span><span class="o">.</span><span class="n">time_format</span><span class="p">(</span><span class="mi">33333</span><span class="p">)))</span>
|
||
<span class="mi">09</span><span class="p">:</span><span class="mi">15</span>
|
||
<span class="o"><<<</span> <span class="n">Done</span><span class="o">.</span>
|
||
</pre></div>
|
||
</div>
|
||
<blockquote>
|
||
<div><p>Warning: When using the <code class="docutils literal notranslate"><span class="pre">msg</span></code> function wrap our argument in <code class="docutils literal notranslate"><span class="pre">str()</span></code> to convert it into a string above. This is not strictly necessary for most types of data (Evennia will usually convert to a string behind the scenes for you). But for <em>lists</em> and <em>tuples</em> you will be confused by the output if you don’t wrap them in <code class="docutils literal notranslate"><span class="pre">str()</span></code>: only the first item of the iterable will be returned. This is because doing <code class="docutils literal notranslate"><span class="pre">msg(text)</span></code> is actually just a convenience shortcut; the full argument that <code class="docutils literal notranslate"><span class="pre">msg</span></code> accepts is something called an <em>outputfunc</em> on the form <code class="docutils literal notranslate"><span class="pre">(cmdname,</span> <span class="pre">(args),</span> <span class="pre">{kwargs})</span></code> (see <a class="reference internal" href="Messagepath.html"><span class="doc">the message path</span></a> for more info). Sending a list/tuple confuses Evennia to think you are sending such a structure. Converting it to a string however makes it clear it should just be displayed as-is.</p>
|
||
</div></blockquote>
|
||
<p>If you were to use Python’s standard <code class="docutils literal notranslate"><span class="pre">print</span></code>, you will see the result in your current <code class="docutils literal notranslate"><span class="pre">stdout</span></code> (your terminal by default, otherwise your log file).</p>
|
||
</div>
|
||
<div class="section" id="finding-objects">
|
||
<h2>Finding objects<a class="headerlink" href="#finding-objects" title="Permalink to this headline">¶</a></h2>
|
||
<p>A common use for <code class="docutils literal notranslate"><span class="pre">@py</span></code> is to explore objects in the database, for debugging and performing specific operations that are not covered by a particular command.</p>
|
||
<p>Locating an object is best done using <code class="docutils literal notranslate"><span class="pre">self.search()</span></code>:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@py</span> <span class="bp">self</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="s2">"red_ball"</span><span class="p">)</span>
|
||
<span class="o"><<<</span> <span class="n">Ball</span>
|
||
|
||
<span class="nd">@py</span> <span class="bp">self</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="s2">"red_ball"</span><span class="p">)</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">color</span> <span class="o">=</span> <span class="s2">"red"</span>
|
||
<span class="o"><<<</span> <span class="n">Done</span><span class="o">.</span>
|
||
|
||
<span class="nd">@py</span> <span class="bp">self</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="s2">"red_ball"</span><span class="p">)</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">color</span>
|
||
<span class="o"><<<</span> <span class="n">red</span>
|
||
</pre></div>
|
||
</div>
|
||
<p><code class="docutils literal notranslate"><span class="pre">self.search()</span></code> is by far the most used case, but you can also search other database tables for other Evennia entities like scripts or configuration entities. To do this you can use the generic search entries found in <code class="docutils literal notranslate"><span class="pre">ev.search_*</span></code>.</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@py</span> <span class="n">evennia</span><span class="o">.</span><span class="n">search_script</span><span class="p">(</span><span class="s2">"sys_game_time"</span><span class="p">)</span>
|
||
<span class="o"><<<</span> <span class="p">[</span><span class="o"><</span><span class="n">src</span><span class="o">.</span><span class="n">utils</span><span class="o">.</span><span class="n">gametime</span><span class="o">.</span><span class="n">GameTime</span> <span class="nb">object</span> <span class="n">at</span> <span class="mh">0x852be2c</span><span class="o">></span><span class="p">]</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>(Note that since this becomes a simple statement, we don’t have to wrap it in <code class="docutils literal notranslate"><span class="pre">self.msg()</span></code> to get the output). You can also use the database model managers directly (accessible through the <code class="docutils literal notranslate"><span class="pre">objects</span></code> properties of database models or as <code class="docutils literal notranslate"><span class="pre">evennia.managers.*</span></code>). This is a bit more flexible since it gives you access to the full range of database search methods defined in each manager.</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@py</span> <span class="n">evennia</span><span class="o">.</span><span class="n">managers</span><span class="o">.</span><span class="n">scripts</span><span class="o">.</span><span class="n">script_search</span><span class="p">(</span><span class="s2">"sys_game_time"</span><span class="p">)</span>
|
||
<span class="o"><<<</span> <span class="p">[</span><span class="o"><</span><span class="n">src</span><span class="o">.</span><span class="n">utils</span><span class="o">.</span><span class="n">gametime</span><span class="o">.</span><span class="n">GameTime</span> <span class="nb">object</span> <span class="n">at</span> <span class="mh">0x852be2c</span><span class="o">></span><span class="p">]</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The managers are useful for all sorts of database studies.</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@py</span> <span class="n">ev</span><span class="o">.</span><span class="n">managers</span><span class="o">.</span><span class="n">configvalues</span><span class="o">.</span><span class="n">all</span><span class="p">()</span>
|
||
<span class="o"><<<</span> <span class="p">[</span><span class="o"><</span><span class="n">ConfigValue</span><span class="p">:</span> <span class="n">default_home</span><span class="p">]</span><span class="o">></span><span class="p">,</span> <span class="o"><</span><span class="n">ConfigValue</span><span class="p">:</span><span class="n">site_name</span><span class="o">></span><span class="p">,</span> <span class="o">...</span><span class="p">]</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="testing-code-outside-the-game">
|
||
<h2>Testing code outside the game<a class="headerlink" href="#testing-code-outside-the-game" title="Permalink to this headline">¶</a></h2>
|
||
<p><code class="docutils literal notranslate"><span class="pre">@py</span></code> has the advantage of operating inside a running server (sharing the same process), where you can test things in real time. Much of this <em>can</em> be done from the outside too though.</p>
|
||
<p>In a terminal, cd to the top of your game directory (this bit is important since we need access to your config file) 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>Your default Python interpreter will start up, configured to be able to work with and import all modules of your Evennia installation. From here you can explore the database and test-run individual modules as desired.</p>
|
||
<p>It’s recommended that you get a more fully featured Python interpreter like <a class="reference external" href="http://ipython.scipy.org/moin/">iPython</a>. If you use a virtual environment, you can just get it with <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">ipython</span></code>. IPython allows you to better work over several lines, and also has a lot of other editing features, such as tab-completion and <code class="docutils literal notranslate"><span class="pre">__doc__</span></code>-string reading.</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ evennia shell
|
||
|
||
IPython 0.10 -- An enhanced Interactive Python
|
||
...
|
||
|
||
In [1]: import evennia
|
||
In [2]: evennia.managers.objects.all()
|
||
Out[3]: [<ObjectDB: Harry>, <ObjectDB: Limbo>, ...]
|
||
</pre></div>
|
||
</div>
|
||
<p>See the page about the <a class="reference internal" href="Evennia-API.html"><span class="doc">Evennia-API</span></a> for more things to explore.</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="#">Execute Python Code</a><ul>
|
||
<li><a class="reference internal" href="#available-variables">Available variables</a></li>
|
||
<li><a class="reference internal" href="#returning-output">Returning output</a></li>
|
||
<li><a class="reference internal" href="#finding-objects">Finding objects</a></li>
|
||
<li><a class="reference internal" href="#testing-code-outside-the-game">Testing code outside the game</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/Execute-Python-Code.md.txt"
|
||
rel="nofollow">Show Page Source</a></li>
|
||
</ul>
|
||
</div>
|
||
<h3>Versions</h3>
|
||
<ul>
|
||
<li><a href="../../versions/1.0-dev/index.html">1.0-dev (develop branch)</a></li>
|
||
<li><a href="Execute-Python-Code.html">0.9.1 (master branch)</a></li>
|
||
</ul>
|
||
|
||
</div>
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="footer">
|
||
©2020, The Evennia developer community.
|
||
|
||
|
|
||
Powered by <a href="http://sphinx-doc.org/">Sphinx 2.4.4</a>
|
||
& <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
||
|
||
|
|
||
<a href="_sources/Execute-Python-Code.md.txt"
|
||
rel="nofollow">Page source</a>
|
||
</div>
|
||
|
||
|
||
|
||
|
||
</body>
|
||
</html> |