evennia/docs/latest/api/evennia.utils.optionhandler.html
Evennia docbuilder action 243d596662 Updated HTML docs.
2025-08-15 18:14:21 +00:00

315 lines
No EOL
23 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.utils.optionhandler &#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="evennia.utils.picklefield" href="evennia.utils.picklefield.html" />
<link rel="prev" title="evennia.utils.optionclasses" href="evennia.utils.optionclasses.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="evennia.utils.picklefield.html" title="evennia.utils.picklefield"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="evennia.utils.optionclasses.html" title="evennia.utils.optionclasses"
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="../Evennia-API.html" >API Summary</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="evennia-api.html" >evennia</a> &#187;</li>
<li class="nav-item nav-item-3"><a href="evennia.html" >evennia</a> &#187;</li>
<li class="nav-item nav-item-4"><a href="evennia.utils.html" accesskey="U">evennia.utils</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">evennia.utils.optionhandler</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="module-evennia.utils.optionhandler">
<span id="evennia-utils-optionhandler"></span><h1>evennia.utils.optionhandler<a class="headerlink" href="#module-evennia.utils.optionhandler" title="Link to this heading"></a></h1>
<dl class="py class">
<dt class="sig sig-object py" id="evennia.utils.optionhandler.InMemorySaveHandler">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">evennia.utils.optionhandler.</span></span><span class="sig-name descname"><span class="pre">InMemorySaveHandler</span></span><a class="reference internal" href="../_modules/evennia/utils/optionhandler.html#InMemorySaveHandler"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.utils.optionhandler.InMemorySaveHandler" title="Link to this definition"></a></dt>
<dd><p>Bases: <code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code></p>
<p>Fallback SaveHandler, implementing a minimum of the required save mechanism
and storing data in memory.</p>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.utils.optionhandler.InMemorySaveHandler.__init__">
<span class="sig-name descname"><span class="pre">__init__</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/utils/optionhandler.html#InMemorySaveHandler.__init__"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.utils.optionhandler.InMemorySaveHandler.__init__" title="Link to this definition"></a></dt>
<dd></dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.utils.optionhandler.InMemorySaveHandler.add">
<span class="sig-name descname"><span class="pre">add</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">value</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/utils/optionhandler.html#InMemorySaveHandler.add"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.utils.optionhandler.InMemorySaveHandler.add" title="Link to this definition"></a></dt>
<dd></dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.utils.optionhandler.InMemorySaveHandler.get">
<span class="sig-name descname"><span class="pre">get</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">default</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/utils/optionhandler.html#InMemorySaveHandler.get"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.utils.optionhandler.InMemorySaveHandler.get" title="Link to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py" id="evennia.utils.optionhandler.OptionHandler">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">evennia.utils.optionhandler.</span></span><span class="sig-name descname"><span class="pre">OptionHandler</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">obj</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">options_dict</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">savefunc</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">loadfunc</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">save_kwargs</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">load_kwargs</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/utils/optionhandler.html#OptionHandler"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.utils.optionhandler.OptionHandler" title="Link to this definition"></a></dt>
<dd><p>Bases: <code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code></p>
<p>This is a generic Option handler. Retrieve options either as properties on
this handler or by using the .get method.</p>
<p>This is used for Account.options but it could be used by Scripts or Objects
just as easily. All it needs to be provided is an options_dict.</p>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.utils.optionhandler.OptionHandler.__init__">
<span class="sig-name descname"><span class="pre">__init__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">obj</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">options_dict</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">savefunc</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">loadfunc</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">save_kwargs</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">load_kwargs</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/utils/optionhandler.html#OptionHandler.__init__"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.utils.optionhandler.OptionHandler.__init__" title="Link to this definition"></a></dt>
<dd><p>Initialize an OptionHandler.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>obj</strong> (<em>object</em>) The object this handler sits on. This is usually a TypedObject.</p></li>
<li><p><strong>options_dict</strong> (<em>dict</em>) A dictionary of option keys, where the values
are options. The format of those tuples is: (key, “Description to
show”, option_type, &lt;default value&gt;)</p></li>
<li><p><strong>savefunc</strong> (<em>callable</em>) A callable for all options to call when saving itself.
It will be called as <strong>savefunc(key, value, **save_kwargs)</strong>. A common one
to pass would be AttributeHandler.add.</p></li>
<li><p><strong>loadfunc</strong> (<em>callable</em>) A callable for all options to call when loading data into
itself. It will be called as <strong>loadfunc(key, default=default, **load_kwargs)</strong>.
A common one to pass would be AttributeHandler.get.</p></li>
<li><p><strong>save_kwargs</strong> (<em>any</em>) Optional extra kwargs to pass into <strong>savefunc</strong> above.</p></li>
<li><p><strong>load_kwargs</strong> (<em>any</em>) Optional extra kwargs to pass into <strong>loadfunc</strong> above.</p></li>
</ul>
</dd>
</dl>
<p class="rubric">Notes</p>
<p>Both loadfunc and savefunc must be specified. If only one is given, the other
will be ignored and in-memory storage will be used.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.utils.optionhandler.OptionHandler.get">
<span class="sig-name descname"><span class="pre">get</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">default</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">return_obj</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">raise_error</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/utils/optionhandler.html#OptionHandler.get"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.utils.optionhandler.OptionHandler.get" title="Link to this definition"></a></dt>
<dd><p>Retrieves an Option stored in the handler. Will load it if it doesnt exist.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>key</strong> (<em>str</em>) The option key to retrieve.</p></li>
<li><p><strong>default</strong> (<em>any</em>) What to return if the option is defined.</p></li>
<li><p><strong>return_obj</strong> (<em>bool</em><em>, </em><em>optional</em>) If True, returns the actual option
object instead of its value.</p></li>
<li><p><strong>raise_error</strong> (<em>bool</em><em>, </em><em>optional</em>) Raise Exception if key is not found in options.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><em>option_value (any or Option)</em> An option value the Option itself.</p>
</dd>
<dt class="field-odd">Raises<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>KeyError</strong> If option is not defined.</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.utils.optionhandler.OptionHandler.set">
<span class="sig-name descname"><span class="pre">set</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">value</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference internal" href="evennia.utils.optionclasses.html#evennia.utils.optionclasses.BaseOption" title="evennia.utils.optionclasses.BaseOption"><span class="pre">BaseOption</span></a></span></span><a class="reference internal" href="../_modules/evennia/utils/optionhandler.html#OptionHandler.set"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.utils.optionhandler.OptionHandler.set" title="Link to this definition"></a></dt>
<dd><p>Change an individual option.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>key</strong> (<em>str</em>) The key of an option that can be changed. Allows partial matching.</p></li>
<li><p><strong>value</strong> (<em>str</em>) The value that should be checked, coerced, and stored.:</p></li>
<li><p><strong>kwargs</strong> (<em>any</em><em>, </em><em>optional</em>) These are passed into the Options validation function,
save function and display function and allows to customize either.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><p><em>BaseOption</em> </p>
<dl class="simple">
<dt>The matched object. Its new value can be accessed with</dt><dd><p>op.value or op.display().</p>
</dd>
</dl>
</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.utils.optionhandler.OptionHandler.all">
<span class="sig-name descname"><span class="pre">all</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">return_objs</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/utils/optionhandler.html#OptionHandler.all"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.utils.optionhandler.OptionHandler.all" title="Link to this definition"></a></dt>
<dd><p>Get all options defined on this handler.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>return_objs</strong> (<em>bool</em><em>, </em><em>optional</em>) Return the actual Option objects rather
than their values.</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><p><em>all_options (dict)</em> </p>
<dl class="simple">
<dt>All options on this handler, either <strong>{key: value}</strong></dt><dd><p>or <strong>{key: &lt;Option&gt;}</strong> if <strong>return_objs</strong> is <strong>True</strong>.</p>
</dd>
</dl>
</p>
</dd>
</dl>
</dd></dl>
</dd></dl>
</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.utils.optionhandler</a><ul>
<li><a class="reference internal" href="#evennia.utils.optionhandler.InMemorySaveHandler"><code class="docutils literal notranslate"><span class="pre">InMemorySaveHandler</span></code></a><ul>
<li><a class="reference internal" href="#evennia.utils.optionhandler.InMemorySaveHandler.__init__"><code class="docutils literal notranslate"><span class="pre">InMemorySaveHandler.__init__()</span></code></a></li>
<li><a class="reference internal" href="#evennia.utils.optionhandler.InMemorySaveHandler.add"><code class="docutils literal notranslate"><span class="pre">InMemorySaveHandler.add()</span></code></a></li>
<li><a class="reference internal" href="#evennia.utils.optionhandler.InMemorySaveHandler.get"><code class="docutils literal notranslate"><span class="pre">InMemorySaveHandler.get()</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#evennia.utils.optionhandler.OptionHandler"><code class="docutils literal notranslate"><span class="pre">OptionHandler</span></code></a><ul>
<li><a class="reference internal" href="#evennia.utils.optionhandler.OptionHandler.__init__"><code class="docutils literal notranslate"><span class="pre">OptionHandler.__init__()</span></code></a></li>
<li><a class="reference internal" href="#evennia.utils.optionhandler.OptionHandler.get"><code class="docutils literal notranslate"><span class="pre">OptionHandler.get()</span></code></a></li>
<li><a class="reference internal" href="#evennia.utils.optionhandler.OptionHandler.set"><code class="docutils literal notranslate"><span class="pre">OptionHandler.set()</span></code></a></li>
<li><a class="reference internal" href="#evennia.utils.optionhandler.OptionHandler.all"><code class="docutils literal notranslate"><span class="pre">OptionHandler.all()</span></code></a></li>
</ul>
</li>
</ul>
</li>
</ul>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="evennia.utils.optionclasses.html"
title="previous chapter">evennia.utils.optionclasses</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="evennia.utils.picklefield.html"
title="next chapter">evennia.utils.picklefield</a></p>
</div>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/api/evennia.utils.optionhandler.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/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="evennia.utils.picklefield.html" title="evennia.utils.picklefield"
>next</a> |</li>
<li class="right" >
<a href="evennia.utils.optionclasses.html" title="evennia.utils.optionclasses"
>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="../Evennia-API.html" >API Summary</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="evennia-api.html" >evennia</a> &#187;</li>
<li class="nav-item nav-item-3"><a href="evennia.html" >evennia</a> &#187;</li>
<li class="nav-item nav-item-4"><a href="evennia.utils.html" >evennia.utils</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">evennia.utils.optionhandler</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>