Andreas/evennia
1
0
Fork 0
mirror of https://github.com/evennia/evennia.git synced 2026-03-18 13:56:30 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions
evennia/docs/3.x/api/evennia.locks.lockhandler.html
Griatch a2f5d016d4 Fix 3.x legacy doc versioning
2023-12-21 00:12:31 +01:00

521 lines
No EOL
29 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>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>evennia.locks.lockhandler &#8212; Evennia 3.x documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<link rel="shortcut 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="admonition important">
<p class="first admonition-title">Note</p>
<p class="last">You are reading an old version of the Evennia documentation. <a href="https://www.evennia.com/docs/latest/index.html">The latest version is here</a></p>.
</div>
<div class="related" role="navigation" aria-label="related navigation">
<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 3.x</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="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/evennia_logo.png" alt="Logo"/>
</a></p>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
<h4>Previous topic</h4>
<p class="topless"><a href="evennia.locks.lockfuncs.html"
title="previous chapter">evennia.locks.lockfuncs</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="evennia.objects.html"
title="next chapter">evennia.objects</a></p>
<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>
</div>
</div>
<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="Permalink to this headline"></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 id="evennia.locks.lockhandler.LockHandler">
<em class="property">class </em><code class="sig-prename descclassname">evennia.locks.lockhandler.</code><code class="sig-name descname">LockHandler</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">obj</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/locks/lockhandler.html#LockHandler"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.locks.lockhandler.LockHandler" title="Permalink 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 id="evennia.locks.lockhandler.LockHandler.__init__">
<code class="sig-name descname">__init__</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">obj</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/locks/lockhandler.html#LockHandler.__init__"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.locks.lockhandler.LockHandler.__init__" title="Permalink 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</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 id="evennia.locks.lockhandler.LockHandler.cache_lock_bypass">
<code class="sig-name descname">cache_lock_bypass</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">obj</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">[source]</span></a><a class="headerlink" href="#evennia.locks.lockhandler.LockHandler.cache_lock_bypass" title="Permalink 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</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 id="evennia.locks.lockhandler.LockHandler.add">
<code class="sig-name descname">add</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">lockstring</span></em>, <em class="sig-param"><span class="n">validate_only</span><span class="o">=</span><span class="default_value">False</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/locks/lockhandler.html#LockHandler.add"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.locks.lockhandler.LockHandler.add" title="Permalink to this definition"></a></dt>
<dd><p>Add a new lockstring to handler.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</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</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 id="evennia.locks.lockhandler.LockHandler.validate">
<code class="sig-name descname">validate</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">lockstring</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/locks/lockhandler.html#LockHandler.validate"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.locks.lockhandler.LockHandler.validate" title="Permalink to this definition"></a></dt>
<dd><p>Validate lockstring syntactically, without saving it.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><strong>lockstring</strong> (<em>str</em>) – Lockstring to validate.</p>
</dd>
<dt class="field-even">Returns</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 id="evennia.locks.lockhandler.LockHandler.replace">
<code class="sig-name descname">replace</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">lockstring</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/locks/lockhandler.html#LockHandler.replace"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.locks.lockhandler.LockHandler.replace" title="Permalink to this definition"></a></dt>
<dd><p>Replaces the lockstring entirely.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><strong>lockstring</strong> (<em>str</em>) – The new lock definition.</p>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><p><em>success (bool)</em> – False if an error occurred.</p>
</dd>
<dt class="field-odd">Raises</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 id="evennia.locks.lockhandler.LockHandler.get">
<code class="sig-name descname">get</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">access_type</span><span class="o">=</span><span class="default_value">None</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/locks/lockhandler.html#LockHandler.get"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.locks.lockhandler.LockHandler.get" title="Permalink 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</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</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 id="evennia.locks.lockhandler.LockHandler.all">
<code class="sig-name descname">all</code><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">[source]</span></a><a class="headerlink" href="#evennia.locks.lockhandler.LockHandler.all" title="Permalink to this definition"></a></dt>
<dd><p>Return all lockstrings</p>
<dl class="field-list simple">
<dt class="field-odd">Returns</dt>
<dd class="field-odd"><p><em>lockstrings (list)</em> – All separate lockstrings</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt id="evennia.locks.lockhandler.LockHandler.remove">
<code class="sig-name descname">remove</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">access_type</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/locks/lockhandler.html#LockHandler.remove"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.locks.lockhandler.LockHandler.remove" title="Permalink 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</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</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 id="evennia.locks.lockhandler.LockHandler.delete">
<code class="sig-name descname">delete</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">access_type</span></em><span class="sig-paren">)</span><a class="headerlink" href="#evennia.locks.lockhandler.LockHandler.delete" title="Permalink 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</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</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 id="evennia.locks.lockhandler.LockHandler.clear">
<code class="sig-name descname">clear</code><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">[source]</span></a><a class="headerlink" href="#evennia.locks.lockhandler.LockHandler.clear" title="Permalink to this definition"></a></dt>
<dd><p>Remove all locks in the handler.</p>
</dd></dl>
<dl class="py method">
<dt id="evennia.locks.lockhandler.LockHandler.reset">
<code class="sig-name descname">reset</code><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">[source]</span></a><a class="headerlink" href="#evennia.locks.lockhandler.LockHandler.reset" title="Permalink 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 id="evennia.locks.lockhandler.LockHandler.append">
<code class="sig-name descname">append</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">access_type</span></em>, <em class="sig-param"><span class="n">lockstring</span></em>, <em class="sig-param"><span class="n">op</span><span class="o">=</span><span class="default_value">'or'</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/locks/lockhandler.html#LockHandler.append"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.locks.lockhandler.LockHandler.append" title="Permalink 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</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 id="evennia.locks.lockhandler.LockHandler.check">
<code class="sig-name descname">check</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">accessing_obj</span></em>, <em class="sig-param"><span class="n">access_type</span></em>, <em class="sig-param"><span class="n">default</span><span class="o">=</span><span class="default_value">False</span></em>, <em class="sig-param"><span class="n">no_superuser_bypass</span><span class="o">=</span><span class="default_value">False</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/locks/lockhandler.html#LockHandler.check"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.locks.lockhandler.LockHandler.check" title="Permalink 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</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 id="evennia.locks.lockhandler.LockHandler.check_lockstring">
<code class="sig-name descname">check_lockstring</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">accessing_obj</span></em>, <em class="sig-param"><span class="n">lockstring</span></em>, <em class="sig-param"><span class="n">no_superuser_bypass</span><span class="o">=</span><span class="default_value">False</span></em>, <em class="sig-param"><span class="n">default</span><span class="o">=</span><span class="default_value">False</span></em>, <em class="sig-param"><span class="n">access_type</span><span class="o">=</span><span class="default_value">None</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/locks/lockhandler.html#LockHandler.check_lockstring"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.locks.lockhandler.LockHandler.check_lockstring" title="Permalink 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</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</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 id="evennia.locks.lockhandler.LockException">
<em class="property">exception </em><code class="sig-prename descclassname">evennia.locks.lockhandler.</code><code class="sig-name descname">LockException</code><a class="reference internal" href="../_modules/evennia/locks/lockhandler.html#LockException"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.locks.lockhandler.LockException" title="Permalink 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>
</section>
</div>
</div>
</div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<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 3.x</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="admonition important">
<p class="first admonition-title">Note</p>
<p class="last">You are reading an old version of the Evennia documentation. <a href="https://www.evennia.com/docs/latest/index.html">The latest version is here</a></p>.
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2023, The Evennia developer community.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.2.1.
</div>
</body>
</html>
Reference in a new issue View git blame Copy permalink