/usr/share/doc/python-oslo.versionedobjects-doc/html/usage.html is in python-oslo.versionedobjects-doc 1.8.0-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Usage — oslo.versionedobjects documentation</title>
<link rel="stylesheet" href="_static/nature.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/tweaks.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="top" title="oslo.versionedobjects documentation" href="index.html" />
<link rel="next" title="Configuration Options" href="opts.html" />
<link rel="prev" title="Fixture" href="api/fixture.html" />
</head>
<body role="document">
<div id="header">
<h1 id="logo"><a href="http://www.openstack.org/">OpenStack</a></h1>
<ul id="navigation">
<li><a href="http://www.openstack.org/" title="Go to the Home page" class="link">Home</a></li>
<li><a href="http://www.openstack.org/projects/" title="Go to the OpenStack Projects page">Projects</a></li>
<li><a href="http://www.openstack.org/user-stories/" title="Go to the User Stories page" class="link">User Stories</a></li>
<li><a href="http://www.openstack.org/community/" title="Go to the Community page" class="link">Community</a></li>
<li><a href="http://www.openstack.org/blog/" title="Go to the OpenStack Blog">Blog</a></li>
<li><a href="http://wiki.openstack.org/" title="Go to the OpenStack Wiki">Wiki</a></li>
<li><a href="http://docs.openstack.org/" title="Go to OpenStack Documentation" class="current">Documentation</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="usage">
<h1>Usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h1>
<p>Incorporating oslo.versionedobjects into your projects can be accomplished in
the following steps:</p>
<ol class="arabic simple">
<li><a class="reference internal" href="#add-oslo-versionedobjects-to-requirements">Add oslo.versionedobjects to requirements</a></li>
<li><a class="reference internal" href="#create-objects-subdirectory-and-a-base-py-inside-it">Create objects subdirectory and a base.py inside it</a></li>
<li><a class="reference internal" href="#create-base-object-with-the-project-namespace">Create base object with the project namespace</a></li>
<li><a class="reference internal" href="#create-other-base-objects-if-needed">Create other base objects if needed</a></li>
<li><a class="reference internal" href="#implement-objects-and-place-them-in-objects-py">Implement objects and place them in objects/*.py</a></li>
<li><a class="reference internal" href="#implement-extra-fields-in-objects-fields-py">Implement extra fields in objects/fields.py</a></li>
<li><a class="reference internal" href="#create-object-registry-and-register-all-objects">Create object registry and register all objects</a></li>
<li><a class="reference internal" href="#create-and-attach-the-object-serializer">Create and attach the object serializer</a></li>
<li><a class="reference internal" href="#implement-the-indirection-api">Implement the indirection API</a></li>
</ol>
<div class="section" id="add-oslo-versionedobjects-to-requirements">
<h2>Add oslo.versionedobjects to requirements<a class="headerlink" href="#add-oslo-versionedobjects-to-requirements" title="Permalink to this headline">¶</a></h2>
<p>To use oslo.versionedobjects in an OpenStack project remember to add it to the
requirements.txt</p>
</div>
<div class="section" id="create-objects-subdirectory-and-a-base-py-inside-it">
<h2>Create objects subdirectory and a base.py inside it<a class="headerlink" href="#create-objects-subdirectory-and-a-base-py-inside-it" title="Permalink to this headline">¶</a></h2>
<p>Objects reside in the <cite><project>/objects</cite> directory and this is the place
from which all objects should be imported.</p>
<p>Start the implementation by creating <cite>objects/base.py</cite> with these main
classes:</p>
</div>
<div class="section" id="create-base-object-with-the-project-namespace">
<h2>Create base object with the project namespace<a class="headerlink" href="#create-base-object-with-the-project-namespace" title="Permalink to this headline">¶</a></h2>
<p><a class="reference internal" href="api/base.html#oslo_versionedobjects.base.VersionedObject" title="oslo_versionedobjects.base.VersionedObject"><code class="xref py py-class docutils literal"><span class="pre">oslo_versionedobjects.base.VersionedObject</span></code></a></p>
<p>The VersionedObject base class for the project. You have to fill up the
<cite>OBJ_PROJECT_NAMESPACE</cite> property. <cite>OBJ_SERIAL_NAMESPACE</cite> is used only for
backward compatibility and should not be set in new projects.</p>
</div>
<div class="section" id="create-other-base-objects-if-needed">
<h2>Create other base objects if needed<a class="headerlink" href="#create-other-base-objects-if-needed" title="Permalink to this headline">¶</a></h2>
<p>class:<cite>oslo_versionedobjects.base.VersionedPersistentObject</cite></p>
<p>A mixin class for persistent objects can be created, defining repeated fields
like <cite>created_at</cite>, <cite>updated_at</cite>. Fields are defined in the fields property
(which is a dict).</p>
<p>If objects were previously passed as dicts (a common situation), a
<a class="reference internal" href="api/base.html#oslo_versionedobjects.base.VersionedObjectDictCompat" title="oslo_versionedobjects.base.VersionedObjectDictCompat"><code class="xref py py-class docutils literal"><span class="pre">oslo_versionedobjects.base.VersionedObjectDictCompat</span></code></a> can be used as a
mixin class to support dict operations.</p>
</div>
<div class="section" id="implement-objects-and-place-them-in-objects-py">
<h2>Implement objects and place them in objects/*.py<a class="headerlink" href="#implement-objects-and-place-them-in-objects-py" title="Permalink to this headline">¶</a></h2>
<p>Objects classes should be created for all resources/objects passed via RPC
as IDs or dicts in order to:</p>
<ul class="simple">
<li>spare the database (or other resource) from extra calls</li>
<li>pass objects instead of dicts, which are tagged with their version</li>
<li>handle all object versions in one place (the <cite>obj_make_compatible</cite> method)</li>
</ul>
<p>To make sure all objects are accessible at all times, you should import them
in __init__.py in the objects/ directory.</p>
</div>
<div class="section" id="implement-extra-fields-in-objects-fields-py">
<h2>Implement extra fields in objects/fields.py<a class="headerlink" href="#implement-extra-fields-in-objects-fields-py" title="Permalink to this headline">¶</a></h2>
<p>New field types can be implemented by inheriting from
<code class="xref py py-class docutils literal"><span class="pre">oslo_versionedobjects.field.Field</span></code> and overwriting the <cite>from_primitive</cite>
and <cite>to_primitive</cite> methods.</p>
<p>By subclassing :class:oslo_versionedobjects.fields.AutoTypedField you can
stack multiple fields together, making sure even nested data structures are
being validated.</p>
</div>
<div class="section" id="create-object-registry-and-register-all-objects">
<h2>Create object registry and register all objects<a class="headerlink" href="#create-object-registry-and-register-all-objects" title="Permalink to this headline">¶</a></h2>
<p><code class="xref py py-class docutils literal"><span class="pre">oslo_versionedobjects.base.VersionedObjectRegistry</span></code></p>
<p>The place where all objects are registered. All object classes should be
registered by the <code class="xref py py-attr docutils literal"><span class="pre">oslo_versionedobjects.base.ObjectRegistry.register</span></code>
class decorator.</p>
</div>
<div class="section" id="create-and-attach-the-object-serializer">
<h2>Create and attach the object serializer<a class="headerlink" href="#create-and-attach-the-object-serializer" title="Permalink to this headline">¶</a></h2>
<p><a class="reference internal" href="api/base.html#oslo_versionedobjects.base.VersionedObjectSerializer" title="oslo_versionedobjects.base.VersionedObjectSerializer"><code class="xref py py-class docutils literal"><span class="pre">oslo_versionedobjects.base.VersionedObjectSerializer</span></code></a></p>
<p>To transfer objects by RPC, subclass the
<a class="reference internal" href="api/base.html#oslo_versionedobjects.base.VersionedObjectSerializer" title="oslo_versionedobjects.base.VersionedObjectSerializer"><code class="xref py py-class docutils literal"><span class="pre">oslo_versionedobjects.base.VersionedObjectSerializer</span></code></a> setting the
OBJ_BASE_CLASS property to the previously defined Object class.</p>
<p>Connect the serializer to oslo_messaging:</p>
<div class="code python highlight-python"><div class="highlight"><pre><span class="n">serializer</span> <span class="o">=</span> <span class="n">RequestContextSerializer</span><span class="p">(</span><span class="n">objects_base</span><span class="o">.</span><span class="n">MagnumObjectSerializer</span><span class="p">())</span>
<span class="n">target</span> <span class="o">=</span> <span class="n">messaging</span><span class="o">.</span><span class="n">Target</span><span class="p">(</span><span class="n">topic</span><span class="o">=</span><span class="n">topic</span><span class="p">,</span> <span class="n">server</span><span class="o">=</span><span class="n">server</span><span class="p">)</span>
<span class="bp">self</span><span class="o">.</span><span class="n">_server</span> <span class="o">=</span> <span class="n">messaging</span><span class="o">.</span><span class="n">get_rpc_server</span><span class="p">(</span><span class="n">transport</span><span class="p">,</span> <span class="n">target</span><span class="p">,</span> <span class="n">handlers</span><span class="p">,</span> <span class="n">serializer</span><span class="o">=</span><span class="n">serializer</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="implement-the-indirection-api">
<h2>Implement the indirection API<a class="headerlink" href="#implement-the-indirection-api" title="Permalink to this headline">¶</a></h2>
<p><code class="xref py py-class docutils literal"><span class="pre">oslo_versionedobjects.base.VersionedObjectIndirectionAPI</span></code></p>
<p>oslo.versionedobjects supports <cite>remotable</cite> method calls. These are calls
of the object methods and classmethods which can be executed locally or
remotely depending on the configuration. Setting the indirection_api as a
property of an object relays the calls to decorated methods through the
defined RPC API. The attachment of the indirection_api should be handled
by configuration at startup time.</p>
<p>Second function of the indirection API is backporting. When the object
serializer attempts to deserialize an object with a future version, not
supported by the current instance, it calls the object_backport method in an
attempt to backport the object to a version which can then be handled as
normal.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Usage</a><ul>
<li><a class="reference internal" href="#add-oslo-versionedobjects-to-requirements">Add oslo.versionedobjects to requirements</a></li>
<li><a class="reference internal" href="#create-objects-subdirectory-and-a-base-py-inside-it">Create objects subdirectory and a base.py inside it</a></li>
<li><a class="reference internal" href="#create-base-object-with-the-project-namespace">Create base object with the project namespace</a></li>
<li><a class="reference internal" href="#create-other-base-objects-if-needed">Create other base objects if needed</a></li>
<li><a class="reference internal" href="#implement-objects-and-place-them-in-objects-py">Implement objects and place them in objects/*.py</a></li>
<li><a class="reference internal" href="#implement-extra-fields-in-objects-fields-py">Implement extra fields in objects/fields.py</a></li>
<li><a class="reference internal" href="#create-object-registry-and-register-all-objects">Create object registry and register all objects</a></li>
<li><a class="reference internal" href="#create-and-attach-the-object-serializer">Create and attach the object serializer</a></li>
<li><a class="reference internal" href="#implement-the-indirection-api">Implement the indirection API</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="api/fixture.html"
title="previous chapter">Fixture</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="opts.html"
title="next chapter">Configuration Options</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/usage.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</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"
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="opts.html" title="Configuration Options"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="api/fixture.html" title="Fixture"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">oslo.versionedobjects documentation</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2014, OpenStack Foundation.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.3.6.
</div>
<script type="text/javascript">
try {
//Tracking docs.openstack.org/developer/<projectname> only
//The URL is built from the project variable in conf.py
var pageTracker = _gat._getTracker("UA-17511903-1");
pageTracker._setCookiePath("/developer/oslo.versionedobjects");
pageTracker._trackPageview();
} catch(err) {}</script>
</body>
</html>
|