evennia/docs/0.x/api/evennia.contrib.random_string_generator.html
2023-12-20 19:10:09 +01:00

327 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>
<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.contrib.random_string_generator &#8212; Evennia 0.9.5 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>
<script async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script type="text/x-mathjax-config">MathJax.Hub.Config({"tex2jax": {"processClass": "tex2jax_process|mathjax_process|math|output_area"}})</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" />
</head><body>
<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="nav-item nav-item-0"><a href="../index.html">Evennia 0.9.5</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">evennia.contrib.random_string_generator</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="module-evennia.contrib.random_string_generator">
<span id="evennia-contrib-random-string-generator"></span><h1>evennia.contrib.random_string_generator<a class="headerlink" href="#module-evennia.contrib.random_string_generator" title="Permalink to this headline"></a></h1>
<p>Pseudo-random generator and registry</p>
<p>Evennia contribution - Vincent Le Goff 2017</p>
<p>This contrib can be used to generate pseudo-random strings of information
with specific criteria. You could, for instance, use it to generate
phone numbers, license plate numbers, validation codes, non-sensivite
passwords and so on. The strings generated by the generator will be
stored and wont be available again in order to avoid repetition.
Heres a very simple example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">evennia.contrib.random_string_generator</span> <span class="kn">import</span> <span class="n">RandomStringGenerator</span>
<span class="c1"># Create a generator for phone numbers</span>
<span class="n">phone_generator</span> <span class="o">=</span> <span class="n">RandomStringGenerator</span><span class="p">(</span><span class="s2">&quot;phone number&quot;</span><span class="p">,</span> <span class="sa">r</span><span class="s2">&quot;555-[0-9]</span><span class="si">{3}</span><span class="s2">-[0-9]</span><span class="si">{4}</span><span class="s2">&quot;</span><span class="p">)</span>
<span class="c1"># Generate a phone number (555-XXX-XXXX with X as numbers)</span>
<span class="n">number</span> <span class="o">=</span> <span class="n">phone_generator</span><span class="o">.</span><span class="n">get</span><span class="p">()</span>
<span class="c1"># **number** will contain something like: &quot;555-981-2207&quot;</span>
<span class="c1"># If you call **phone_generator.get**, it won&#39;t give the same anymore.phone_generator.all()</span>
<span class="c1"># Will return a list of all currently-used phone numbers</span>
<span class="n">phone_generator</span><span class="o">.</span><span class="n">remove</span><span class="p">(</span><span class="s2">&quot;555-981-2207&quot;</span><span class="p">)</span>
<span class="c1"># The number can be generated again</span>
</pre></div>
</div>
<p>To use it, you will need to:</p>
<ol class="arabic simple">
<li><p>Import the <strong>RandomStringGenerator</strong> class from the contrib.</p></li>
<li><p>Create an instance of this class taking two arguments:
- The name of the gemerator (like “phone number”, “license plate”…).
- The regular expression representing the expected results.</p></li>
<li><p>Use the generators <strong>all</strong>, <strong>get</strong> and <strong>remove</strong> methods as shown above.</p></li>
</ol>
<p>To understand how to read and create regular expressions, you can refer to
[the documentation on the re module](<a class="reference external" href="https://docs.python.org/2/library/re.html">https://docs.python.org/2/library/re.html</a>).
Some examples of regular expressions you could use:</p>
<ul class="simple">
<li><p><strong>r”555-d{3}-d{4}”</strong>: 555, a dash, 3 digits, another dash, 4 digits.</p></li>
<li><p><strong>r”[0-9]{3}[A-Z][0-9]{3}”</strong>: 3 digits, a capital letter, 3 digits.</p></li>
<li><p><strong>r”[A-Za-z0-9]{8,15}”</strong>: between 8 and 15 letters and digits.</p></li>
<li><p></p></li>
</ul>
<p>Behind the scenes, a script is created to store the generated information
for a single generator. The <strong>RandomStringGenerator</strong> object will also
read the regular expression you give to it to see what information is
required (letters, digits, a more restricted class, simple characters…)…
More complex regular expressions (with branches for instance) might not be
available.</p>
<dl class="py exception">
<dt id="evennia.contrib.random_string_generator.RejectedRegex">
<em class="property">exception </em><code class="sig-prename descclassname">evennia.contrib.random_string_generator.</code><code class="sig-name descname">RejectedRegex</code><a class="reference internal" href="../_modules/evennia/contrib/random_string_generator.html#RejectedRegex"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.contrib.random_string_generator.RejectedRegex" title="Permalink to this definition"></a></dt>
<dd><p>Bases: <code class="xref py py-class docutils literal notranslate"><span class="pre">RuntimeError</span></code></p>
<p>The provided regular expression has been rejected.</p>
<p>More details regarding why this error occurred will be provided in
the message. The usual reason is the provided regular expression is
not specific enough and could lead to inconsistent generating.</p>
</dd></dl>
<dl class="py exception">
<dt id="evennia.contrib.random_string_generator.ExhaustedGenerator">
<em class="property">exception </em><code class="sig-prename descclassname">evennia.contrib.random_string_generator.</code><code class="sig-name descname">ExhaustedGenerator</code><a class="reference internal" href="../_modules/evennia/contrib/random_string_generator.html#ExhaustedGenerator"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.contrib.random_string_generator.ExhaustedGenerator" title="Permalink to this definition"></a></dt>
<dd><p>Bases: <code class="xref py py-class docutils literal notranslate"><span class="pre">RuntimeError</span></code></p>
<p>The generator hasnt any available strings to generate anymore.</p>
</dd></dl>
<dl class="py class">
<dt id="evennia.contrib.random_string_generator.RandomStringGeneratorScript">
<em class="property">class </em><code class="sig-prename descclassname">evennia.contrib.random_string_generator.</code><code class="sig-name descname">RandomStringGeneratorScript</code><span class="sig-paren">(</span><em class="sig-param"><span class="o">*</span><span class="n">args</span></em>, <em class="sig-param"><span class="o">**</span><span class="n">kwargs</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/random_string_generator.html#RandomStringGeneratorScript"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.contrib.random_string_generator.RandomStringGeneratorScript" title="Permalink to this definition"></a></dt>
<dd><p>Bases: <a class="reference internal" href="evennia.scripts.scripts.html#evennia.scripts.scripts.DefaultScript" title="evennia.scripts.scripts.DefaultScript"><code class="xref py py-class docutils literal notranslate"><span class="pre">evennia.scripts.scripts.DefaultScript</span></code></a></p>
<p>The global script to hold all generators.</p>
<p>It will be automatically created the first time <strong>generate</strong> is called
on a RandomStringGenerator object.</p>
<dl class="py method">
<dt id="evennia.contrib.random_string_generator.RandomStringGeneratorScript.at_script_creation">
<code class="sig-name descname">at_script_creation</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/random_string_generator.html#RandomStringGeneratorScript.at_script_creation"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.contrib.random_string_generator.RandomStringGeneratorScript.at_script_creation" title="Permalink to this definition"></a></dt>
<dd><p>Hook called when the script is created.</p>
</dd></dl>
<dl class="py exception">
<dt id="evennia.contrib.random_string_generator.RandomStringGeneratorScript.DoesNotExist">
<em class="property">exception </em><code class="sig-name descname">DoesNotExist</code><a class="headerlink" href="#evennia.contrib.random_string_generator.RandomStringGeneratorScript.DoesNotExist" title="Permalink to this definition"></a></dt>
<dd><p>Bases: <a class="reference internal" href="evennia.scripts.scripts.html#evennia.scripts.scripts.DefaultScript.DoesNotExist" title="evennia.scripts.scripts.DefaultScript.DoesNotExist"><code class="xref py py-class docutils literal notranslate"><span class="pre">evennia.scripts.scripts.DefaultScript.DoesNotExist</span></code></a></p>
</dd></dl>
<dl class="py exception">
<dt id="evennia.contrib.random_string_generator.RandomStringGeneratorScript.MultipleObjectsReturned">
<em class="property">exception </em><code class="sig-name descname">MultipleObjectsReturned</code><a class="headerlink" href="#evennia.contrib.random_string_generator.RandomStringGeneratorScript.MultipleObjectsReturned" title="Permalink to this definition"></a></dt>
<dd><p>Bases: <a class="reference internal" href="evennia.scripts.scripts.html#evennia.scripts.scripts.DefaultScript.MultipleObjectsReturned" title="evennia.scripts.scripts.DefaultScript.MultipleObjectsReturned"><code class="xref py py-class docutils literal notranslate"><span class="pre">evennia.scripts.scripts.DefaultScript.MultipleObjectsReturned</span></code></a></p>
</dd></dl>
<dl class="py attribute">
<dt id="evennia.contrib.random_string_generator.RandomStringGeneratorScript.path">
<code class="sig-name descname">path</code><em class="property"> = 'evennia.contrib.random_string_generator.RandomStringGeneratorScript'</em><a class="headerlink" href="#evennia.contrib.random_string_generator.RandomStringGeneratorScript.path" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
<dt id="evennia.contrib.random_string_generator.RandomStringGeneratorScript.typename">
<code class="sig-name descname">typename</code><em class="property"> = 'RandomStringGeneratorScript'</em><a class="headerlink" href="#evennia.contrib.random_string_generator.RandomStringGeneratorScript.typename" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>
<dl class="py class">
<dt id="evennia.contrib.random_string_generator.RandomStringGenerator">
<em class="property">class </em><code class="sig-prename descclassname">evennia.contrib.random_string_generator.</code><code class="sig-name descname">RandomStringGenerator</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">name</span></em>, <em class="sig-param"><span class="n">regex</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/random_string_generator.html#RandomStringGenerator"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.contrib.random_string_generator.RandomStringGenerator" 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>A generator class to generate pseudo-random strings with a rule.</p>
<p>The “rule” defining what the generator should provide in terms of
string is given as a regular expression when creating instances of
this class. You can use the <strong>all</strong> method to get all generated strings,
the <strong>get</strong> method to generate a new string, the <strong>remove</strong> method
to remove a generated string, or the <strong>clear</strong> method to remove all
generated strings.</p>
<p>Bear in mind, however, that while the generated strings will be
stored to avoid repetition, the generator will not concern itself
with how the string is stored on the object you use. You probably
want to create a tag to mark this object. This is outside of the scope
of this class.</p>
<dl class="py attribute">
<dt id="evennia.contrib.random_string_generator.RandomStringGenerator.script">
<code class="sig-name descname">script</code><em class="property"> = None</em><a class="headerlink" href="#evennia.contrib.random_string_generator.RandomStringGenerator.script" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py method">
<dt id="evennia.contrib.random_string_generator.RandomStringGenerator.__init__">
<code class="sig-name descname">__init__</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">name</span></em>, <em class="sig-param"><span class="n">regex</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/random_string_generator.html#RandomStringGenerator.__init__"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.contrib.random_string_generator.RandomStringGenerator.__init__" title="Permalink to this definition"></a></dt>
<dd><p>Create a new generator.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>name</strong> (<em>str</em>) name of the generator to create.</p></li>
<li><p><strong>regex</strong> (<em>str</em>) regular expression describing the generator.</p></li>
</ul>
</dd>
</dl>
<p class="rubric">Notes</p>
<p><strong>name</strong> should be an explicit name. If you use more than one
generator in your game, be sure to give them different names.
This name will be used to store the generated information
in the global script, and in case of errors.</p>
<p>The regular expression should describe the generator, what
it should generate: a phone number, a license plate, a password
or something else. Regular expressions allow you to use
pretty advanced criteria, but be aware that some regular
expressions will be rejected if not specific enough.</p>
<dl class="field-list simple">
<dt class="field-odd">Raises</dt>
<dd class="field-odd"><ul class="simple">
<li><p><a class="reference internal" href="#evennia.contrib.random_string_generator.RejectedRegex" title="evennia.contrib.random_string_generator.RejectedRegex"><strong>RejectedRegex</strong></a> the provided regular expression couldnt be</p></li>
<li><p><strong>accepted as a valid generator description.</strong> </p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt id="evennia.contrib.random_string_generator.RandomStringGenerator.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/contrib/random_string_generator.html#RandomStringGenerator.all"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.contrib.random_string_generator.RandomStringGenerator.all" title="Permalink to this definition"></a></dt>
<dd><p>Return all generated strings for this generator.</p>
<dl class="field-list simple">
<dt class="field-odd">Returns</dt>
<dd class="field-odd"><p><em>strings (list of strr)</em> the list of strings that are already
used. The strings that were generated first come first in the list.</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt id="evennia.contrib.random_string_generator.RandomStringGenerator.get">
<code class="sig-name descname">get</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">store</span><span class="o">=</span><span class="default_value">True</span></em>, <em class="sig-param"><span class="n">unique</span><span class="o">=</span><span class="default_value">True</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/random_string_generator.html#RandomStringGenerator.get"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.contrib.random_string_generator.RandomStringGenerator.get" title="Permalink to this definition"></a></dt>
<dd><p>Generate a pseudo-random string according to the regular expression.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>store</strong> (<em>bool</em><em>, </em><em>optional</em>) store the generated string in the script.</p></li>
<li><p><strong>unique</strong> (<em>bool</em><em>, </em><em>optional</em>) keep on trying if the string is already used.</p></li>
</ul>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><p>The newly-generated string.</p>
</dd>
<dt class="field-odd">Raises</dt>
<dd class="field-odd"><p><a class="reference internal" href="#evennia.contrib.random_string_generator.ExhaustedGenerator" title="evennia.contrib.random_string_generator.ExhaustedGenerator"><strong>ExhaustedGenerator</strong></a> if theres no available string in this generator.</p>
</dd>
</dl>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Unless asked explicitly, the returned string cant repeat itself.</p>
</div>
</dd></dl>
<dl class="py method">
<dt id="evennia.contrib.random_string_generator.RandomStringGenerator.remove">
<code class="sig-name descname">remove</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">element</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/random_string_generator.html#RandomStringGenerator.remove"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.contrib.random_string_generator.RandomStringGenerator.remove" title="Permalink to this definition"></a></dt>
<dd><p>Remove a generated string from the list of stored strings.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><strong>element</strong> (<em>str</em>) the string to remove from the list of generated strings.</p>
</dd>
<dt class="field-even">Raises</dt>
<dd class="field-even"><p><strong>ValueError</strong> the specified value hasnt been generated and is not present.</p>
</dd>
</dl>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The specified string has to be present in the script (so
has to have been generated). It will remove this entry
from the script, so this string could be generated again by
calling the <strong>get</strong> method.</p>
</div>
</dd></dl>
<dl class="py method">
<dt id="evennia.contrib.random_string_generator.RandomStringGenerator.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/contrib/random_string_generator.html#RandomStringGenerator.clear"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.contrib.random_string_generator.RandomStringGenerator.clear" title="Permalink to this definition"></a></dt>
<dd><p>Clear the generator of all generated strings.</p>
</dd></dl>
</dd></dl>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<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>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/api/evennia.contrib.random_string_generator.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div><h3>Links</h3>
<ul>
<li><a href="https://www.evennia.com">Home page</a> </li>
<li><a href="https://github.com/evennia/evennia">Evennia Github</a> </li>
<li><a href="http://games.evennia.com">Game Index</a> </li>
<li><a href="http://webchat.freenode.net/?channels=evennia&uio=MT1mYWxzZSY5PXRydWUmMTE9MTk1JjEyPXRydWUbb">IRC</a> -
<a href="https://discord.gg/NecFePw">Discord</a> -
<a href="https://groups.google.com/forum/#%21forum/evennia">Forums</a>
</li>
<li><a href="http://evennia.blogspot.com/">Evennia Dev blog</a> </li>
</ul>
<h3>Versions</h3>
<ul>
<li><a href="../../1.0-dev/index.html">1.0-dev (develop branch)</a></li>
<li><a href="evennia.contrib.random_string_generator.html">0.9.5 (v0.9.5 branch)</a></li>
</ul>
</div>
</div>
<div class="clearer"></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="nav-item nav-item-0"><a href="../index.html">Evennia 0.9.5</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">evennia.contrib.random_string_generator</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2020, The Evennia developer community.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.2.1.
</div>
</body>
</html>