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
|
**************
User Reference
**************
.. _pyxbgen:
Creating bindings with ``pyxbgen``
==================================
.. toctree::
:hidden:
pyxbgen_cli
.. include:: pyxbgen_cli.txt
** THESE EXAMPLES ARE NOT UP TO DATE. SEE `examples/ndfd/genbindings.sh`
and `examples/openGIS/makebind.sh` **
The module path and schema URI are required. Raw bindings allow the user to
import the module and obtain :ref:`customized classes
<binding_customization>` that augment the pure data with functionality or
additional data. Optionally, the XML document retrieved from the URI can be
stored into a local file for review (usually important when working with
WSDL definitions). If the XML document is a WSDL definition, only the
``types`` portion is extracted. Last, the component model must be saved if
the subsequent bindings are to be generated for namespaces that refer to
defined objects in this namespace.
The following sections reference example schema and programs that are
available in the ``examples/manual`` subdirectory of the PyXB distribution.
Self-contained schema
---------------------
The following schema ``po1.xsd`` is a condensed version of the `purchase
order schema <http://www.w3.org/TR/xmlschema-0/#POSchema>`_ in the XMLSchema
Primer:
.. literalinclude:: ../examples/manual/po1.xsd
Translate this into Python with the following command::
pyxbgen -u po1.xsd -m po1
Then this program (``demo1.py``):
.. literalinclude:: ../examples/manual/demo1.py
processing this document:
.. literalinclude:: ../examples/manual/po1.xml
produces the following output::
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
Multi-document schema
---------------------
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 USAddress can be abstracted to handle a variety of addresses, and
maintained as its own document ``address.xsd``:
.. literalinclude:: ../examples/manual/address.xsd
The XMLSchema `include directive
<http://www.w3.org/TR/xmlschema-1/#compound-schema>`_ can be used to
incorporate this document into ``po2.xsd``:
.. literalinclude:: ../examples/manual/po2.xsd
Translation of this document and execution of the test program is just as it
was in the previous section.
Multi-namespace documents
-------------------------
Documents of significant complexity are likely to require references to
multiple namespaces. You may have noticed that the schemas we've looked at
so far have :ref:`no namespace <absentNamespaces>` for both their target and
default namespaces. The following schema ``nsaddress.xsd`` places the types
that are in ``address.xsd`` into the namespace ``URN:address``:
.. literalinclude:: ../examples/manual/nsaddress.xsd
This schema can be translated into its own Python binding module with the
following command::
pyxbgen -u nsaddress.xsd -m address -C
Note that the ``-C`` or ``--save-component-model`` option was given this
time. This causes a file ``address.wxs`` to be written which contains a
:ref:`stored namespace <namespaceStorage>` with all the types and elements
defined in ``address.xsd`` available for lookup when :ref:`resolving
<resolution>` names in the ``URN:address`` namespace.
The following schema references the address information through a namespace
declaration:
.. literalinclude:: ../examples/manual/po3.xsd
and can be translated with the standard command. As with the previous
purchase order schemas, we don't need to save the component model here since
we won't be referencing it. However, we do have to set an environment
variable that tells ``pyxbgen`` where to find the stored ``URN:address``
namespace::
export PYXB_NAMESPACE_PATH=+:.
pyxbgen -u po3.xsd -m po3
The ``PYXB_NAMESPACE_PATH`` environment variable is a colon-separated set of
directories. Upon startup, the :api:`pyxb.namespace` module walks all the
specified directories looking for files that end with ``.wxs``. Any that it
finds that it can correctly read are recorded, and namespaces created, so
that if they are referenced in a schema the namespace contents can be
retrieved. The value ``+`` in the path refers to the default binding path,
which is normally ``pyxb/standard/bindings/raw`` in your installation area.
If you examine the top of the generated ``po3.py`` file, you'll see that
``pyxbgen`` inserted a Python ``import`` statement so that the
``address:USAddress`` type can be referenced in the purchase order::
# Import bindings for namespaces imported into schema
import address
The name of the module to import was retrieved from the ``address.wxs``
file.
Note that if you wish only to refer to types in a different namespace, it is
sufficient to provide the namespace declaration in the schema, and to have a
stored namespace along with the generated binding accessible to ``pyxbgen``.
If you wish to extend one of the types from the namespace, you must use the
XMLSchema `import directive
<http://www.w3.org/TR/xmlschema-1/#composition-schemaImport>`_. A fourth
example showing this is also available in the ``examples/manual``
subdirectory.
** THIS SECTION HAS NOT BEEN UPDATED FOR 0.5.0. RUN ``pyxbgen`` WITH NO
ARGUMENTS TO SEE NEW INTERFACE. ALSO SEE `examples/ndfd/genbindings.sh`
and `examples/openGIS/makebind.sh` **
Customized bindings
===================
To customize bindings, you need to be familiar with the
:api:`pyxb.binding.basis._DynamicCreate_mixin` class. One readily-available
example is :ref:`ex_tmsxtvd`. A more complex example is the customized
standard binding for WSDL, available in
:file:`pyxb/standard/bindings/wsdl.py`.
|
