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

231 lines
No EOL
13 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.utils.dbserialize &#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.utils.eveditor" href="evennia.utils.eveditor.html" />
<link rel="prev" title="evennia.utils.create" href="evennia.utils.create.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.utils.eveditor.html" title="evennia.utils.eveditor"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="evennia.utils.create.html" title="evennia.utils.create"
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.utils.html" accesskey="U">evennia.utils</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">evennia.utils.dbserialize</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.utils.create.html"
title="previous chapter">evennia.utils.create</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="evennia.utils.eveditor.html"
title="next chapter">evennia.utils.eveditor</a></p>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/api/evennia.utils.dbserialize.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.utils.dbserialize">
<span id="evennia-utils-dbserialize"></span><h1>evennia.utils.dbserialize<a class="headerlink" href="#module-evennia.utils.dbserialize" title="Permalink to this headline"></a></h1>
<p>This module handles serialization of arbitrary python structural data,
intended primarily to be stored in the database. It also supports
storing Django model instances (which plain pickle cannot do).</p>
<p>This serialization is used internally by the server, notably for
storing data in Attributes and for piping data to process pools.</p>
<p>The purpose of dbserialize is to handle all forms of data. For
well-structured non-arbitrary exchange, such as communicating with a
rich web client, a simpler JSON serialization makes more sense.</p>
<p>This module also implements the <strong>SaverList</strong>, <strong>SaverDict</strong> and <strong>SaverSet</strong>
classes. These are iterables that track their position in a nested
structure and makes sure to send updates up to their root. This is
used by Attributes - without it, one would not be able to update mutables
in-situ, e.g <strong>obj.db.mynestedlist[3][5] = 3</strong> would never be saved and
be out of sync with the database.</p>
<dl class="py function">
<dt id="evennia.utils.dbserialize.to_pickle">
<code class="sig-prename descclassname">evennia.utils.dbserialize.</code><code class="sig-name descname">to_pickle</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">data</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/utils/dbserialize.html#to_pickle"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.utils.dbserialize.to_pickle" title="Permalink to this definition"></a></dt>
<dd><p>This prepares data on arbitrary form to be pickled. It handles any
nested structure and returns data on a form that is safe to pickle
(including having converted any database models to their internal
representation). We also convert any Saver*-type objects back to
their normal representations, they are not pickle-safe.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><strong>data</strong> (<em>any</em>) – Data to pickle.</p>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><p><em>data (any)</em> – Pickled data.</p>
</dd>
</dl>
</dd></dl>
<dl class="py function">
<dt id="evennia.utils.dbserialize.from_pickle">
<code class="sig-prename descclassname">evennia.utils.dbserialize.</code><code class="sig-name descname">from_pickle</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">data</span></em>, <em class="sig-param"><span class="n">db_obj</span><span class="o">=</span><span class="default_value">None</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/utils/dbserialize.html#from_pickle"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.utils.dbserialize.from_pickle" title="Permalink to this definition"></a></dt>
<dd><p>This should be fed a just de-pickled data object. It will be converted back
to a form that may contain database objects again. Note that if a database
object was removed (or changed in-place) in the database, None will be
returned.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>data</strong> (<em>any</em>) – Pickled data to unpickle.</p></li>
<li><p><strong>db_obj</strong> (<em>Atribute</em><em>, </em><em>any</em>) – This is the model instance (normally
an Attribute) that _Saver*-type iterables (_SaverList etc)
will save to when they update. It must have a ‘value’ property
that saves assigned data to the database. Skip if not
serializing onto a given object. If db_obj is given, this
function will convert lists, dicts and sets to their
_SaverList, _SaverDict and _SaverSet counterparts.</p></li>
</ul>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><p><em>data (any)</em> – Unpickled data.</p>
</dd>
</dl>
</dd></dl>
<dl class="py function">
<dt id="evennia.utils.dbserialize.do_pickle">
<code class="sig-prename descclassname">evennia.utils.dbserialize.</code><code class="sig-name descname">do_pickle</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">data</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/utils/dbserialize.html#do_pickle"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.utils.dbserialize.do_pickle" title="Permalink to this definition"></a></dt>
<dd><p>Perform pickle to string</p>
</dd></dl>
<dl class="py function">
<dt id="evennia.utils.dbserialize.do_unpickle">
<code class="sig-prename descclassname">evennia.utils.dbserialize.</code><code class="sig-name descname">do_unpickle</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">data</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/utils/dbserialize.html#do_unpickle"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.utils.dbserialize.do_unpickle" title="Permalink to this definition"></a></dt>
<dd><p>Retrieve pickle from pickled string</p>
</dd></dl>
<dl class="py function">
<dt id="evennia.utils.dbserialize.dbserialize">
<code class="sig-prename descclassname">evennia.utils.dbserialize.</code><code class="sig-name descname">dbserialize</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">data</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/utils/dbserialize.html#dbserialize"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.utils.dbserialize.dbserialize" title="Permalink to this definition"></a></dt>
<dd><p>Serialize to pickled form in one step</p>
</dd></dl>
<dl class="py function">
<dt id="evennia.utils.dbserialize.dbunserialize">
<code class="sig-prename descclassname">evennia.utils.dbserialize.</code><code class="sig-name descname">dbunserialize</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">data</span></em>, <em class="sig-param"><span class="n">db_obj</span><span class="o">=</span><span class="default_value">None</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/utils/dbserialize.html#dbunserialize"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.utils.dbserialize.dbunserialize" title="Permalink to this definition"></a></dt>
<dd><p>Un-serialize in one step. See from_pickle for help db_obj.</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.utils.eveditor.html" title="evennia.utils.eveditor"
>next</a> |</li>
<li class="right" >
<a href="evennia.utils.create.html" title="evennia.utils.create"
>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.utils.html" >evennia.utils</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">evennia.utils.dbserialize</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