evennia/docs/6.x/Coding/Evennia-Code-Style.html
2026-02-15 19:06:04 +01:00

434 lines
No EOL
24 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Evennia Code Style &#8212; Evennia latest documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=d75fae25" />
<link rel="stylesheet" type="text/css" href="../_static/nature.css?v=279e0f84" />
<link rel="stylesheet" type="text/css" href="../_static/custom.css?v=e4a91a55" />
<script src="../_static/documentation_options.js?v=c6e86fd7"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Default Command Syntax" href="Default-Command-Syntax.html" />
<link rel="prev" title="Coding and development help" href="Coding-Overview.html" />
</head><body>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Default-Command-Syntax.html" title="Default Command Syntax"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Coding-Overview.html" title="Coding and development help"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="Coding-Overview.html" accesskey="U">Coding and development help</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Evennia Code Style</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section class="tex2jax_ignore mathjax_ignore" id="evennia-code-style">
<h1>Evennia Code Style<a class="headerlink" href="#evennia-code-style" title="Link to this heading"></a></h1>
<p>All code submitted or committed to the Evennia project should aim to follow the
guidelines outlined in <a class="reference external" href="http://www.python.org/dev/peps/pep-0008">Python PEP 8</a>. Keeping the code style uniform
makes it much easier for people to collaborate and read the code.</p>
<p>A good way to check if your code follows PEP8 is to use the <a class="reference external" href="https://pypi.python.org/pypi/pep8">PEP8 tool</a>
on your sources.</p>
<section id="main-code-style-specification">
<h2>Main code style specification<a class="headerlink" href="#main-code-style-specification" title="Link to this heading"></a></h2>
<ul class="simple">
<li><p>4-space indentation, NO TABS!</p></li>
<li><p>Unix line endings.</p></li>
<li><p>100 character line widths</p></li>
<li><p>CamelCase is only used for classes, nothing else.</p></li>
<li><p>All non-global variable names and all function names are to be
lowercase, words separated by underscores. Variable names should
always be more than two letters long.</p></li>
<li><p>Module-level global variables (only) are to be in CAPITAL letters.</p></li>
<li><p>Imports should be done in this order:</p>
<ul>
<li><p>Python modules (builtins and standard library)</p></li>
<li><p>Twisted modules</p></li>
<li><p>Django modules</p></li>
<li><p>Evennia library modules (<code class="docutils literal notranslate"><span class="pre">evennia</span></code>)</p></li>
<li><p>Evennia contrib modules (<code class="docutils literal notranslate"><span class="pre">evennia.contrib</span></code>)</p></li>
</ul>
</li>
<li><p>All modules, classes, functions and methods should have doc strings formatted
as outlined below.</p></li>
<li><p>All default commands should have a consistent docstring formatted as
outlined below.</p></li>
</ul>
</section>
<section id="code-docstrings">
<h2>Code Docstrings<a class="headerlink" href="#code-docstrings" title="Link to this heading"></a></h2>
<p>All modules, classes, functions and methods should have docstrings
formatted with <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html">Google style</a> -inspired indents, using
<a class="reference external" href="https://help.github.com/articles/github-flavored-markdown/">Markdown</a> formatting where needed. Evennias <code class="docutils literal notranslate"><span class="pre">api2md</span></code>
parser will use this to create pretty API documentation.</p>
<section id="module-docstrings">
<h3>Module docstrings<a class="headerlink" href="#module-docstrings" title="Link to this heading"></a></h3>
<p>Modules should all start with at least a few lines of docstring at
their top describing the contents and purpose of the module.</p>
<p>Example of module docstring (top of file):</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd">This module handles the creation of `Objects` that</span>
<span class="sd">are useful in the game ...</span>
<span class="sd">&quot;&quot;&quot;</span>
</pre></div>
</div>
<p>Sectioning (<code class="docutils literal notranslate"><span class="pre">#</span> <span class="pre">title</span></code>, <code class="docutils literal notranslate"><span class="pre">##</span> <span class="pre">subtile</span></code> etc) should not be used in
freeform docstrings - this will confuse the sectioning of the auto
documentation page and the auto-api will create this automatically.
Write just the section name bolded on its own line to mark a section.
Beyond sections markdown should be used as needed to format
the text.</p>
<p>Code examples should use <a class="reference external" href="https://help.github.com/articles/github-flavored-markdown/#syntax-highlighting">multi-line syntax highlighting</a>
to mark multi-line code blocks, using the “python” identifier. Just
indenting code blocks (common in markdown) will not produce the
desired look.</p>
<p>When using any code tags (inline or blocks) its recommended that you
dont let the code extend wider than about 70 characters or it will
need to be scrolled horizontally in the wiki (this does not affect any
other text, only code).</p>
</section>
<section id="class-docstrings">
<h3>Class docstrings<a class="headerlink" href="#class-docstrings" title="Link to this heading"></a></h3>
<p>The root class docstring should describe the over-arching use of the
class. It should usually not describe the exact call sequence nor list
important methods, this tends to be hard to keep updated as the API
develops. Dont use section markers (<code class="docutils literal notranslate"><span class="pre">#</span></code>, <code class="docutils literal notranslate"><span class="pre">##</span></code> etc).</p>
<p>Example of class docstring:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span><span class="w"> </span><span class="nc">MyClass</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
<span class="w"> </span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> This class describes the creation of `Objects`. It is useful</span>
<span class="sd"> in many situations, such as ...</span>
<span class="sd"> &quot;&quot;&quot;</span>
</pre></div>
</div>
</section>
<section id="function-method-docstrings">
<h3>Function / method docstrings<a class="headerlink" href="#function-method-docstrings" title="Link to this heading"></a></h3>
<p>Example of function or method docstring:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span>
<span class="k">def</span><span class="w"> </span><span class="nf">funcname</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">,</span> <span class="n">c</span><span class="p">,</span> <span class="n">d</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="w"> </span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> This is a brief introduction to the function/class/method</span>
<span class="sd"> Args:</span>
<span class="sd"> a (str): This is a string argument that we can talk about</span>
<span class="sd"> over multiple lines.</span>
<span class="sd"> b (int or str): Another argument.</span>
<span class="sd"> c (list): A list argument.</span>
<span class="sd"> d (bool, optional): An optional keyword argument.</span>
<span class="sd"> Keyword Args:</span>
<span class="sd"> test (list): A test keyword.</span>
<span class="sd"> Returns:</span>
<span class="sd"> str: The result of the function.</span>
<span class="sd"> Raises:</span>
<span class="sd"> RuntimeException: If there is a critical error,</span>
<span class="sd"> this is raised.</span>
<span class="sd"> IOError: This is only raised if there is a</span>
<span class="sd"> problem with the database.</span>
<span class="sd"> Notes:</span>
<span class="sd"> This is an example function. If `d=True`, something</span>
<span class="sd"> amazing will happen.</span>
<span class="sd"> &quot;&quot;&quot;</span>
</pre></div>
</div>
<p>The syntax is very “loose” but the indentation matters. That is, you
should end the block headers (like <code class="docutils literal notranslate"><span class="pre">Args:</span></code>) with a line break followed by
an indent. When you need to break a line you should start the next line
with another indent. For consistency with the code we recommend all
indents to be 4 spaces wide (no tabs!).</p>
<p>Here are all the supported block headers:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="w"> </span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> Args</span>
<span class="sd"> argname (freeform type): Description endind with period.</span>
<span class="sd"> Keyword Args:</span>
<span class="sd"> argname (freeform type): Description.</span>
<span class="sd"> Returns/Yields:</span>
<span class="sd"> type: Description.</span>
<span class="sd"> Raises:</span>
<span class="sd"> Exceptiontype: Description.</span>
<span class="sd"> Notes/Note/Examples/Example:</span>
<span class="sd"> Freeform text.</span>
<span class="sd"> &quot;&quot;&quot;</span>
</pre></div>
</div>
<p>Parts marked with “freeform” means that you can in principle put any
text there using any formatting except for sections markers (<code class="docutils literal notranslate"><span class="pre">#</span></code>, <code class="docutils literal notranslate"><span class="pre">##</span></code>
etc). You must also keep indentation to mark which block you are part
of. You should normally use the specified format rather than the
freeform counterpart (this will produce nicer output) but in some
cases the freeform may produce a more compact and readable result
(such as when describing an <code class="docutils literal notranslate"><span class="pre">*args</span></code> or <code class="docutils literal notranslate"><span class="pre">**kwargs</span></code> statement in general
terms). The first <code class="docutils literal notranslate"><span class="pre">self</span></code> argument of class methods should never be
documented.</p>
<p>Note that</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd">Args:</span>
<span class="sd"> argname (type, optional): Description.</span>
<span class="sd">&quot;&quot;&quot;</span>
</pre></div>
</div>
<p>and</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd">Keyword Args:</span>
<span class="sd"> sargname (type): Description.</span>
<span class="sd">&quot;&quot;&quot;</span>
</pre></div>
</div>
<p>mean the same thing! Which one is used depends on the function or
method documented, but there are no hard rules; If there is a large
<code class="docutils literal notranslate"><span class="pre">**kwargs</span></code> block in the function, using the <code class="docutils literal notranslate"><span class="pre">Keyword</span> <span class="pre">Args:</span></code> block may be a
good idea, for a small number of arguments though, just using <code class="docutils literal notranslate"><span class="pre">Args:</span></code>
and marking keywords as <code class="docutils literal notranslate"><span class="pre">optional</span></code> will shorten the docstring and make
it easier to read.</p>
</section>
</section>
<section id="default-command-docstrings">
<h2>Default Command Docstrings<a class="headerlink" href="#default-command-docstrings" title="Link to this heading"></a></h2>
<p>These represent a special case since Commands in Evennia use their class
docstrings to represent the in-game help entry for that command.</p>
<p>All the commands in the <em>default command</em> sets should have their doc-strings
formatted on a similar form. For contribs, this is loosened, but if there is
no particular reason to use a different form, one should aim to use the same
style for contrib-command docstrings as well.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="w"> </span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> Short header</span>
<span class="sd"> Usage:</span>
<span class="sd"> key[/switches, if any] &lt;mandatory args&gt; [optional] choice1||choice2||choice3</span>
<span class="sd"> Switches:</span>
<span class="sd"> switch1 - description</span>
<span class="sd"> switch2 - description</span>
<span class="sd"> Examples:</span>
<span class="sd"> Usage example and output</span>
<span class="sd"> Longer documentation detailing the command.</span>
<span class="sd"> &quot;&quot;&quot;</span>
</pre></div>
</div>
<ul class="simple">
<li><p>Two spaces are used for <em>indentation</em> in all default commands.</p></li>
<li><p>Square brackets <code class="docutils literal notranslate"><span class="pre">[</span> <span class="pre">]</span></code> surround <em>optional, skippable arguments</em>.</p></li>
<li><p>Angled brackets <code class="docutils literal notranslate"><span class="pre">&lt;</span> <span class="pre">&gt;</span></code> surround a <em>description</em> of what to write rather than the exact syntax.</p></li>
<li><p>Explicit choices are separated by <code class="docutils literal notranslate"><span class="pre">|</span></code>. To avoid this being parsed as a color code, use <code class="docutils literal notranslate"><span class="pre">||</span></code> (this
will come out as a single <code class="docutils literal notranslate"><span class="pre">|</span></code>) or put spaces around the character (“<code class="docutils literal notranslate"><span class="pre">|</span></code>”) if theres plenty of room.</p></li>
<li><p>The <code class="docutils literal notranslate"><span class="pre">Switches</span></code> and <code class="docutils literal notranslate"><span class="pre">Examples</span></code> blocks are optional and based on the Command.</p></li>
</ul>
<p>Here is the <code class="docutils literal notranslate"><span class="pre">nick</span></code> command as an example:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="w"> </span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> Define a personal alias/nick</span>
<span class="sd"> Usage:</span>
<span class="sd"> nick[/switches] &lt;nickname&gt; = [&lt;string&gt;]</span>
<span class="sd"> alias &#39;&#39;</span>
<span class="sd"> Switches:</span>
<span class="sd"> object - alias an object</span>
<span class="sd"> account - alias an account</span>
<span class="sd"> clearall - clear all your aliases</span>
<span class="sd"> list - show all defined aliases (also &quot;nicks&quot; works)</span>
<span class="sd"> Examples:</span>
<span class="sd"> nick hi = say Hello, I&#39;m Sarah!</span>
<span class="sd"> nick/object tom = the tall man</span>
<span class="sd"> A &#39;nick&#39; is a personal shortcut you create for your own use [...]</span>
<span class="sd"> &quot;&quot;&quot;</span>
</pre></div>
</div>
<p>For commands that <em>require arguments</em>, the policy is for it to return a <code class="docutils literal notranslate"><span class="pre">Usage:</span></code>
string if the command is entered without any arguments. So for such commands,
the Command body should contain something to the effect of</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="k">if</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="n">args</span><span class="p">:</span>
<span class="bp">self</span><span class="o">.</span><span class="n">caller</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span><span class="s2">&quot;Usage: nick[/switches] &lt;nickname&gt; = [&lt;string&gt;]&quot;</span><span class="p">)</span>
<span class="k">return</span>
</pre></div>
</div>
</section>
<section id="tools-for-auto-linting">
<h2>Tools for auto-linting<a class="headerlink" href="#tools-for-auto-linting" title="Link to this heading"></a></h2>
<section id="black">
<h3>black<a class="headerlink" href="#black" title="Link to this heading"></a></h3>
<p>Automatic pep8 compliant formatting and linting can be performed using the
<code class="docutils literal notranslate"><span class="pre">black</span></code> formatter:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>black --line-length 100
</pre></div>
</div>
</section>
<section id="pycharm">
<h3>PyCharm<a class="headerlink" href="#pycharm" title="Link to this heading"></a></h3>
<p>The Python IDE <a class="reference external" href="https://www.jetbrains.com/pycharm/">Pycharm</a> can auto-generate empty doc-string stubs. The
default is to use <code class="docutils literal notranslate"><span class="pre">reStructuredText</span></code> form, however. To change to Evennias
Google-style docstrings, follow <a class="reference external" href="https://www.jetbrains.com/help/pycharm/2016.3/python-integrated-tools.html">this guide</a>.</p>
</section>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/evennia_logo.png" alt="Logo of Evennia"/>
</a></p>
<search 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" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Evennia Code Style</a><ul>
<li><a class="reference internal" href="#main-code-style-specification">Main code style specification</a></li>
<li><a class="reference internal" href="#code-docstrings">Code Docstrings</a><ul>
<li><a class="reference internal" href="#module-docstrings">Module docstrings</a></li>
<li><a class="reference internal" href="#class-docstrings">Class docstrings</a></li>
<li><a class="reference internal" href="#function-method-docstrings">Function / method docstrings</a></li>
</ul>
</li>
<li><a class="reference internal" href="#default-command-docstrings">Default Command Docstrings</a></li>
<li><a class="reference internal" href="#tools-for-auto-linting">Tools for auto-linting</a><ul>
<li><a class="reference internal" href="#black">black</a></li>
<li><a class="reference internal" href="#pycharm">PyCharm</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="Coding-Overview.html"
title="previous chapter">Coding and development help</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="Default-Command-Syntax.html"
title="next chapter">Default Command Syntax</a></p>
</div>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Coding/Evennia-Code-Style.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div><h3>Links</h3>
<ul>
<li><a href="https://www.evennia.com/docs/latest/index.html">Documentation Top</a> </li>
<li><a href="https://www.evennia.com">Evennia Home</a> </li>
<li><a href="https://github.com/evennia/evennia">Github</a> </li>
<li><a href="http://games.evennia.com">Game Index</a> </li>
<li>
<a href="https://discord.gg/AJJpcRUhtF">Discord</a> -
<a href="https://github.com/evennia/evennia/discussions">Discussions</a> -
<a href="https://evennia.blogspot.com/">Blog</a>
</li>
</ul>
<h3>Doc Versions</h3>
<ul>
<li>
<a href="https://www.evennia.com/docs/latest/index.html">latest (main branch)</a>
</li>
<li>
<a href="https://www.evennia.com/docs/6.x/index.html">v6.0.0 branch (outdated)</a>
</li>
<li>
<a href="https://www.evennia.com/docs/5.x/index.html">v5.0.0 branch (outdated)</a>
</li>
<li>
<a href="https://www.evennia.com/docs/4.x/index.html">v4.0.0 branch (outdated)</a>
</li>
<li>
<a href="https://www.evennia.com/docs/3.x/index.html">v3.0.0 branch (outdated)</a>
</li>
<li>
<a href="https://www.evennia.com/docs/2.x/index.html">v2.0.0 branch (outdated)</a>
</li>
<li>
<a href="https://www.evennia.com/docs/1.x/index.html">v1.0.0 branch (outdated)</a>
</li>
<li>
<a href="https://www.evennia.com/docs/0.x/index.html">v0.9.5 branch (outdated)</a>
</li>
</ul>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Default-Command-Syntax.html" title="Default Command Syntax"
>next</a> |</li>
<li class="right" >
<a href="Coding-Overview.html" title="Coding and development help"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="Coding-Overview.html" >Coding and development help</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Evennia Code Style</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2024, The Evennia developer community.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
</div>
</body>
</html>