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
|
.. _usebind:
Using Binding Classes
=====================
Python instances corresponding to XML structures can be created in two
primary ways: from XML documents, and directly within Python code.
Generating XML documents from bindings can also be controlled.
.. _from-xml:
Creating Instances from XML Documents
-------------------------------------
XML documents are converted into Python bindings by invoking the
``CreateFromDocument`` function in a binding module. For example:
.. literalinclude:: ../examples/manual/demo3.py
The ``CreateFromDocument`` function in a given binding module is configured
so that documents with no default namespace are assumed to be in the
namespace from which the binding was generated.
.. _from-python:
Creating Instances in Python Code
---------------------------------
Creating bindings from XML documents is straightforward, because the
documents contain enough information to identify each element and attribute,
locate the corresponding use in the binding class, and store a value that is
converted to the appropriate type. Creating values in Python is inherently
more complex, because native Python objects like strings and integers do not
contain this information.
As described in :ref:`bindingModel`, binding classes corresponding to simple
types extend the underlying Python type (such as ``str`` or ``int``), and
add XML-specific information like the canonical representation of the value
in Unicode. These classes also maintain a set of facets that constrain the
values that can be stored as instances when validation is active. Binding
classes for complex types have constructors that parse positional and
keyword parameters to determine the appropriate element or attribute to
which the value belongs. Attributes are assigned using keyword parameters.
Content is assigned using positional parameters. The order of the
positional parameters must be consistent with the order expected by the
content model.
Using the schema in the :ref:`namespace-aware address schema
<nsaddress_xsd>`, we can begin to construct the example document in Python:
.. literalinclude:: ../examples/manual/demo4a.py
This produces:
.. literalinclude:: ../examples/manual/demo4a.out
Assigning to individual fields like this bypasses the complex type content
model, although each field itself is validated. For example, the address
schema does not include New York as a state, so the following assignment::
addr.state = 'NY'
will cause a :api:`pyxb.exceptions_.BadTypeValueError` exception to be raised:
.. literalinclude:: ../examples/manual/demo4a1.out
However, the order of the field assignments does not matter, as long as all
required fields are present by the time the XML document is generated.
.. literalinclude:: ../examples/manual/demo4a2.py
Alternatively, you can provide the content as positional parameters in the
object creation call:
.. literalinclude:: ../examples/manual/demo4b.py
This has the same effect, and is much more compact, but it does require that
the order match the content model.
Attributes are set using keyword parameters:
.. literalinclude:: ../examples/manual/demo4c.py
This example produces (after reformatting):
.. literalinclude:: ../examples/manual/demo4c.out
Note that, because we're in the middle of the example and have not provided
the ``items`` stanza that the content model requires, the code explicitly
disables the requirement for validation when generating XML from a binding
instance. A consequence of this is that the generated XML is not valid, and
validation must be disabled for parsing as well if the resulting document is
to be re-converted into a binding with ``CreateFromDocument``.
Creating Instances of Anonymous Types
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The style of XML schema used for purchase orders uses anonymous types for
the deeper elements of the purchase order:
.. literalinclude:: ../examples/manual/po4.xsd
In particular, there is no global ``item`` element that can be used to
create the individual items. For situations like this, we use
:api:`pyxb.BIND`:
.. literalinclude:: ../examples/manual/demo4c1.py
The :api:`pyxb.BIND` reference wraps the content of the inner elements, and
is a cue to PyXB to attempt to build an instance of whatever type of object
would satisfy the content model at that point. The resulting document
(after reformatting) is:
.. literalinclude:: ../examples/manual/demo4c1.out
The complete document is generated by the following program:
.. literalinclude:: ../examples/manual/demo4c2.py
The additional code demonstrates a couple additional features:
- Fixed attribute values are present in the bindings, even though they are
only printed if they are set explicitly
- The PyXB types for representing dates and times are extensions of those
used by Python for the same purpose, including the ability to use them in
expressions
.. _to-xml:
Creating XML Documents from Binding Instances
---------------------------------------------
All along we've been seeing how to generate XML from a binding instance.
The ``toxml`` method is short-hand for a sequence that converts the binding
to a DOM instance using ``xml.dom.minidom``, then uses the DOM interface to
generate the XML document.
The :api:`pyxb.utils.domutils.BindingDOMSupport` class provides ways to
control this generation. In particular, you may want to use something more
informative than ``ns#`` to denote namespaces in the generated documents.
This can be done using the following code:
.. literalinclude:: ../examples/manual/demo4c3.py
:lines: 20-
With this, the final document produced is:
.. literalinclude:: ../examples/manual/demo4c3.out
(Surprise: ``addr`` does not appear, because the ``nsaddress.xsd`` schema
uses the default element form ``unqualified``, so none of the address
components in the document have a namespace.)
|
