<!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 v1.1.2 documentation</title>
<link rel="stylesheet" href="_static/default.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.1.2',
COLLAPSE_MODINDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="top" title="PyXB v1.1.2 documentation" href="index.html" />
<link rel="up" title="Architecture" href="architecture.html" />
<link rel="next" title="User Reference" href="userref_index.html" />
<link rel="prev" title="Binding Model" href="arch_binding.html" />
</head>
<body>
<div class="related">
<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="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><a href="index.html">PyXB v1.1.2 documentation</a> »</li>
<li><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">
<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 external" href="arch_component.html#componentmodel"><em>Component Model</em></a> and the <a class="reference external" href="arch_binding.html#bindingmodel"><em>Binding Model</em></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>
<p>The classes involved in the content model are in the
<a class="reference external" href="api/pyxb.binding.content-module.html">pyxb.binding.content</a> module, and their relationships are displayed in
the following diagram.</p>
<img alt="_images/ContentModel.jpg" src="_images/ContentModel.jpg" />
<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>In the standard code generation template, both element and attribute values
are stored in Python class fields. As noted in
<a class="reference external" href="arch_binding.html#binding-deconflictingnames"><em>Deconflicting Names</em></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 external" href="api/pyxb.binding.content.AttributeUse-class.html#name">name</a> of the element/attribute in the XML</li>
<li>its <a class="reference external" href="api/pyxb.binding.content.AttributeUse-class.html#id">deconflicted name</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 external" href="api/pyxb.binding.basis.complexTypeDefinition-class.html">complexTypeDefinition</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 external" href="api/pyxb.binding.content.AttributeUse-class.html">AttributeUse</a> instance. This class provides:</p>
<ul class="simple">
<li>The <a class="reference external" href="api/pyxb.binding.content.AttributeUse-class.html#dataType">type</a> of the
attribute, as a subclass of <a class="reference external" href="api/pyxb.binding.basis.simpleTypeDefinition-class.html">simpleTypeDefinition</a></li>
<li>The <a class="reference external" href="api/pyxb.binding.content.AttributeUse-class.html#defaultValue">default value</a> of
the attribute</li>
<li>Whether the <a class="reference external" href="http://www.w3.org/TR/xmlschema-1/#cAttributeUse">attribute use</a> is
<a class="reference external" href="api/pyxb.binding.content.AttributeUse-class.html#required">required</a>
or <a class="reference external" href="api/pyxb.binding.content.AttributeUse-class.html#prohibited">prohibited</a></li>
<li>Whether the value of the attribute in a binding instance was <a class="reference external" href="api/pyxb.binding.content.AttributeUse-class.html#provided">provided</a> by an external source or set
to the default value</li>
<li>Whether the attribute value is <a class="reference external" href="api/pyxb.binding.content.AttributeUse-class.html#fixed">fixed</a></li>
<li>Methods to <a class="reference external" href="api/pyxb.binding.content.AttributeUse-class.html#value">read</a>, <a class="reference external" href="api/pyxb.binding.content.AttributeUse-class.html#set">set</a>, and <a class="reference external" href="api/pyxb.binding.content.AttributeUse-class.html#reset">reset</a> the value of the attribute in a
given binding instance.</li>
</ul>
<p>A <a class="reference external" href="api/pyxb.binding.basis.complexTypeDefinition-class.html#_AttributeMap">map</a> 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 external" href="api/pyxb.binding.content.ElementUse-class.html">ElementUse</a> instance. This class provides:</p>
<ul class="simple">
<li>The <a class="reference external" href="api/pyxb.binding.content.ElementUse-class.html#elementBinding">element binding</a>
that defines the properties of the referenced element, including its type</li>
<li>Whether the use allows <a class="reference external" href="api/pyxb.binding.content.ElementUse-class.html#isPlural">multiple occurrences</a></li>
<li>The <a class="reference external" href="api/pyxb.binding.content.ElementUse-class.html#defaultValue">default value</a> of
the element. Currently this is either C{None} or an empty list, depending
on <a class="reference external" href="api/pyxb.binding.content.ElementUse-class.html#isPlural">ElementUse.isPlural</a></li>
<li>Methods to <a class="reference external" href="api/pyxb.binding.content.ElementUse-class.html#value">read</a>, <a class="reference external" href="api/pyxb.binding.content.ElementUse-class.html#set">set</a>, <a class="reference external" href="api/pyxb.binding.content.ElementUse-class.html#append">append to</a> (only for plural elements), and
<a class="reference external" href="api/pyxb.binding.content.ElementUse-class.html#reset">reset</a> the value of the
element in a given binding instance</li>
<li>The <a class="reference external" href="api/pyxb.binding.content.ElementUse-class.html#setOrAppend">setOrAppend</a> method,
which is most commonly used to provide new content to a value</li>
</ul>
<p>A <a class="reference external" href="api/pyxb.binding.basis.complexTypeDefinition-class.html#_ElementMap">map</a> is used to
map from expanded names to ElementUse instances. This map is defined within
the class definition itself.</p>
</div>
</div>
<div class="section" id="content-model-automata">
<h2>Content Model Automata<a class="headerlink" href="#content-model-automata" title="Permalink to this headline">¶</a></h2>
<p>The XML <a class="reference external" href="http://www.w3.org/TR/xmlschema-1/#Model_Groups">model group</a>
construct permits a nested specification of legal type instances through
ordered sequences (<tt class="docutils literal"><span class="pre">sequence</span></tt>), conjunctions or unordered sequences
(<tt class="docutils literal"><span class="pre">all</span></tt>), choices (<tt class="docutils literal"><span class="pre">choice</span></tt>), and wildcards (<tt class="docutils literal"><span class="pre">any</span></tt>). The model group can
be considered a form of regular expression, and as such we use <a class="reference external" href="http://portal.acm.org/citation.cfm?doid=363387">Thompson’s
algorithm</a> to construct a
non-deterministic finite automaton which recognizes the set of conforming
documents. A <a class="reference external" href="http://en.wikipedia.org/wiki/Powerset_construction">powerset construction</a> is then used to make
the automaton deterministic, and the resulting automaton is stored as a
<a class="reference external" href="api/pyxb.binding.content-module.html#ContentModel">ContentModel</a> instance, with a set of <a class="reference external" href="api/pyxb.binding.content-module.html#ContentModelState">states</a> each of which has <a class="reference external" href="api/pyxb.binding.content-module.html#ContentModelTransition">transitions</a> on elements, wildcards, and
model groups with an <tt class="docutils literal"><span class="pre">all</span></tt> compositor.</p>
<p>The sole complication in the automaton construction is dealing with <tt class="docutils literal"><span class="pre">all</span></tt>
model groups, which accept subsets of a set of nodes in any order. This
construct produces an exponential increase in the size of the deterministic
finite automaton, so is left as a single <a class="reference external" href="api/pyxb.binding.content-module.html#ModelGroupAll">transition</a> which iteratively matches against the
candidate value until an alternative is found.</p>
<div class="section" id="parsing-with-automata">
<span id="arch-content-automata-parsing"></span><h3>Parsing With Automata<a class="headerlink" href="#parsing-with-automata" title="Permalink to this headline">¶</a></h3>
<p>Automata-based parsing is used for building up a binding instance from a
series of values.</p>
<p>To allow incremental construction of instances, as required by the <a class="reference external" href="api/pyxb.binding.saxer.PyXBSAXHandler-class.html">SAX
interface</a> or initialization by constructor
arguments, each complex type with a content model contains a <a class="reference external" href="api/pyxb.binding.content-module.html#DFAStack">DFA stack</a>. Each level of the stack contains an instance
of <a class="reference external" href="api/pyxb.binding.content-module.html#_DFAState">DFA state</a>. Normally the state
specifies the content model and automaton state within that model that
represents the instance’s position in a path through the automata, where the
path so far comprises the member elements added to the instance.</p>
<p>The need for a stack of states comes when automaton execution reaches a
transition that involves an <a class="reference external" href="api/pyxb.binding.content-module.html#ModelGroupAll">“all” model group</a>. Evaluation of such a transition
requires suspending the parent automaton execution and continuing with the
evaluation of the automata that represent alternatives in the model group.</p>
</div>
<div class="section" id="generation-with-automata">
<h3>Generation With Automata<a class="headerlink" href="#generation-with-automata" title="Permalink to this headline">¶</a></h3>
<p>Automaton evaluation is also used to validate that the content of a binding
instance is consistent with type’s content model, and to determine a sequence
of contained elements that define a valid path through the automaton. This
technique is used to create a valid DOM document from a binding instance.</p>
<p>A memoization technique is used, where the state of the system is represented
by a set of element uses (which identify valid consuming transitions), with a
sequence of values for each such use. The element uses are symbols in the
alphabet of the automaton; the values are a token that permits a transition on
that symbol. The state of the system also incorporates a sequence of
symbol-value pairs that record the path up to the current position.</p>
<p>The automaton starts in the initial state, then each transition is examined
until one is found for which there is a value available. The state resulting
from executing that transition is pushed onto a stack, and the remaining
transitions are examined as well. If no transition can proceed, the state is
discarded and the top state from the stack is evaluated.</p>
<p>When no more symbols remain, if the current state is a final state, the
validation succeeds, and the corresponding sequence is returned as a valid
path. If a final state cannot be reached, the validation fails.</p>
<p>See the <tt class="docutils literal"><span class="pre">pyxb.binding.content.ContentModel.validate</span></tt>
for details on how all this really works.</p>
</div>
</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 external" href="#">Content Model</a><ul>
<li><a class="reference external" href="#associating-xml-and-python-objects">Associating XML and Python Objects</a><ul>
<li><a class="reference external" href="#attribute-uses">Attribute Uses</a></li>
<li><a class="reference external" href="#element-uses">Element Uses</a></li>
</ul>
</li>
<li><a class="reference external" href="#content-model-automata">Content Model Automata</a><ul>
<li><a class="reference external" href="#parsing-with-automata">Parsing With Automata</a></li>
<li><a class="reference external" href="#generation-with-automata">Generation With Automata</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>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/arch_content.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">
<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="userref_index.html" title="User Reference"
>next</a> |</li>
<li class="right" >
<a href="arch_binding.html" title="Binding Model"
>previous</a> |</li>
<li><a href="index.html">PyXB v1.1.2 documentation</a> »</li>
<li><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">
© Copyright 2009, Peter A. Bigot.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.5.
</div>
</body>
</html>
