<!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>Content Model — PyXB 1.2.6 documentation</title>
<link rel="stylesheet" href="_static/classic.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '1.2.6',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</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="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="User Reference" href="userref_index.html" />
<link rel="prev" title="Binding Model" href="arch_binding.html" />
</head>
<body role="document">
<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="userref_index.html" title="User Reference"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="arch_binding.html" title="Binding Model"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">PyXB 1.2.6 documentation</a> »</li>
<li class="nav-item nav-item-1"><a href="architecture.html" accesskey="U">Architecture</a> »</li>
<li style="margin-left: 20px">PyXB hosted on <a href="http://sourceforge.net/projects/pyxb"><img src="http://sflogo.sourceforge.net/sflogo.php?group_id=263147&type=9"
width="80" height="15" alt="Get PyXB: Python XML Schema Bindings at SourceForge.net. Fast, secure and Free Open Source software downloads"/></a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="content-model">
<span id="contentmodel"></span><h1>Content Model<a class="headerlink" href="#content-model" title="Permalink to this headline">¶</a></h1>
<p>PyXB’s content model is used to complete the link between the
<a class="reference internal" href="arch_component.html#componentmodel"><span class="std std-ref">Component Model</span></a> and the <a class="reference internal" href="arch_binding.html#bindingmodel"><span class="std std-ref">Binding Model</span></a>. These classes are the
ones that:</p>
<ul class="simple">
<li>determine what Python class attribute is used to store which XML
element or attribute;</li>
<li>distinguish those elements that can occur at most once from those that
require an aggregation; and</li>
<li>ensure that the ordering and occurrence constraints imposed by the XML
<a class="reference external" href="http://www.w3.org/TR/xmlschema-1/#Model_Groups">model group</a> are
satisfied, when XML is converted to Python instances and vice-versa.</li>
</ul>
<div class="section" id="associating-xml-and-python-objects">
<h2>Associating XML and Python Objects<a class="headerlink" href="#associating-xml-and-python-objects" title="Permalink to this headline">¶</a></h2>
<p>Most of the classes involved in the content model are in the
<a class="reference internal" href="pyxb.binding.html#module-pyxb.binding.content" title="pyxb.binding.content"><code class="xref py py-obj docutils literal"><span class="pre">pyxb.binding.content</span></code></a> module. The relations among these classes are
displayed in the following diagram.</p>
<img alt="_images/ContentModel.jpg" id="cd-contentmodel" src="_images/ContentModel.jpg" />
<p>In the standard code generation template, both element and attribute values
are stored in Python class fields. As noted in
<a class="reference internal" href="arch_binding.html#binding-deconflictingnames"><span class="std std-ref">Deconflicting Names</span></a> it is necessary to ensure an attribute and
an element which have the same name in their containing complex type have
distinct names in the Python class corresponding to that type. Use
information for each of these is maintained in the type class. This use
information comprises:</p>
<ul class="simple">
<li>the original <a class="reference internal" href="pyxb.binding.html#pyxb.binding.content.AttributeUse.name" title="pyxb.binding.content.AttributeUse.name"><code class="xref py py-obj docutils literal"><span class="pre">name</span></code></a> of the element/attribute in the XML</li>
<li>its <a class="reference internal" href="pyxb.binding.html#pyxb.binding.content.AttributeUse.id" title="pyxb.binding.content.AttributeUse.id"><code class="xref py py-obj docutils literal"><span class="pre">deconflicted</span> <span class="pre">name</span></code></a> in Python</li>
<li>the private name by which the value is stored in the Python instance dictionary</li>
</ul>
<p>Other information is specific to the type of use. The
<a class="reference internal" href="pyxb.binding.html#pyxb.binding.basis.complexTypeDefinition" title="pyxb.binding.basis.complexTypeDefinition"><code class="xref py py-obj docutils literal"><span class="pre">pyxb.binding.basis.complexTypeDefinition</span></code></a> retains maps from the
component’s name the attribute use or element use instance corresponding to
the component’s use.</p>
<div class="section" id="attribute-uses">
<span id="attributeuse"></span><h3>Attribute Uses<a class="headerlink" href="#attribute-uses" title="Permalink to this headline">¶</a></h3>
<p>The information associated with an <a class="reference external" href="http://www.w3.org/TR/xmlschema-1/#cAttributeUse">attribute use</a> is recorded in an
<a class="reference internal" href="pyxb.binding.html#pyxb.binding.content.AttributeUse" title="pyxb.binding.content.AttributeUse"><code class="xref py py-obj docutils literal"><span class="pre">pyxb.binding.content.AttributeUse</span></code></a> instance. This class provides:</p>
<ul class="simple">
<li>The <a class="reference internal" href="pyxb.binding.html#pyxb.binding.content.AttributeUse.name" title="pyxb.binding.content.AttributeUse.name"><code class="xref py py-obj docutils literal"><span class="pre">name</span></code></a> of the
attribute</li>
<li>The <a class="reference internal" href="pyxb.binding.html#pyxb.binding.content.AttributeUse.defaultValue" title="pyxb.binding.content.AttributeUse.defaultValue"><code class="xref py py-obj docutils literal"><span class="pre">default</span> <span class="pre">value</span></code></a> of
the attribute</li>
<li>Whether the attribute value is <a class="reference internal" href="pyxb.binding.html#pyxb.binding.content.AttributeUse.fixed" title="pyxb.binding.content.AttributeUse.fixed"><code class="xref py py-obj docutils literal"><span class="pre">fixed</span></code></a></li>
<li>Whether the <a class="reference external" href="http://www.w3.org/TR/xmlschema-1/#cAttributeUse">attribute use</a> is
<a class="reference internal" href="pyxb.binding.html#pyxb.binding.content.AttributeUse.required" title="pyxb.binding.content.AttributeUse.required"><code class="xref py py-obj docutils literal"><span class="pre">required</span></code></a>
or <a class="reference internal" href="pyxb.binding.html#pyxb.binding.content.AttributeUse.prohibited" title="pyxb.binding.content.AttributeUse.prohibited"><code class="xref py py-obj docutils literal"><span class="pre">prohibited</span></code></a></li>
<li>The <a class="reference internal" href="pyxb.binding.html#pyxb.binding.content.AttributeUse.dataType" title="pyxb.binding.content.AttributeUse.dataType"><code class="xref py py-obj docutils literal"><span class="pre">type</span></code></a> of the
attribute, as a subclass of <a class="reference internal" href="pyxb.binding.html#pyxb.binding.basis.simpleTypeDefinition" title="pyxb.binding.basis.simpleTypeDefinition"><code class="xref py py-obj docutils literal"><span class="pre">pyxb.binding.basis.simpleTypeDefinition</span></code></a></li>
<li>Methods to <a class="reference internal" href="pyxb.binding.html#pyxb.binding.content.AttributeUse.value" title="pyxb.binding.content.AttributeUse.value"><code class="xref py py-obj docutils literal"><span class="pre">read</span></code></a>, <a class="reference internal" href="pyxb.binding.html#pyxb.binding.content.AttributeUse.set" title="pyxb.binding.content.AttributeUse.set"><code class="xref py py-obj docutils literal"><span class="pre">set</span></code></a>, and <a class="reference internal" href="pyxb.binding.html#pyxb.binding.content.AttributeUse.reset" title="pyxb.binding.content.AttributeUse.reset"><code class="xref py py-obj docutils literal"><span class="pre">reset</span></code></a> the value of the attribute in a
given binding instance.</li>
</ul>
<p>A <code class="xref py py-obj docutils literal"><span class="pre">map</span></code> is used
to map from expanded names to AttributeUse instances. This map is defined
within the class definition itself.</p>
</div>
<div class="section" id="element-uses">
<span id="elementuse"></span><h3>Element Uses<a class="headerlink" href="#element-uses" title="Permalink to this headline">¶</a></h3>
<p>The element analog to an attribute use is an <a class="reference external" href="http://www.w3.org/TR/xmlschema-1/#cElement_Declarations">element declaration</a>, and the
corresponding information is stored in a
<a class="reference internal" href="pyxb.binding.html#pyxb.binding.content.ElementDeclaration" title="pyxb.binding.content.ElementDeclaration"><code class="xref py py-obj docutils literal"><span class="pre">pyxb.binding.content.ElementDeclaration</span></code></a> instance. This class provides:</p>
<ul class="simple">
<li>The <a class="reference internal" href="pyxb.binding.html#pyxb.binding.content.ElementDeclaration.elementBinding" title="pyxb.binding.content.ElementDeclaration.elementBinding"><code class="xref py py-obj docutils literal"><span class="pre">element</span> <span class="pre">binding</span></code></a>
that defines the properties of the referenced element, including its type</li>
<li>Whether the use allows <a class="reference internal" href="pyxb.binding.html#pyxb.binding.content.ElementDeclaration.isPlural" title="pyxb.binding.content.ElementDeclaration.isPlural"><code class="xref py py-obj docutils literal"><span class="pre">multiple</span> <span class="pre">occurrences</span></code></a></li>
<li>The <a class="reference internal" href="pyxb.binding.html#pyxb.binding.content.ElementDeclaration.defaultValue" title="pyxb.binding.content.ElementDeclaration.defaultValue"><code class="xref py py-obj docutils literal"><span class="pre">default</span> <span class="pre">value</span></code></a> of
the element. Currently this is either C{None} or an empty list, depending
on <a class="reference internal" href="pyxb.binding.html#pyxb.binding.content.ElementDeclaration.isPlural" title="pyxb.binding.content.ElementDeclaration.isPlural"><code class="xref py py-obj docutils literal"><span class="pre">pyxb.binding.content.ElementDeclaration.isPlural</span></code></a></li>
<li>Methods to <a class="reference internal" href="pyxb.binding.html#pyxb.binding.content.ElementDeclaration.value" title="pyxb.binding.content.ElementDeclaration.value"><code class="xref py py-obj docutils literal"><span class="pre">read</span></code></a>, <a class="reference internal" href="pyxb.binding.html#pyxb.binding.content.ElementDeclaration.set" title="pyxb.binding.content.ElementDeclaration.set"><code class="xref py py-obj docutils literal"><span class="pre">set</span></code></a>, <a class="reference internal" href="pyxb.binding.html#pyxb.binding.content.ElementDeclaration.append" title="pyxb.binding.content.ElementDeclaration.append"><code class="xref py py-obj docutils literal"><span class="pre">append</span> <span class="pre">to</span></code></a> (only for plural elements), and
<a class="reference internal" href="pyxb.binding.html#pyxb.binding.content.ElementDeclaration.reset" title="pyxb.binding.content.ElementDeclaration.reset"><code class="xref py py-obj docutils literal"><span class="pre">reset</span></code></a> the value of the
element in a given binding instance</li>
<li>The <a class="reference internal" href="pyxb.binding.html#pyxb.binding.content.ElementDeclaration.setOrAppend" title="pyxb.binding.content.ElementDeclaration.setOrAppend"><code class="xref py py-obj docutils literal"><span class="pre">setOrAppend</span></code></a> method,
which is most commonly used to provide new content to a value</li>
</ul>
<p>A <a class="reference internal" href="pyxb.binding.html#pyxb.binding.basis.complexTypeDefinition._ElementMap" title="pyxb.binding.basis.complexTypeDefinition._ElementMap"><code class="xref py py-obj docutils literal"><span class="pre">map</span></code></a> is used to
map from expanded names to ElementDeclaration instances. This map is defined
within the class definition itself. As mentioned before, when the same
element name appears at multiple places within the element content the uses
are collapsed into a single attribute on the complex type; thus the map is to
the <a class="reference internal" href="pyxb.binding.html#pyxb.binding.content.ElementDeclaration" title="pyxb.binding.content.ElementDeclaration"><code class="xref py py-obj docutils literal"><span class="pre">ElementDeclaration</span></code></a>, not
the <a class="reference internal" href="pyxb.binding.html#pyxb.binding.content.ElementUse" title="pyxb.binding.content.ElementUse"><code class="xref py py-obj docutils literal"><span class="pre">ElementUse</span></code></a>.</p>
</div>
</div>
<div class="section" id="validating-the-content-model">
<span id="validating-content"></span><h2>Validating the Content Model<a class="headerlink" href="#validating-the-content-model" title="Permalink to this headline">¶</a></h2>
<p>As of <a class="reference internal" href="releases.html#pyxb-1-2-0"><span class="std std-ref">PyXB 1.2.0</span></a>, content validation is performed using
the <strong>Finite Automata with Counters (FAC)</strong> data structure, as described in
<a class="reference external" href="http://bora.uib.no/handle/1956/3628">Regular Expressions with Numerical Constraints and Automata with Counters</a>, <a class="reference external" href="http://www.ii.uib.no/~dagh/">Dag Hovland</a>, Lecture Notes in Computer Science, 2009,
Volume 5684, Theoretical Aspects of Computing - ICTAC 2009, Pages 231-245.</p>
<p>This structure allows accurate validation of occurrence and order constraints
without the complexity of the original back-tracking validation solution from
<a class="reference internal" href="releases.html#pyxb-1-1-1"><span class="std std-ref">PyXB 1.1.1</span></a> and earlier. It also avoids the
<a class="reference external" href="https://sourceforge.net/p/pyxb/tickets/112/">incorrect rejection of valid documents</a> that (rarely) occurred
with the greedy algorithm introduced in <a class="reference internal" href="releases.html#pyxb-1-1-2"><span class="std std-ref">PyXB 1.1.2</span></a>.
Conversion to this data structure also enabled the distinction between
<a class="reference internal" href="pyxb.binding.html#pyxb.binding.content.ElementDeclaration" title="pyxb.binding.content.ElementDeclaration"><code class="xref py py-obj docutils literal"><span class="pre">element</span> <span class="pre">declaration</span></code></a> and
<a class="reference internal" href="pyxb.binding.html#pyxb.binding.content.ElementUse" title="pyxb.binding.content.ElementUse"><code class="xref py py-obj docutils literal"><span class="pre">element</span> <span class="pre">use</span></code></a> nodes, allowing
diagnostics to trace back to the element references in context.</p>
<p>The data structures for the automaton and the configuration structure
that represents a processing automaton are:</p>
<img alt="_images/FACAutomaton.jpg" src="_images/FACAutomaton.jpg" />
<p>The implementation in PyXB is generally follows the description in the ICTAC
2009 paper. Calculation of first/follow sets has been enhanced to support
term trees with more than two children per node. In addition, support for
unordered catenation as required for the <a class="reference external" href="http://www.w3.org/TR/xmlschema-1/#element-all">“all” model group</a> is implemented by a state
that maintains a distinct sub-automaton for each alternative, requiring a
layered approach where executon of an automaton is suspended until the
subordinate automaton has accepted and a transition out of it is encountered.</p>
<p>For more information on the implementation, please see the <a class="reference internal" href="pyxb.utils.html#module-pyxb.utils.fac" title="pyxb.utils.fac"><code class="xref py py-obj docutils literal"><span class="pre">FAC</span> <span class="pre">module</span></code></a>. This module has been written to be independent of PyXB
infrastructure, and may be re-used in other code in accordance with the
<a class="reference internal" href="legal.html#pyxb-license"><span class="std std-ref">PyXB license</span></a>.</p>
<div class="section" id="fac-and-the-pyxb-content-model">
<h3>FAC and the PyXB Content Model<a class="headerlink" href="#fac-and-the-pyxb-content-model" title="Permalink to this headline">¶</a></h3>
<p>As depicted in the <a class="reference internal" href="#cd-contentmodel"><span class="std std-ref">Content Model class diagram</span></a> each
complex type binding class has a <a class="reference internal" href="pyxb.utils.html#pyxb.utils.fac.Automaton" title="pyxb.utils.fac.Automaton"><code class="xref py py-obj docutils literal"><span class="pre">_Automaton</span></code></a>
which encodes the content model of the type as a Finite Automaton with
Counters. This representation models the occurrence constraints and
sub-element orders, referencing the specific element and wildcard uses as they
appear in the schema. Each instance of a complex binding supports an
<a class="reference internal" href="pyxb.binding.html#pyxb.binding.content.AutomatonConfiguration" title="pyxb.binding.content.AutomatonConfiguration"><code class="xref py py-obj docutils literal"><span class="pre">AutomatonConfiguration</span></code></a>
that is used to validate the binding content against the model.</p>
<p>An <a class="reference internal" href="pyxb.binding.html#pyxb.binding.content.ElementUse" title="pyxb.binding.content.ElementUse"><code class="xref py py-obj docutils literal"><span class="pre">ElementUse</span></code></a> instance is provided as
the metadata for automaton states that correspond an element declaration in the
schema. Similarly, a <a class="reference internal" href="pyxb.binding.html#pyxb.binding.content.WildcardUse" title="pyxb.binding.content.WildcardUse"><code class="xref py py-obj docutils literal"><span class="pre">WildcardUse</span></code></a>
instance is used as the metadata for automaton states that correspond to an
instance of the <a class="reference external" href="http://www.w3.org/TR/xmlschema-1/#Wildcards">xs:any</a>
wildcard schema component. Validation in the automaton delegates through the
<a class="reference internal" href="pyxb.utils.html#pyxb.utils.fac.SymbolMatch_mixin" title="pyxb.utils.fac.SymbolMatch_mixin"><code class="xref py py-obj docutils literal"><span class="pre">SymbolMatch_mixin</span></code></a> interface to see
whether content in the form of a complex type binding instance is conformant
to the restrictions on symbols associated with a particular state.</p>
<p>When parsing, a transition taken results in the storage of the consumed symbol
into the appropriate element attribute or wildcard list in the binding
instance. In many cases, the transition from one state to a next is uniquely
determined by the content; as long as this condition holds, the
<a class="reference internal" href="pyxb.binding.html#pyxb.binding.content.AutomatonConfiguration" title="pyxb.binding.content.AutomatonConfiguration"><code class="xref py py-obj docutils literal"><span class="pre">AutomatonConfiguration</span></code></a>
instance retains a single underlying <a class="reference internal" href="pyxb.utils.html#pyxb.utils.fac.Configuration" title="pyxb.utils.fac.Configuration"><code class="xref py py-obj docutils literal"><span class="pre">FAC</span> <span class="pre">Configuration</span></code></a> representing the current state.</p>
<p>To generate the XML corresponding to a binding instance, the element and
wildcard content of the instance are loaded into a Python dictionary, keyed by
the <a class="reference internal" href="pyxb.binding.html#pyxb.binding.content.ElementDeclaration" title="pyxb.binding.content.ElementDeclaration"><code class="xref py py-obj docutils literal"><span class="pre">ElementDeclaration</span></code></a>.
These subordinate elements are appended to a list of child nodes as
transitions that recognize them are encountered. As of <a class="reference internal" href="releases.html#pyxb-1-2-0"><span class="std std-ref">PyXB 1.2.0</span></a> the first legal transition in the order imposed by the schema is
taken, and there is no provision for influencing the order in the generated
document when multiple orderings are valid.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Content Model</a><ul>
<li><a class="reference internal" href="#associating-xml-and-python-objects">Associating XML and Python Objects</a><ul>
<li><a class="reference internal" href="#attribute-uses">Attribute Uses</a></li>
<li><a class="reference internal" href="#element-uses">Element Uses</a></li>
</ul>
</li>
<li><a class="reference internal" href="#validating-the-content-model">Validating the Content Model</a><ul>
<li><a class="reference internal" href="#fac-and-the-pyxb-content-model">FAC and the PyXB Content Model</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="arch_binding.html"
title="previous chapter">Binding Model</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="userref_index.html"
title="next chapter">User Reference</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/arch_content.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<div><input type="text" name="q" /></div>
<div><input type="submit" value="Go" /></div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</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"
>index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="userref_index.html" title="User Reference"
>next</a> |</li>
<li class="right" >
<a href="arch_binding.html" title="Binding Model"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">PyXB 1.2.6 documentation</a> »</li>
<li class="nav-item nav-item-1"><a href="architecture.html" >Architecture</a> »</li>
<li style="margin-left: 20px">PyXB hosted on <a href="http://sourceforge.net/projects/pyxb"><img src="http://sflogo.sourceforge.net/sflogo.php?group_id=263147&type=9"
width="80" height="15" alt="Get PyXB: Python XML Schema Bindings at SourceForge.net. Fast, secure and Free Open Source software downloads"/></a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2009-2017, Peter A. Bigot.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.5.
</div>
</body>
</html>
