<!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>Generating Binding Classes — 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="Using Binding Classes" href="userref_usebind.html" />
<link rel="prev" title="User Reference" href="userref_index.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_usebind.html" title="Using Binding Classes"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="userref_index.html" title="User Reference"
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="userref_index.html" accesskey="U">User Reference</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="generating-binding-classes">
<span id="pyxbgen"></span><h1>Generating Binding Classes<a class="headerlink" href="#generating-binding-classes" title="Permalink to this headline">¶</a></h1>
<p>The following sections reference example schema and programs that are
available in the <code class="docutils literal"><span class="pre">examples/manual</span></code> subdirectory of the PyXB
distribution.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>PyXB is developed and tested assuming a POSIX file system, as is used
on Linux. While PyXB works perfectly well on Windows, some
accommodation is required. In particular, when providing file URIs
as command-line arguments to <code class="docutils literal"><span class="pre">pyxbgen</span></code> it may be necessary to
explicitly note that the parameter is a URI by using the <a class="reference external" href="http://blogs.msdn.com/b/ie/archive/2006/12/06/file-uris-in-windows.aspx">Windows
file URI form</a>
of the file path.</p>
<p>For example, something like this will generally not work:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">pyxbgen</span> <span class="o">-</span><span class="n">m</span> <span class="n">x</span> <span class="o">-</span><span class="n">u</span> <span class="s2">"c:</span><span class="se">\\</span><span class="s2">Windows\My Documents\x.xsd"</span> <span class="c1"># DO NOT USE</span>
</pre></div>
</div>
<p>This should be expressed as:</p>
<div class="last highlight-default"><div class="highlight"><pre><span></span><span class="n">pyxbgen</span> <span class="o">-</span><span class="n">m</span> <span class="n">x</span> <span class="o">-</span><span class="n">u</span> <span class="n">file</span><span class="p">:</span><span class="o">//</span><span class="n">c</span><span class="p">:</span><span class="o">/</span><span class="n">Windows</span><span class="o">/</span><span class="n">My</span><span class="o">%</span><span class="mi">20</span><span class="n">Documents</span><span class="o">/</span><span class="n">x</span><span class="o">.</span><span class="n">xsd</span>
</pre></div>
</div>
</div>
<div class="section" id="self-contained-schema">
<h2>Self-contained schema<a class="headerlink" href="#self-contained-schema" title="Permalink to this headline">¶</a></h2>
<p>The following schema <code class="docutils literal"><span class="pre">po1.xsd</span></code> is a condensed version of the <a class="reference external" href="http://www.w3.org/TR/xmlschema-0/#POSchema">purchase
order schema</a> in the XMLSchema
Primer:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:element name="purchaseOrder" type="PurchaseOrderType"/>
<xsd:element name="comment" type="xsd:string"/>
<xsd:complexType name="PurchaseOrderType">
<xsd:sequence>
<xsd:element name="shipTo" type="USAddress"/>
<xsd:element name="billTo" type="USAddress"/>
<xsd:element ref="comment" minOccurs="0"/>
<xsd:element name="items" type="Items"/>
</xsd:sequence>
<xsd:attribute name="orderDate" type="xsd:date"/>
</xsd:complexType>
<xsd:complexType name="USAddress">
<xsd:sequence>
<xsd:element name="name" type="xsd:string"/>
<xsd:element name="street" type="xsd:string"/>
<xsd:element name="city" type="xsd:string"/>
<xsd:element name="state" type="xsd:string"/>
<xsd:element name="zip" type="xsd:decimal"/>
</xsd:sequence>
<xsd:attribute name="country" type="xsd:NMTOKEN" fixed="US"/>
</xsd:complexType>
<xsd:complexType name="Items">
<xsd:sequence>
<xsd:element name="item" minOccurs="0" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="productName" type="xsd:string"/>
<xsd:element name="quantity">
<xsd:simpleType>
<xsd:restriction base="xsd:positiveInteger">
<xsd:maxExclusive value="100"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
<xsd:element name="USPrice" type="xsd:decimal"/>
<xsd:element ref="comment" minOccurs="0"/>
<xsd:element name="shipDate" type="xsd:date" minOccurs="0"/>
</xsd:sequence>
<xsd:attribute name="partNum" type="SKU" use="required"/>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
<!-- Stock Keeping Unit, a code for identifying products -->
<xsd:simpleType name="SKU">
<xsd:restriction base="xsd:string">
<xsd:pattern value="\d{3}-[A-Z]{2}"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:schema>
</pre></div>
</div>
<p>Translate this into Python with the following command:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">pyxbgen</span> \
<span class="o">-</span><span class="n">u</span> <span class="n">po1</span><span class="o">.</span><span class="n">xsd</span> <span class="o">-</span><span class="n">m</span> <span class="n">po1</span>
</pre></div>
</div>
<p>The <a class="reference internal" href="pyxbgen_cli.html#pyxbgen-schema-location"><span class="std std-ref">-u</span></a> parameter identifies a schema
document describing contents of a namespace. The parameter may be a path to
a file on the local system, or a URL to a network-accessible location like
<a class="reference external" href="http://www.weather.gov/forecasts/xml/DWMLgen/schema/DWML.xsd">http://www.weather.gov/forecasts/xml/DWMLgen/schema/DWML.xsd</a>. The
<a class="reference internal" href="pyxbgen_cli.html#pyxbgen-module"><span class="std std-ref">-m</span></a> parameter specifies the name to be used by the
Python module holding the bindings generated for the namespace in the
preceding schema. After running this, the Python bindings will be in a
file named <code class="docutils literal"><span class="pre">po1.py</span></code>.</p>
<p>With the bindings available, this program (<code class="docutils literal"><span class="pre">demo1.py</span></code>):</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">__future__</span> <span class="k">import</span> <span class="n">print_function</span>
<span class="kn">import</span> <span class="nn">po1</span>
<span class="n">xml</span> <span class="o">=</span> <span class="nb">open</span><span class="p">(</span><span class="s1">'po1.xml'</span><span class="p">)</span><span class="o">.</span><span class="n">read</span><span class="p">()</span>
<span class="n">order</span> <span class="o">=</span> <span class="n">po1</span><span class="o">.</span><span class="n">CreateFromDocument</span><span class="p">(</span><span class="n">xml</span><span class="p">)</span>
<span class="nb">print</span><span class="p">(</span><span class="s1">'</span><span class="si">%s</span><span class="s1"> is sending </span><span class="si">%s</span><span class="s1"> </span><span class="si">%d</span><span class="s1"> thing(s):'</span> <span class="o">%</span> <span class="p">(</span><span class="n">order</span><span class="o">.</span><span class="n">billTo</span><span class="o">.</span><span class="n">name</span><span class="p">,</span> <span class="n">order</span><span class="o">.</span><span class="n">shipTo</span><span class="o">.</span><span class="n">name</span><span class="p">,</span> <span class="nb">len</span><span class="p">(</span><span class="n">order</span><span class="o">.</span><span class="n">items</span><span class="o">.</span><span class="n">item</span><span class="p">)))</span>
<span class="k">for</span> <span class="n">item</span> <span class="ow">in</span> <span class="n">order</span><span class="o">.</span><span class="n">items</span><span class="o">.</span><span class="n">item</span><span class="p">:</span>
<span class="nb">print</span><span class="p">(</span><span class="s1">' Quantity </span><span class="si">%d</span><span class="s1"> of </span><span class="si">%s</span><span class="s1"> at $</span><span class="si">%s</span><span class="s1">'</span> <span class="o">%</span> <span class="p">(</span><span class="n">item</span><span class="o">.</span><span class="n">quantity</span><span class="p">,</span> <span class="n">item</span><span class="o">.</span><span class="n">productName</span><span class="p">,</span> <span class="n">item</span><span class="o">.</span><span class="n">USPrice</span><span class="p">))</span>
</pre></div>
</div>
<p>processing this document:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><?xml version="1.0"?>
<purchaseOrder orderDate="1999-10-20">
<shipTo country="US">
<name>Alice Smith</name>
<street>123 Maple Street</street>
<city>Anytown</city><state>AK</state><zip>12341</zip>
</shipTo>
<billTo country="US">
<name>Robert Smith</name>
<street>8 Oak Avenue</street>
<city>Anytown</city><state>AK</state><zip>12341</zip>
</billTo>
<items>
<item partNum="833-AA">
<productName>Lapis necklace</productName>
<quantity>1</quantity>
<USPrice>99.95</USPrice>
<comment>Want this for the holidays!</comment>
<shipDate>1999-12-05</shipDate>
</item>
<item partNum="833-AB">
<productName>Plastic necklace</productName>
<quantity>4</quantity>
<USPrice>3.95</USPrice>
<shipDate>1999-12-24</shipDate>
</item>
</items>
</purchaseOrder>
</pre></div>
</div>
<p>produces the following output:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>Robert Smith is sending Alice Smith 2 thing(s):
Quantity 1 of Lapis necklace at $99.95
Quantity 4 of Plastic necklace at $3.95
</pre></div>
</div>
</div>
<div class="section" id="multi-document-schema">
<h2>Multi-document schema<a class="headerlink" href="#multi-document-schema" title="Permalink to this headline">¶</a></h2>
<p>Complex schema are more easy to manage when they are separated into multiple
documents, each of which contains a cohesive set of types. In the example
above, the <code class="docutils literal"><span class="pre">USAddress</span></code> type can be abstracted to handle a variety of
addresses, and maintained as its own document <code class="docutils literal"><span class="pre">address.xsd</span></code>:</p>
<div class="highlight-default" id="address-xsd"><div class="highlight"><pre><span></span><xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:complexType name="Address">
<xsd:sequence>
<xsd:element name="name" type="xsd:string"/>
<xsd:element name="street" type="xsd:string"/>
<xsd:element name="city" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="USAddress">
<xsd:complexContent>
<xsd:extension base="Address">
<xsd:sequence>
<xsd:element name="state" type="USState"/>
<xsd:element name="zip" type="xsd:positiveInteger"/>
</xsd:sequence>
<xsd:attribute name="country" type="xsd:NMTOKEN" fixed="US"/>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:complexType name="UKAddress">
<xsd:complexContent>
<xsd:extension base="Address">
<xsd:sequence>
<xsd:element name="postcode" type="UKPostcode"/>
</xsd:sequence>
<attribute name="exportCode" type="xsd:positiveInteger" fixed="1"/>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<!-- other Address derivations for more countries -->
<xsd:simpleType name="USState">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="AK"/>
<xsd:enumeration value="AL"/>
<xsd:enumeration value="AR"/>
<xsd:enumeration value="AZ"/>
<!-- and so on ... -->
</xsd:restriction>
</xsd:simpleType>
<!-- simple type definition for UKPostcode -->
<!-- *** pyxb mod: provide missing STD *** -->
<xsd:simpleType name="UKPostcode">
<xsd:restriction base="xsd:string">
<xsd:pattern value="[A-Z]{2}\d\s\d[A-Z]{2}"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:schema>
</pre></div>
</div>
<p>The XMLSchema <a class="reference external" href="http://www.w3.org/TR/xmlschema-1/#compound-schema">include directive</a> can be used to
incorporate this document into <code class="docutils literal"><span class="pre">po2.xsd</span></code>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:include schemaLocation="file:address.xsd"/>
<xsd:element name="purchaseOrder" type="PurchaseOrderType"/>
<xsd:element name="comment" type="xsd:string"/>
<xsd:complexType name="PurchaseOrderType">
<xsd:sequence>
<xsd:element name="shipTo" type="USAddress"/>
<xsd:element name="billTo" type="USAddress"/>
<xsd:element ref="comment" minOccurs="0"/>
<xsd:element name="items" type="Items"/>
</xsd:sequence>
<xsd:attribute name="orderDate" type="xsd:date"/>
</xsd:complexType>
<xsd:complexType name="Items">
<xsd:sequence>
<xsd:element name="item" minOccurs="0" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="productName" type="xsd:string"/>
<xsd:element name="quantity">
<xsd:simpleType>
<xsd:restriction base="xsd:positiveInteger">
<xsd:maxExclusive value="100"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
<xsd:element name="USPrice" type="xsd:decimal"/>
<xsd:element ref="comment" minOccurs="0"/>
<xsd:element name="shipDate" type="xsd:date" minOccurs="0"/>
</xsd:sequence>
<xsd:attribute name="partNum" type="SKU" use="required"/>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
<!-- Stock Keeping Unit, a code for identifying products -->
<xsd:simpleType name="SKU">
<xsd:restriction base="xsd:string">
<xsd:pattern value="\d{3}-[A-Z]{2}"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:schema>
</pre></div>
</div>
<p>Translation of this document and execution of the test program is just as it
was in the previous section:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">pyxbgen</span> \
<span class="o">-</span><span class="n">u</span> <span class="n">po2</span><span class="o">.</span><span class="n">xsd</span> <span class="o">-</span><span class="n">m</span> <span class="n">po2</span>
</pre></div>
</div>
<p>Note that you do not need to explicitly list the <code class="docutils literal"><span class="pre">address.xsd</span></code> file. PyXB
detects the <code class="docutils literal"><span class="pre">include</span></code> directive and reads the second schema by resolving
its <code class="docutils literal"><span class="pre">schemaLocation</span></code> relative to the base URI of the containing document.
Because the contents of the two schema files belong to the same namespace,
their combined bindings are placed into the <code class="docutils literal"><span class="pre">po2.py</span></code> module.</p>
</div>
<div class="section" id="working-with-namespaces">
<h2>Working with Namespaces<a class="headerlink" href="#working-with-namespaces" title="Permalink to this headline">¶</a></h2>
<p>Documents of significant complexity are likely to require references to
multiple namespaces. Notice that the schemas we’ve looked at so far have
<a class="reference internal" href="arch_namespaces.html#absentnamespaces"><span class="std std-ref">no namespace</span></a> for both their target and default
namespaces. The following schema <code class="docutils literal"><span class="pre">nsaddress.xsd</span></code> places the types that
are in <a class="reference internal" href="#address-xsd"><span class="std std-ref">address.xsd</span></a> into the namespace <code class="docutils literal"><span class="pre">URN:address</span></code>
by defining a <a class="reference external" href="http://www/Documentation/W3C/www.w3.org/TR/xmlschema-0/index.html#QualLocals">target namespace</a>
then including the namespace-less schema:</p>
<div class="highlight-default" id="nsaddress-xsd"><div class="highlight"><pre><span></span><span class="o"><</span><span class="n">xsd</span><span class="p">:</span><span class="n">schema</span>
<span class="n">targetNamespace</span><span class="o">=</span><span class="s2">"URN:address"</span>
<span class="n">xmlns</span><span class="p">:</span><span class="n">xsd</span><span class="o">=</span><span class="s2">"http://www.w3.org/2001/XMLSchema"</span><span class="o">></span>
<span class="o"><</span><span class="n">xsd</span><span class="p">:</span><span class="n">include</span> <span class="n">schemaLocation</span><span class="o">=</span><span class="s2">"address.xsd"</span><span class="o">/></span>
<span class="o"></</span><span class="n">xsd</span><span class="p">:</span><span class="n">schema</span><span class="o">></span>
</pre></div>
</div>
<p>Note that this technique takes advantage of the <a class="reference external" href="http://www.xfront.com/ZeroOneOrManyNamespaces.html#mixed">chameleon schema</a> pattern.</p>
<p>There are several ways you can prepare to process documents with multiple
namespaces. If you have no expectation of using the imported namespace
directly, you can process the importing schema just as before:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">pyxbgen</span> \
<span class="o">-</span><span class="n">u</span> <span class="n">po3</span><span class="o">.</span><span class="n">xsd</span> <span class="o">-</span><span class="n">m</span> <span class="n">po3</span>
</pre></div>
</div>
<p>PyXB will detect the <code class="docutils literal"><span class="pre">import</span></code> statement, read the corresponding schema,
and create bindings for its types. However, since the <code class="docutils literal"><span class="pre">pyxbgen</span></code>
invocation did not mention the <code class="docutils literal"><span class="pre">URN:address</span></code> namespace, the bindings are
written into a <a class="reference internal" href="pyxbgen_cli.html#pyxbgen-private-namespace"><span class="std std-ref">private</span></a> binding file.
The generated module file <code class="docutils literal"><span class="pre">_address.py</span></code> is created with a prefixed
underscore indicating that it is not expected to be referenced directly.
The public module <code class="docutils literal"><span class="pre">po3.py</span></code> will locally import module <code class="docutils literal"><span class="pre">_address</span></code> so that
the required classes are available, but will not expose them to code that
imports only module <code class="docutils literal"><span class="pre">po3</span></code>. The demonstration program <code class="docutils literal"><span class="pre">demo3.py</span></code> shows
that things work as expected without the new namespace being made explicit.</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">__future__</span> <span class="k">import</span> <span class="n">print_function</span>
<span class="kn">import</span> <span class="nn">po3</span>
<span class="n">order</span> <span class="o">=</span> <span class="n">po3</span><span class="o">.</span><span class="n">CreateFromDocument</span><span class="p">(</span><span class="nb">open</span><span class="p">(</span><span class="s1">'po3.xml'</span><span class="p">)</span><span class="o">.</span><span class="n">read</span><span class="p">())</span>
<span class="nb">print</span><span class="p">(</span><span class="s1">'</span><span class="si">%s</span><span class="s1"> is sending </span><span class="si">%s</span><span class="s1"> </span><span class="si">%d</span><span class="s1"> thing(s):'</span> <span class="o">%</span> <span class="p">(</span><span class="n">order</span><span class="o">.</span><span class="n">billTo</span><span class="o">.</span><span class="n">name</span><span class="p">,</span> <span class="n">order</span><span class="o">.</span><span class="n">shipTo</span><span class="o">.</span><span class="n">name</span><span class="p">,</span> <span class="nb">len</span><span class="p">(</span><span class="n">order</span><span class="o">.</span><span class="n">items</span><span class="o">.</span><span class="n">item</span><span class="p">)))</span>
<span class="k">for</span> <span class="n">item</span> <span class="ow">in</span> <span class="n">order</span><span class="o">.</span><span class="n">items</span><span class="o">.</span><span class="n">item</span><span class="p">:</span>
<span class="nb">print</span><span class="p">(</span><span class="s1">' Quantity </span><span class="si">%d</span><span class="s1"> of </span><span class="si">%s</span><span class="s1"> at $</span><span class="si">%s</span><span class="s1">'</span> <span class="o">%</span> <span class="p">(</span><span class="n">item</span><span class="o">.</span><span class="n">quantity</span><span class="p">,</span> <span class="n">item</span><span class="o">.</span><span class="n">productName</span><span class="p">,</span> <span class="n">item</span><span class="o">.</span><span class="n">USPrice</span><span class="p">))</span>
</pre></div>
</div>
<p>More often, you will want to be able to import the module defining bindings
from the additional namespaces. To do this, explicitly reference the
additional schema and provide it with a module name:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">pyxbgen</span> \
<span class="o">-</span><span class="n">u</span> <span class="n">po3</span><span class="o">.</span><span class="n">xsd</span> <span class="o">-</span><span class="n">m</span> <span class="n">po3</span> \
<span class="o">-</span><span class="n">u</span> <span class="n">nsaddress</span><span class="o">.</span><span class="n">xsd</span> <span class="o">-</span><span class="n">m</span> <span class="n">address</span>
</pre></div>
</div>
<p>Here each namespace is represented in its own module (<code class="docutils literal"><span class="pre">address</span></code> for
<code class="docutils literal"><span class="pre">URN:address</span></code> and <code class="docutils literal"><span class="pre">po3</span></code> for module with an absent namespace). In this
case, the demonstration program is unchanged; see <a class="reference internal" href="userref_usebind.html#from-python"><span class="std std-ref">Creating Instances in Python Code</span></a> for
additional examples.</p>
</div>
<div class="section" id="sharing-namespace-bindings">
<h2>Sharing Namespace Bindings<a class="headerlink" href="#sharing-namespace-bindings" title="Permalink to this headline">¶</a></h2>
<p>Most often, if you have a common utility namespace like <code class="docutils literal"><span class="pre">URN:address</span></code>, you
will want to generate its bindings once, and reference them in other schema
without regenerating them. To do this, PyXB must be provided with an
archive containing the schema components that were defined in that
namespace, so they can be referenced in independent generation activities.</p>
<p>To generate the archive, you add the <a class="reference internal" href="pyxbgen_cli.html#pyxbgen-archive-to-file"><span class="std std-ref">–archive-to-file</span></a>
flag to the binding generation command:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">pyxbgen</span> \
<span class="o">-</span><span class="n">u</span> <span class="n">nsaddress</span><span class="o">.</span><span class="n">xsd</span> <span class="o">-</span><span class="n">m</span> <span class="n">address</span> \
<span class="o">--</span><span class="n">archive</span><span class="o">-</span><span class="n">to</span><span class="o">-</span><span class="n">file</span> <span class="n">address</span><span class="o">.</span><span class="n">wxs</span>
</pre></div>
</div>
<p>In addition to generating the <code class="docutils literal"><span class="pre">address</span></code> Python module, this causes a
<a class="reference internal" href="arch_namespaces.html#namespace-archive"><span class="std std-ref">archive</span></a> of the schema contents to be saved in the
corresponding file, which by convention ends with the extension <code class="docutils literal"><span class="pre">.wxs</span></code>.
Any anonymous names that were generated with the bindings are also recorded
in this archive, so that cross-namespace extension works correctly.</p>
<p>You can then generate bindings for importing namespaces by providing PyXB
with the information necessary to locate this archive:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">pyxbgen</span> \
<span class="o">-</span><span class="n">u</span> <span class="n">po3</span><span class="o">.</span><span class="n">xsd</span> <span class="o">-</span><span class="n">m</span> <span class="n">po3</span> \
<span class="o">--</span><span class="n">archive</span><span class="o">-</span><span class="n">path</span> <span class="o">.</span><span class="p">:</span><span class="o">+</span>
</pre></div>
</div>
<p>The <a class="reference internal" href="pyxbgen_cli.html#pyxbgen-archive-path"><span class="std std-ref">–archive-path</span></a> directive indicates that the current
directory (<code class="docutils literal"><span class="pre">.</span></code>) should be searched for files that end in <code class="docutils literal"><span class="pre">.wxs</span></code>, and any
namespaces found in such files implicitly made available for reference when
they are encountered in an <code class="docutils literal"><span class="pre">import</span></code> instruction. (The second path
component <code class="docutils literal"><span class="pre">+</span></code> causes the standard search path to be used after searching
the current directory.)</p>
<p>In this case, when the <code class="docutils literal"><span class="pre">import</span></code> instruction is encountered, PyXB detects
that it has an archive <code class="docutils literal"><span class="pre">address.wxs</span></code> that defines the contents of the
imported namespace. Instead of reading and processing the schema, it
generates references to the existing binding modules. Again, the
demonstration program is unchanged.</p>
</div>
<div class="section" id="advanced-topics">
<h2>Advanced Topics<a class="headerlink" href="#advanced-topics" title="Permalink to this headline">¶</a></h2>
<div class="section" id="schemas-defined-in-wsdl-documents">
<h3>Schemas Defined in WSDL Documents<a class="headerlink" href="#schemas-defined-in-wsdl-documents" title="Permalink to this headline">¶</a></h3>
<p>It is a common, if regrettable, practice that web services define the
structure of their documents using XML schema elements encoded directly into
a <code class="docutils literal"><span class="pre">types</span></code> element of a WSDL specification rather than having that elements
import complete standalone schema. To accommodate this, pyxbgen supports
the <a class="reference internal" href="pyxbgen_cli.html#pyxbgen-wsdl-location"><span class="std std-ref">–wsdl-location</span></a> argument as an alternative to
<a class="reference internal" href="pyxbgen_cli.html#pyxbgen-schema-location"><span class="std std-ref">–schema-location</span></a>. For example, the following will generate a
module <code class="docutils literal"><span class="pre">ndfd</span></code> containing bindings required to communicate with the
<a class="reference external" href="http://www.nws.noaa.gov/xml">National Digital Forecast Database</a>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>pyxbgen \
--wsdl-location=http://www.weather.gov/forecasts/xml/DWMLgen/wsdl/ndfdXML.wsdl --module=ndfd \
--archive-path=${PYXB_ROOT}/pyxb/bundles/wssplat//:+
</pre></div>
</div>
<p>Note that it will be necessary to have the <a class="reference internal" href="bundles.html#bundle-wssplat"><span class="std std-ref">WS-*</span></a>
bindings available, as provided by the <a class="reference internal" href="pyxbgen_cli.html#pyxbgen-archive-path"><span class="std std-ref">–archive-path</span></a> option
above.</p>
</div>
<div class="section" id="customizing-binding-classes">
<span id="customized-bindings"></span><h3>Customizing Binding Classes<a class="headerlink" href="#customizing-binding-classes" title="Permalink to this headline">¶</a></h3>
<p>PyXB permits you to customize the bindings that it generates by creating a
module that imports the generated classes and instances, then extends them
with subclasses with additional behavior. As long as you do not make major
changes to the structure and names used in your namespaces, you can
fine-tune the schema without changing the custom code.</p>
<p>The <a class="reference internal" href="pyxbgen_cli.html#pyxbgen-write-for-customization"><span class="std std-ref">–write-for-customization</span></a> option causes PyXB to generate
all the Python modules in a subdirectory <code class="docutils literal"><span class="pre">raw</span></code>. Then you write a module
that imports the generated bindings and extends them.</p>
<p>Until this documentation is enhanced significantly, users interested in
generating custom bindings are referred to the extensions for WSDL 1.1 that
are provided in the WS-* support bundle as
<code class="docutils literal"><span class="pre">pyxb.bundles.wssplat.wsdl11.py</span></code>. An excerpt of the sort of thing done
there is:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">pyxb.bundles.wssplat.raw.wsdl11</span> <span class="k">import</span> <span class="o">*</span>
<span class="kn">import</span> <span class="nn">pyxb.bundles.wssplat.raw.wsdl11</span> <span class="k">as</span> <span class="nn">raw_wsdl11</span>
<span class="k">class</span> <span class="nc">tParam</span> <span class="p">(</span><span class="n">raw_wsdl11</span><span class="o">.</span><span class="n">tParam</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">__getMessageReference</span> <span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">__messageReference</span>
<span class="k">def</span> <span class="nf">_setMessageReference</span> <span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">message_reference</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">__messageReference</span> <span class="o">=</span> <span class="n">message_reference</span>
<span class="n">__messageReference</span> <span class="o">=</span> <span class="kc">None</span>
<span class="n">messageReference</span> <span class="o">=</span> <span class="nb">property</span><span class="p">(</span><span class="n">__getMessageReference</span><span class="p">)</span>
<span class="n">raw_wsdl11</span><span class="o">.</span><span class="n">tParam</span><span class="o">.</span><span class="n">_SetSupersedingClass</span><span class="p">(</span><span class="n">tParam</span><span class="p">)</span>
</pre></div>
</div>
<p>The first line brings in all the public identifiers from the generated
binding. The second makes them available in a qualified form that ensures
we use the generated value rather than the customized value.</p>
<p>The class definition shows how to extend the generated bindings for the
<code class="docutils literal"><span class="pre">tParam</span></code> complex type so that it has a field that can hold the instance
of <code class="docutils literal"><span class="pre">tMessage</span></code> that was identified by the <code class="docutils literal"><span class="pre">message</span></code> attribute in an
<code class="docutils literal"><span class="pre">operation</span></code> element. Following the class is a directive that tells PyXB to
create instances of the customized class when automatically generating
<code class="docutils literal"><span class="pre">tParam</span></code> instances from XML documents.</p>
<p>To customize bindings, you will need to be familiar with the
<a class="reference internal" href="pyxb.binding.html#pyxb.binding.basis._DynamicCreate_mixin" title="pyxb.binding.basis._DynamicCreate_mixin"><code class="xref py py-obj docutils literal"><span class="pre">pyxb.binding.basis._DynamicCreate_mixin</span></code></a> class.</p>
<p>Be aware that <a class="reference internal" href="pyxb.binding.html#pyxb.binding.basis._DynamicCreate_mixin" title="pyxb.binding.basis._DynamicCreate_mixin"><code class="xref py py-obj docutils literal"><span class="pre">_SetSupersedingClass</span></code></a> only affects the behavior of
<a class="reference internal" href="pyxb.binding.html#pyxb.binding.basis._TypeBinding_mixin" title="pyxb.binding.basis._TypeBinding_mixin"><code class="xref py py-obj docutils literal"><span class="pre">Factory</span></code></a>, and does not change
the Python inheritance tree. This means that the superseding class is only
invoked when the content model requires an instance of the original type.
When an instance of a subclass of a superseded class (that is not itself
superseded) is needed by the content model, this infrastructure is bypassed,
the normal Python inheritance mechanism takes control, and the instance will
not be an instance of the superseding class. This will happen both when
instances are created in Python directly and when they are created due to
presence in the binding model.</p>
<p>This is probably not what you will want, and to avoid it you must customize
all subclasses of a customized class. A detailed example customization is
in the <code class="file docutils literal"><span class="pre">examples/customization</span></code> subdirectory of the distribution. In
particular, it shows how to introspect the binding model extracted from the
generated Python module and programmatically create custom binding classes
without manually reproducing the content hierarchy, making the customizing
module more compact and stable.</p>
</div>
<div class="section" id="generating-related-namespaces">
<h3>Generating Related Namespaces<a class="headerlink" href="#generating-related-namespaces" title="Permalink to this headline">¶</a></h3>
<p>The <a class="reference internal" href="pyxbgen_cli.html#pyxbgen-module-prefix"><span class="std std-ref">–module-prefix</span></a> option permits you to add a fixed prefix
to the generated modules. For example, when generating bindings for the
OpenGIS schemas it is desirable to aggregate them into a Python module
hierarchy so the imported name incorporates the namespace collection:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>pyxbgen \
--schema-location=${SCHEMA_DIR}/gml/3.2.1/gml.xsd --module=gml_3_2 \
--schema-location=${SCHEMA_DIR}/iso/19139/20070417/gmd/gmd.xsd --module=iso19139.gmd \
--schema-location=${SCHEMA_DIR}/iso/19139/20070417/gts/gts.xsd --module=iso19139.gts \
--schema-location=${SCHEMA_DIR}/iso/19139/20070417/gsr/gsr.xsd --module=iso19139.gsr \
--schema-location=${SCHEMA_DIR}/iso/19139/20070417/gss/gss.xsd --module=iso19139.gss \
--schema-location=${SCHEMA_DIR}/iso/19139/20070417/gco/gco.xsd --module=iso19139.gco \
--module-prefix=opengis \
--archive-to-file=opengis/iso19139.core.wxs
</pre></div>
</div>
<p>When generated this way, your Python code imports these modules with
directives like:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">opengis.gml_3_2</span> <span class="k">as</span> <span class="nn">gml</span>
<span class="kn">import</span> <span class="nn">opengis.iso19139.gmd</span>
</pre></div>
</div>
<p>PyXB comes with <a class="reference internal" href="bundles.html#bundles"><span class="std std-ref">pre-defined bundles</span></a> for related namespaces
in the <code class="docutils literal"><span class="pre">pyxb.bundles</span></code> module hierarchy. The command above is an excerpt
from an early version of the script that generates the <a class="reference internal" href="bundles.html#bundle-opengis"><span class="std std-ref">OpenGIS</span></a> bundles. See <a class="reference internal" href="bundles.html#bundle-layout"><span class="std std-ref">Layout of a Bundle Directory</span></a> for more information and the location of the current
version of the script.</p>
</div>
<div class="section" id="fine-grained-namespace-control">
<h3>Fine-Grained Namespace Control<a class="headerlink" href="#fine-grained-namespace-control" title="Permalink to this headline">¶</a></h3>
<p>In certain cases, schema developers will presume that it is within their
purview to re-declare or extend the contents of namespaces that belong to
others. Supporting this while preserving or re-using the original namespace
contents requires finesse.</p>
<p>For example, when generating the bindings for the OpenGIS <a class="reference external" href="http://www.opengeospatial.org/standards/sos">Sensor
Observation Service</a>, you
would find that this service extends the <code class="docutils literal"><span class="pre">http://www.opengis.net/ogc</span></code>
namespace, normally defined in the OpenGIS <a class="reference external" href="http://www.opengeospatial.org/standards/filter">Filter Encoding</a>, with temporal operators
that are defined in a local schema <code class="docutils literal"><span class="pre">ogc4sos.xsd</span></code>.</p>
<p>Because <code class="docutils literal"><span class="pre">http://www.opengis.net/ogc</span></code> is defined in a namespace archive,
PyXB would normally assume that any <code class="docutils literal"><span class="pre">import</span></code> commands related to that
namespace are redundant with the contents of that archive, and would ignore
the import directive. In this case, that assumption is mistaken, and the
<code class="docutils literal"><span class="pre">ogc4sos.xsd</span></code> schema must be read to define the additional elements and
types. The required build command is:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>pyxbgen \
--schema-location=${SCHEMA_DIR}/sos/1.0.0/sosAll.xsd --module sos_1_0 \
--archive-path=${ARCHIVE_DIR} \
--import-augmentable-namespace=http://www.opengis.net/ogc
</pre></div>
</div>
<p>The <a class="reference internal" href="pyxbgen_cli.html#pyxbgen-import-augmentable-namespace"><span class="std std-ref">–import-augmentable-namespace</span></a> directive causes PyXB to
allow import directives within the schema to add material to the content
already loaded from an archive. Consequently, when reference to the
<code class="docutils literal"><span class="pre">ogc4sos.xsd</span></code> schema is encountered, PyXB detects that, although it
already has definitions for components in that namespace, this particular
schema has not yet been read. PyXB reads the additional components, and
generates bindings for the additional material into a private module
<code class="docutils literal"><span class="pre">_ogc</span></code> which is then imported into the <code class="docutils literal"><span class="pre">sos_1_0</span></code> module.</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="#">Generating Binding Classes</a><ul>
<li><a class="reference internal" href="#self-contained-schema">Self-contained schema</a></li>
<li><a class="reference internal" href="#multi-document-schema">Multi-document schema</a></li>
<li><a class="reference internal" href="#working-with-namespaces">Working with Namespaces</a></li>
<li><a class="reference internal" href="#sharing-namespace-bindings">Sharing Namespace Bindings</a></li>
<li><a class="reference internal" href="#advanced-topics">Advanced Topics</a><ul>
<li><a class="reference internal" href="#schemas-defined-in-wsdl-documents">Schemas Defined in WSDL Documents</a></li>
<li><a class="reference internal" href="#customizing-binding-classes">Customizing Binding Classes</a></li>
<li><a class="reference internal" href="#generating-related-namespaces">Generating Related Namespaces</a></li>
<li><a class="reference internal" href="#fine-grained-namespace-control">Fine-Grained Namespace Control</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="userref_index.html"
title="previous chapter">User Reference</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="userref_usebind.html"
title="next chapter">Using Binding Classes</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/userref_pyxbgen.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_usebind.html" title="Using Binding Classes"
>next</a> |</li>
<li class="right" >
<a href="userref_index.html" title="User Reference"
>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="userref_index.html" >User Reference</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>
