Andreas/evennia
1
0
Fork 0
mirror of https://github.com/evennia/evennia.git synced 2026-04-04 06:57:16 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions
evennia/docs/latest/api/evennia.locks.lockhandler.html

653 lines
43 KiB
HTML
Raw Normal View History

Updated HTML docs.
2025-08-15 18:14:21 +00:00
<!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.locks.lockhandler &#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.objects" href="evennia.objects.html" />
<link rel="prev" title="evennia.locks.lockfuncs" href="evennia.locks.lockfuncs.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.objects.html" title="evennia.objects"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="evennia.locks.lockfuncs.html" title="evennia.locks.lockfuncs"
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.locks.html" accesskey="U">evennia.locks</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">evennia.locks.lockhandler</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="module-evennia.locks.lockhandler">
<span id="evennia-locks-lockhandler"></span><h1>evennia.locks.lockhandler<a class="headerlink" href="#module-evennia.locks.lockhandler" title="Link to this heading"></a></h1>
<p>A <em>lock</em> defines access to a particular subsystem or property of
Evennia. For example, the “owner” property can be impmemented as a
lock. Or the disability to lift an object or to ban users.</p>
<p>A lock consists of three parts:</p>
<blockquote>
<div><ul class="simple">
<li><p>access_type - this defines what kind of access this lock regulates. This
just a string.</p></li>
<li><p>function call - this is one or many calls to functions that will determine
if the lock is passed or not.</p></li>
<li><p>lock function(s). These are regular python functions with a special
set of allowed arguments. They should always return a boolean depending
on if they allow access or not.</p></li>
</ul>
</div></blockquote>
<p>A lock function is defined by existing in one of the modules
listed by settings.LOCK_FUNC_MODULES. It should also always
take four arguments looking like this:</p>
<blockquote>
<div><dl class="simple">
<dt>funcname(accessing_obj, accessed_obj, <a href="#id1"><span class="problematic" id="id2">*</span></a>args, <a href="#id3"><span class="problematic" id="id4">**</span></a>kwargs):</dt><dd><p>[…]</p>
</dd>
</dl>
</div></blockquote>
<p>The accessing object is the object wanting to gain access.
The accessed object is the object this lock resides on
args and kwargs will hold optional arguments and/or keyword arguments
to the function as a list and a dictionary respectively.</p>
<p class="rubric">Example</p>
<dl>
<dt>perm(accessing_obj, accessed_obj, <a href="#id5"><span class="problematic" id="id6">*</span></a>args, <a href="#id7"><span class="problematic" id="id8">**</span></a>kwargs):</dt><dd><p>“Checking if the object has a particular, desired permission”
if args:</p>
<blockquote>
<div><p>desired_perm = args[0]
return desired_perm in accessing_obj.permissions.all()</p>
</div></blockquote>
<p>return False</p>
</dd>
</dl>
<p>Lock functions should most often be pretty general and ideally possible to
re-use and combine in various ways to build clever locks.</p>
<p>Lock definition (“Lock string”)</p>
<p>A lock definition is a string with a special syntax. It is added to
each object’s lockhandler, making that lock available from then on.</p>
<p>The lock definition looks like this:</p>
<blockquote>
<div><p>‘access_type:[NOT] func1(args)[ AND|OR][NOT] func2() …’</p>
</div></blockquote>
<p>That is, the access_type, a colon followed by calls to lock functions
combined with AND or OR. NOT negates the result of the following call.</p>
<p class="rubric">Example</p>
<p>We want to limit who may edit a particular object (let’s call this access_type</p>
<p>for ‘edit’, it depends on what the command is looking for). We want this to
only work for those with the Permission ‘Builder’. So we use our lock
function above and define it like this:</p>
<blockquote>
<div><p>‘edit:perm(Builder)’</p>
</div></blockquote>
<p>Here, the lock-function perm() will be called with the string
‘Builder’ (accessing_obj and accessed_obj are added automatically,
you only need to add the args/kwargs, if any).</p>
<p>If we wanted to make sure the accessing object was BOTH a Builder and a
GoodGuy, we could use AND:</p>
<blockquote>
<div><p>‘edit:perm(Builder) AND perm(GoodGuy)’</p>
</div></blockquote>
<p>To allow EITHER Builder and GoodGuys, we replace AND with OR. perm() is just
one example, the lock function can do anything and compare any properties of
the calling object to decide if the lock is passed or not.</p>
<blockquote>
<div><p>‘lift:attrib(very_strong) AND NOT attrib(bad_back)’</p>
</div></blockquote>
<p>To make these work, add the string to the lockhandler of the object you want
to apply the lock to:</p>
<blockquote>
<div><p>obj.lockhandler.add(‘edit:perm(Builder)’)</p>
</div></blockquote>
<p>From then on, a command that wants to check for ‘edit’ access on this
object would do something like this:</p>
<blockquote>
<div><dl class="simple">
<dt>if not target_obj.lockhandler.has_perm(caller, ‘edit’):</dt><dd><p>caller.msg(“Sorry, you cannot edit that.”)</p>
</dd>
</dl>
</div></blockquote>
<p>All objects also has a shortcut called ‘access’ that is recommended to
use instead:</p>
<blockquote>
<div><dl class="simple">
<dt>if not target_obj.access(caller, ‘edit’):</dt><dd><p>caller.msg(“Sorry, you cannot edit that.”)</p>
</dd>
</dl>
</div></blockquote>
<p>Permissions</p>
<p>Permissions are just text strings stored in a comma-separated list on
typeclassed objects. The default perm() lock function uses them,
taking into account settings.PERMISSION_HIERARCHY. Also, the
restricted &#64;perm command sets them, but otherwise they are identical
to any other identifier you can use.</p>
<dl class="py class">
<dt class="sig sig-object py" id="evennia.locks.lockhandler.LockHandler">
<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.locks.lockhandler.</span></span><span class="sig-name descname"><span class="pre">LockHandler</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">obj</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/locks/lockhandler.html#LockHandler"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.locks.lockhandler.LockHandler" 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 handler should be attached to all objects implementing
permission checks, under the property ‘lockhandler’.</p>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.locks.lockhandler.LockHandler.__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><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/locks/lockhandler.html#LockHandler.__init__"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.locks.lockhandler.LockHandler.__init__" title="Link to this definition"></a></dt>
<dd><p>Loads and pre-caches all relevant locks and their functions.</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 on which the lockhandler is</p></li>
<li><p><strong>defined.</strong></p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.locks.lockhandler.LockHandler.cache_lock_bypass">
<span class="sig-name descname"><span class="pre">cache_lock_bypass</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">obj</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/locks/lockhandler.html#LockHandler.cache_lock_bypass"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.locks.lockhandler.LockHandler.cache_lock_bypass" title="Link to this definition"></a></dt>
<dd><p>We cache superuser bypass checks here for efficiency. This
needs to be re-run when an account is assigned to a character.
We need to grant access to superusers. We need to check both
directly on the object (accounts), through obj.account and using
the get_account() method (this sits on serversessions, in some
rare cases where a check is done before the login process has
yet been fully finalized)</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>obj</strong> (<em>object</em>) – This is checked for the <strong>is_superuser</strong> property.</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.locks.lockhandler.LockHandler.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">lockstring</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">validate_only</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/locks/lockhandler.html#LockHandler.add"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.locks.lockhandler.LockHandler.add" title="Link to this definition"></a></dt>
<dd><p>Add a new lockstring to handler.</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>lockstring</strong> (<em>str</em><em> or </em><em>list</em>) – A string on the form
<strong>“&lt;access_type&gt;:&lt;functions&gt;”</strong>. Multiple access types
should be separated by semicolon (<strong>;</strong>). Alternatively,
a list with lockstrings.</p></li>
<li><p><strong>validate_only</strong> (<em>bool</em><em>, </em><em>optional</em>) – If True, validate the lockstring but
don’t actually store it.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><p><em>success (bool)</em> –</p>
<dl class="simple">
<dt>The outcome of the addition, <strong>False</strong> on</dt><dd><p>error. If <strong>validate_only</strong> is True, this will be a tuple
(bool, error), for pass/fail and a string error.</p>
</dd>
</dl>
</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.locks.lockhandler.LockHandler.validate">
<span class="sig-name descname"><span class="pre">validate</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">lockstring</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/locks/lockhandler.html#LockHandler.validate"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.locks.lockhandler.LockHandler.validate" title="Link to this definition"></a></dt>
<dd><p>Validate lockstring syntactically, without saving it.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>lockstring</strong> (<em>str</em>) – Lockstring to validate.</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><em>valid (bool)</em> – If validation passed or not.</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.locks.lockhandler.LockHandler.replace">
<span class="sig-name descname"><span class="pre">replace</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">lockstring</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/locks/lockhandler.html#LockHandler.replace"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.locks.lockhandler.LockHandler.replace" title="Link to this definition"></a></dt>
<dd><p>Replaces the lockstring entirely.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>lockstring</strong> (<em>str</em>) – The new lock definition.</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><em>success (bool)</em> – False if an error occurred.</p>
</dd>
<dt class="field-odd">Raises<span class="colon">:</span></dt>
<dd class="field-odd"><p><a class="reference internal" href="#evennia.locks.lockhandler.LockException" title="evennia.locks.lockhandler.LockException"><strong>LockException</strong></a> – If a critical error occurred.
If so, the old string is recovered.</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.locks.lockhandler.LockHandler.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">access_type</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/locks/lockhandler.html#LockHandler.get"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.locks.lockhandler.LockHandler.get" title="Link to this definition"></a></dt>
<dd><p>Get the full lockstring or the lockstring of a particular
access type.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>access_type</strong> (<em>str</em><em>, </em><em>optional</em>)</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><p><em>lockstring (str)</em> –</p>
<dl class="simple">
<dt>The matched lockstring, or the full</dt><dd><p>lockstring if no access_type was given.</p>
</dd>
</dl>
</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.locks.lockhandler.LockHandler.all">
<span class="sig-name descname"><span class="pre">all</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/locks/lockhandler.html#LockHandler.all"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.locks.lockhandler.LockHandler.all" title="Link to this definition"></a></dt>
<dd><p>Return all lockstrings</p>
<dl class="field-list simple">
<dt class="field-odd">Returns<span class="colon">:</span></dt>
<dd class="field-odd"><p><em>lockstrings (list)</em> – All separate lockstrings</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.locks.lockhandler.LockHandler.remove">
<span class="sig-name descname"><span class="pre">remove</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">access_type</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/locks/lockhandler.html#LockHandler.remove"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.locks.lockhandler.LockHandler.remove" title="Link to this definition"></a></dt>
<dd><p>Remove a particular lock from the handler</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>access_type</strong> (<em>str</em>) – The type of lock to remove.</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><p><em>success (bool)</em> –</p>
<dl class="simple">
<dt>If the access_type was not found</dt><dd><p>in the lock, this returns <strong>False</strong>.</p>
</dd>
</dl>
</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.locks.lockhandler.LockHandler.delete">
<span class="sig-name descname"><span class="pre">delete</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">access_type</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#evennia.locks.lockhandler.LockHandler.delete" title="Link to this definition"></a></dt>
<dd><p>Remove a particular lock from the handler</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>access_type</strong> (<em>str</em>) – The type of lock to remove.</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><p><em>success (bool)</em> –</p>
<dl class="simple">
<dt>If the access_type was not found</dt><dd><p>in the lock, this returns <strong>False</strong>.</p>
</dd>
</dl>
</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.locks.lockhandler.LockHandler.clear">
<span class="sig-name descname"><span class="pre">clear</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/locks/lockhandler.html#LockHandler.clear"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.locks.lockhandler.LockHandler.clear" title="Link to this definition"></a></dt>
<dd><p>Remove all locks in the handler.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.locks.lockhandler.LockHandler.reset">
<span class="sig-name descname"><span class="pre">reset</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/locks/lockhandler.html#LockHandler.reset"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.locks.lockhandler.LockHandler.reset" title="Link to this definition"></a></dt>
<dd><p>Set the reset flag, so the the lock will be re-cached at next
checking. This is usually called by &#64;reload.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.locks.lockhandler.LockHandler.append">
<span class="sig-name descname"><span class="pre">append</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">access_type</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">lockstring</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">op</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'or'</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/locks/lockhandler.html#LockHandler.append"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.locks.lockhandler.LockHandler.append" title="Link to this definition"></a></dt>
<dd><p>Append a lock definition to access_type if it doesn’t already 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>access_type</strong> (<em>str</em>) – Access type.</p></li>
<li><p><strong>lockstring</strong> (<em>str</em>) – A valid lockstring, without the operator to
link it to an eventual existing lockstring.</p></li>
<li><p><strong>op</strong> (<em>str</em>) – An operator ‘and’, ‘or’, ‘and not’, ‘or not’ used
for appending the lockstring to an existing access-type.</p></li>
</ul>
</dd>
</dl>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The most common use of this method is for use in commands where
the user can specify their own lockstrings. This method allows
the system to auto-add things like Admin-override access.</p>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.locks.lockhandler.LockHandler.check">
<span class="sig-name descname"><span class="pre">check</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">accessing_obj</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">access_type</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">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">no_superuser_bypass</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/locks/lockhandler.html#LockHandler.check"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.locks.lockhandler.LockHandler.check" title="Link to this definition"></a></dt>
<dd><p>Checks a lock of the correct type by passing execution off to
the lock function(s).</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>accessing_obj</strong> (<em>object</em>) – The object seeking access.</p></li>
<li><p><strong>access_type</strong> (<em>str</em>) – The type of access wanted.</p></li>
<li><p><strong>default</strong> (<em>bool</em><em>, </em><em>optional</em>) – If no suitable lock type is
found, default to this result.</p></li>
<li><p><strong>no_superuser_bypass</strong> (<em>bool</em>) – Don’t use this unless you
really, really need to, it makes supersusers susceptible
to the lock check.</p></li>
</ul>
</dd>
</dl>
<p class="rubric">Notes</p>
<p>A lock is executed in the follwoing way:</p>
<p>Parsing the lockstring, we (during cache) extract the valid
lock functions and store their function objects in the right
order along with their args/kwargs. These are now executed in
sequence, creating a list of True/False values. This is put
into the evalstring, which is a string of AND/OR/NOT entries
separated by placeholders where each function result should
go. We just put those results in and evaluate the string to
get a final, combined True/False value for the lockstring.</p>
<p>The important bit with this solution is that the full
lockstring is never blindly evaluated, and thus there (should
be) no way to sneak in malign code in it. Only “safe” lock
functions (as defined by your settings) are executed.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.locks.lockhandler.LockHandler.check_lockstring">
<span class="sig-name descname"><span class="pre">check_lockstring</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">accessing_obj</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">lockstring</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">no_superuser_bypass</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">default</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">access_type</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/locks/lockhandler.html#LockHandler.check_lockstring"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.locks.lockhandler.LockHandler.check_lockstring" title="Link to this definition"></a></dt>
<dd><p>Do a direct check against a lockstring (‘atype:func()..’),
without any intermediary storage on the accessed object.</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>accessing_obj</strong> (<em>object</em><em> or </em><em>None</em>) – The object seeking access.
Importantly, this can be left unset if the lock functions
don’t access it, no updating or storage of locks are made
against this object in this method.</p></li>
<li><p><strong>lockstring</strong> (<em>str</em>) – Lock string to check, on the form
<strong>“access_type:lock_definition”</strong> where the <strong>access_type</strong>
part can potentially be set to a dummy value to just check
a lock condition.</p></li>
<li><p><strong>no_superuser_bypass</strong> (<em>bool</em><em>, </em><em>optional</em>) – Force superusers to heed lock.</p></li>
<li><p><strong>default</strong> (<em>bool</em><em>, </em><em>optional</em>) – Fallback result to use if <strong>access_type</strong> is set
but no such <strong>access_type</strong> is found in the given <strong>lockstring</strong>.</p></li>
<li><p><strong>access_type</strong> (<em>str</em><em>, </em><em>bool</em>) – If set, only this access_type will be looked up
among the locks defined by <strong>lockstring</strong>.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><em>access (bool)</em> – If check is passed or not.</p>
</dd>
</dl>
</dd></dl>
</dd></dl>
<dl class="py exception">
<dt class="sig sig-object py" id="evennia.locks.lockhandler.LockException">
<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">evennia.locks.lockhandler.</span></span><span class="sig-name descname"><span class="pre">LockException</span></span><a class="reference internal" href="../_modules/evennia/locks/lockhandler.html#LockException"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.locks.lockhandler.LockException" title="Link to this definition"></a></dt>
<dd><p>Bases: <code class="xref py py-class docutils literal notranslate"><span class="pre">Exception</span></code></p>
<p>Raised during an error in a lock.</p>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="evennia.locks.lockhandler.check_lockstring">
<span class="sig-prename descclassname"><span class="pre">evennia.locks.lockhandler.</span></span><span class="sig-name descname"><span class="pre">check_lockstring</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">accessing_obj</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">lockstring</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">no_superuser_bypass</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">default</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">access_type</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/locks/lockhandler.html#check_lockstring"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.locks.lockhandler.check_lockstring" title="Link to this definition"></a></dt>
<dd><p>Do a direct check against a lockstring (‘atype:func()..’),
without any intermediary storage on the accessed object.</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>accessing_obj</strong> (<em>object</em><em> or </em><em>None</em>) – The object seeking access.
Importantly, this can be left unset if the lock functions
don’t access it, no updating or storage of locks are made
against this object in this method.</p></li>
<li><p><strong>lockstring</strong> (<em>str</em>) – Lock string to check, on the form
<strong>“access_type:lock_definition”</strong> where the <strong>access_type</strong>
part can potentially be set to a dummy value to just check
a lock condition.</p></li>
<li><p><strong>no_superuser_bypass</strong> (<em>bool</em><em>, </em><em>optional</em>) – Force superusers to heed lock.</p></li>
<li><p><strong>default</strong> (<em>bool</em><em>, </em><em>optional</em>) – Fallback result to use if <strong>access_type</strong> is set
but no such <strong>access_type</strong> is found in the given <strong>lockstring</strong>.</p></li>
<li><p><strong>access_type</strong> (<em>str</em><em>, </em><em>bool</em>) – If set, only this access_type will be looked up
among the locks defined by <strong>lockstring</strong>.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><em>access (bool)</em> – If check is passed or not.</p>
</dd>
</dl>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="evennia.locks.lockhandler.check_perm">
<span class="sig-prename descclassname"><span class="pre">evennia.locks.lockhandler.</span></span><span class="sig-name descname"><span class="pre">check_perm</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">permission</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">no_superuser_bypass</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/locks/lockhandler.html#check_perm"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.locks.lockhandler.check_perm" title="Link to this definition"></a></dt>
<dd><p>Shortcut for checking if an object has the given <strong>permission</strong>. If the
permission is in <strong>settings.PERMISSION_HIERARCHY</strong>, the check passes
if the object has this permission or higher.</p>
<p>This is equivalent to calling the perm() lockfunc, but without needing
an accessed object.</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><em>, </em><em>Account</em>) – The object to check access. If this has a linked
Account, the account is checked instead (same rules as per perm()).</p></li>
<li><p><strong>permission</strong> (<em>str</em>) – The permission string to check.</p></li>
<li><p><strong>no_superuser_bypass</strong> (<em>bool</em><em>, </em><em>optional</em>) – If unset, the superuser
will always pass this check.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="evennia.locks.lockhandler.get_all_lockfuncs">
<span class="sig-prename descclassname"><span class="pre">evennia.locks.lockhandler.</span></span><span class="sig-name descname"><span class="pre">get_all_lockfuncs</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/locks/lockhandler.html#get_all_lockfuncs"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.locks.lockhandler.get_all_lockfuncs" title="Link to this definition"></a></dt>
<dd><p>Get a dict of available lock funcs.</p>
<dl class="field-list simple">
<dt class="field-odd">Returns<span class="colon">:</span></dt>
<dd class="field-odd"><p><em>lockfuncs (dict)</em> – Mapping {lockfuncname:func}.</p>
</dd>
</dl>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="evennia.locks.lockhandler.validate_lockstring">
<span class="sig-prename descclassname"><span class="pre">evennia.locks.lockhandler.</span></span><span class="sig-name descname"><span class="pre">validate_lockstring</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">lockstring</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/locks/lockhandler.html#validate_lockstring"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.locks.lockhandler.validate_lockstring" title="Link to this definition"></a></dt>
<dd><p>Validate so lockstring is on a valid form.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>lockstring</strong> (<em>str</em>) – Lockstring to validate.</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><p><em>is_valid (bool)</em> – If the lockstring is valid or not.
error (str or None): A string describing the error, or None</p>
<blockquote>
<div><p>if no error was found.</p>
</div></blockquote>
</p>
</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.locks.lockhandler</a><ul>
<li><a class="reference internal" href="#evennia.locks.lockhandler.LockHandler"><code class="docutils literal notranslate"><span class="pre">LockHandler</span></code></a><ul>
<li><a class="reference internal" href="#evennia.locks.lockhandler.LockHandler.__init__"><code class="docutils literal notranslate"><span class="pre">LockHandler.__init__()</span></code></a></li>
<li><a class="reference internal" href="#evennia.locks.lockhandler.LockHandler.cache_lock_bypass"><code class="docutils literal notranslate"><span class="pre">LockHandler.cache_lock_bypass()</span></code></a></li>
<li><a class="reference internal" href="#evennia.locks.lockhandler.LockHandler.add"><code class="docutils literal notranslate"><span class="pre">LockHandler.add()</span></code></a></li>
<li><a class="reference internal" href="#evennia.locks.lockhandler.LockHandler.validate"><code class="docutils literal notranslate"><span class="pre">LockHandler.validate()</span></code></a></li>
<li><a class="reference internal" href="#evennia.locks.lockhandler.LockHandler.replace"><code class="docutils literal notranslate"><span class="pre">LockHandler.replace()</span></code></a></li>
<li><a class="reference internal" href="#evennia.locks.lockhandler.LockHandler.get"><code class="docutils literal notranslate"><span class="pre">LockHandler.get()</span></code></a></li>
<li><a class="reference internal" href="#evennia.locks.lockhandler.LockHandler.all"><code class="docutils literal notranslate"><span class="pre">LockHandler.all()</span></code></a></li>
<li><a class="reference internal" href="#evennia.locks.lockhandler.LockHandler.remove"><code class="docutils literal notranslate"><span class="pre">LockHandler.remove()</span></code></a></li>
<li><a class="reference internal" href="#evennia.locks.lockhandler.LockHandler.delete"><code class="docutils literal notranslate"><span class="pre">LockHandler.delete()</span></code></a></li>
<li><a class="reference internal" href="#evennia.locks.lockhandler.LockHandler.clear"><code class="docutils literal notranslate"><span class="pre">LockHandler.clear()</span></code></a></li>
<li><a class="reference internal" href="#evennia.locks.lockhandler.LockHandler.reset"><code class="docutils literal notranslate"><span class="pre">LockHandler.reset()</span></code></a></li>
<li><a class="reference internal" href="#evennia.locks.lockhandler.LockHandler.append"><code class="docutils literal notranslate"><span class="pre">LockHandler.append()</span></code></a></li>
<li><a class="reference internal" href="#evennia.locks.lockhandler.LockHandler.check"><code class="docutils literal notranslate"><span class="pre">LockHandler.check()</span></code></a></li>
<li><a class="reference internal" href="#evennia.locks.lockhandler.LockHandler.check_lockstring"><code class="docutils literal notranslate"><span class="pre">LockHandler.check_lockstring()</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#evennia.locks.lockhandler.LockException"><code class="docutils literal notranslate"><span class="pre">LockException</span></code></a></li>
<li><a class="reference internal" href="#evennia.locks.lockhandler.check_lockstring"><code class="docutils literal notranslate"><span class="pre">check_lockstring()</span></code></a></li>
<li><a class="reference internal" href="#evennia.locks.lockhandler.check_perm"><code class="docutils literal notranslate"><span class="pre">check_perm()</span></code></a></li>
<li><a class="reference internal" href="#evennia.locks.lockhandler.get_all_lockfuncs"><code class="docutils literal notranslate"><span class="pre">get_all_lockfuncs()</span></code></a></li>
<li><a class="reference internal" href="#evennia.locks.lockhandler.validate_lockstring"><code class="docutils literal notranslate"><span class="pre">validate_lockstring()</span></code></a></li>
</ul>
</li>
</ul>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="evennia.locks.lockfuncs.html"
title="previous chapter">evennia.locks.lockfuncs</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="evennia.objects.html"
title="next chapter">evennia.objects</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.locks.lockhandler.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>
Updated HTML docs.
2026-02-15 18:13:08 +00:00
<li>
<a href="https://www.evennia.com/docs/6.x/index.html">v6.0.0 branch (outdated)</a>
</li>
Updated HTML docs.
2025-08-15 18:14:21 +00:00
<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.objects.html" title="evennia.objects"
>next</a> |</li>
<li class="right" >
<a href="evennia.locks.lockfuncs.html" title="evennia.locks.lockfuncs"
>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.locks.html" >evennia.locks</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">evennia.locks.lockhandler</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>
Reference in a new issue Copy permalink