<spanid="evennia-utils-batchprocessors"></span><h1>evennia.utils.batchprocessors<aclass="headerlink"href="#module-evennia.utils.batchprocessors"title="Permalink to this headline">¶</a></h1>
<p>This module contains the core methods for the Batch-command- and
Batch-code-processors respectively. In short, these are two different ways to
build a game world using a normal text-editor without having to do so ‘on the
fly’ in-game. They also serve as an automatic backup so you can quickly
recreate a world also after a server reset. The functions in this module is
meant to form the backbone of a system called and accessed through game
commands.</p>
<p>The Batch-command processor is the simplest. It simply runs a list of in-game
commands in sequence by reading them from a text file. The advantage of this is
that the builder only need to remember the normal in-game commands. They are
also executing with full permission checks etc, making it relatively safe for
builders to use. The drawback is that in-game there is really a
builder-character walking around building things, and it can be important to
create rooms and objects in the right order, so the character can move between
them. Also objects that affects players (such as mobs, dark rooms etc) will
affect the building character too, requiring extra care to turn off/on.</p>
<p>The Batch-code processor is a more advanced system that accepts full
Python code, executing in chunks. The advantage of this is much more
power; practically anything imaginable can be coded and handled using
the batch-code processor. There is no in-game character that moves and
that can be affected by what is being built - the database is
populated on the fly. The drawback is safety and entry threshold - the
code is executed as would any server code, without mud-specific
permission-checks, and you have full access to modifying objects
etc. You also need to know Python and Evennia’s API. Hence it’s
recommended that the batch-code processor is limited only to
<h2>Batch-code processor file syntax<aclass="headerlink"href="#batch-code-processor-file-syntax"title="Permalink to this headline">¶</a></h2>
<p>The Batch-code processor accepts full python modules (e.g. <strong>batch.py</strong>)
that looks identical to normal Python files. The difference from
importing and running any Python module is that the batch-code module
is loaded as a file and executed directly, so changes to the file will
apply immediately without a server @reload.</p>
<p>Optionally, one can add some special commented tokens to split the
execution of the code for the benefit of the batchprocessor’s
interactive- and debug-modes. This allows to conveniently step through
the code and re-run sections of it easily during development.</p>
<p>Code blocks are marked by commented tokens alone on a line:</p>
<ulclass="simple">
<li><p><strong>#HEADER</strong> - This denotes code that should be pasted at the top of all
other code. Multiple HEADER statements - regardless of where
it exists in the file - is the same as one big block.
Observe that changes to variables made in one block is not
preserved between blocks!</p></li>
<li><p><strong>#CODE</strong> - This designates a code block that will be executed like a
stand-alone piece of code together with any HEADER(s)
defined. It is mainly used as a way to mark stop points for
the interactive mode of the batchprocessor. If no CODE block
is defined in the module, the entire module (including HEADERS)
is assumed to be a CODE block.</p></li>
<li><p><strong>#INSERT path.filename</strong> - This imports another batch_code.py file and
runs it in the given position. The inserted file will retain
its own HEADERs which will not be mixed with the headers of
this file.</p></li>
</ul>
<p>Importing works as normal. The following variables are automatically
made available in the script namespace.</p>
<ulclass="simple">
<li><p><strong>caller</strong> - The object executing the batchscript</p></li>
<li><dlclass="simple">
<dt><strong>DEBUG</strong> - This is a boolean marking if the batchprocessor is running</dt><dd><p>in debug mode. It can be checked to e.g. delete created objects
when running a CODE block multiple times during testing.
(avoids creating a slew of same-named db objects)</p>
</dd>
</dl>
</li>
</ul>
<divclass="section"id="example-batch-py-file">
<h3>Example batch.py file<aclass="headerlink"href="#example-batch-py-file"title="Permalink to this headline">¶</a></h3>
<spanclass="n">caller</span><spanclass="o">.</span><spanclass="n">msg</span><spanclass="p">(</span><spanclass="s2">"The object was created!"</span><spanclass="p">)</span>
<codeclass="sig-prename descclassname">evennia.utils.batchprocessors.</code><codeclass="sig-name descname">read_batchfile</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">pythonpath</span></em>, <emclass="sig-param"><spanclass="n">file_ending</span><spanclass="o">=</span><spanclass="default_value">'.py'</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/batchprocessors.html#read_batchfile"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.batchprocessors.read_batchfile"title="Permalink to this definition">¶</a></dt>
<emclass="property">class </em><codeclass="sig-prename descclassname">evennia.utils.batchprocessors.</code><codeclass="sig-name descname">BatchCommandProcessor</code><aclass="reference internal"href="../_modules/evennia/utils/batchprocessors.html#BatchCommandProcessor"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.batchprocessors.BatchCommandProcessor"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">parse_file</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">pythonpath</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/batchprocessors.html#BatchCommandProcessor.parse_file"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.batchprocessors.BatchCommandProcessor.parse_file"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-prename descclassname">evennia.utils.batchprocessors.</code><codeclass="sig-name descname">tb_filename</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">tb</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/batchprocessors.html#tb_filename"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.batchprocessors.tb_filename"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-prename descclassname">evennia.utils.batchprocessors.</code><codeclass="sig-name descname">tb_iter</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">tb</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/batchprocessors.html#tb_iter"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.batchprocessors.tb_iter"title="Permalink to this definition">¶</a></dt>
<emclass="property">class </em><codeclass="sig-prename descclassname">evennia.utils.batchprocessors.</code><codeclass="sig-name descname">BatchCodeProcessor</code><aclass="reference internal"href="../_modules/evennia/utils/batchprocessors.html#BatchCodeProcessor"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.batchprocessors.BatchCodeProcessor"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">parse_file</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">pythonpath</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/batchprocessors.html#BatchCodeProcessor.parse_file"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.batchprocessors.BatchCodeProcessor.parse_file"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">code_exec</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">code</span></em>, <emclass="sig-param"><spanclass="n">extra_environ</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">debug</span><spanclass="o">=</span><spanclass="default_value">False</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/batchprocessors.html#BatchCodeProcessor.code_exec"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.batchprocessors.BatchCodeProcessor.code_exec"title="Permalink to this definition">¶</a></dt>