1 """PyXB stands for Python U{W3C XML
2 Schema<http://www.w3.org/XML/Schema>} Bindings, and is pronounced
3 "pixbee". It enables translation between XML instance documents and
4 Python objects following rules specified by an XML Schema document.
5
6 This is the top-level entrypoint to the PyXB system. Importing this
7 gets you all the L{exceptions<pyxb.exceptions_.PyXBException>}, and
8 L{pyxb.namespace}. For more functionality, delve into these
9 submodules:
10
11 - L{pyxb.xmlschema} Module holding the
12 L{structures<pyxb.xmlschema.structures>} that convert XMLSchema
13 from a DOM model to a Python class model based on the XMLSchema
14 components. Use this when you need to operate on the component
15 model.
16
17 - L{pyxb.binding} Module used to generate the bindings and at runtime
18 to support the generated bindings. Use this if you need to use the
19 binding model or content model.
20
21 - L{pyxb.utils} Common utilities used in parsing, generating, and
22 executing. The submodules must be imported separately.
23
24 """
25
27 """This little bundle of joy exists because in Python 2.6 it
28 became an error to invoke C{object.__init__} with parameters (unless
29 you also override C{__new__}, in which case it's only a warning.
30 Whatever.). Since I'm bloody not going to check in every class
31 whether C{super(Myclass,self)} refers to C{object} (even if I could
32 figure out how to do that, 'cuz the obvious solutions don't work),
33 we'll just make this thing the root of all U{cooperative super
34 calling<http://www.geocities.com/foetsch/python/new_style_classes.htm#super>}
35 hierarchies. The standard syntax in PyXB for this pattern is::
36
37 def method_csc (self, *args, **kw):
38 super_fn = getattr(super(ThisClass, self), 'method_csc', lambda *a,**kw: self)
39 return super_fn(*args, **kw)
40
41 """
42
44
45
46
47
48
49
50
51
52
53 if issubclass(self.__class__.mro()[-2], ( list, dict )):
54 super(cscRoot, self).__init__(*args)
55
56 __version__ = '1.0.0'
57 """The version of PyXB"""
58
59 __url__ = 'http://pyxb.sourceforge.net'
60 """The URL for PyXB's homepage"""
61
62 __license__ = 'Apache License 2.0'
63
64
65 from exceptions_ import *
66
67
68 import namespace
69
71 """Bundle data for automated binding generation.
72
73 Instances of this class capture positional and keyword arguments that are
74 used to create binding instances based on context. For example, if C{w}
75 is an instance of a complex type whose C{option} element is declared to be
76 an anonymous class with simple content of type integer and an attribute of
77 C{units}, a correct assignment to that element could be achieved with::
78
79 w.option = BIND(54, units="m")
80
81 """
82 __args = None
83 __kw = None
84
86 """Cache parameters for subsequent binding creation.
87 Invoke just as you would the factory for a binding class."""
88 self.__args = args
89 self.__kw = kw
90
92 """Invoke the given factory method.
93
94 Position arguments to the factory are those cached in this instance.
95 Keyword arguments are the ones on the command line, updated from the
96 ones in this instance."""
97 kw.update(self.__kw)
98 return factory(*self.__args, **kw)
99
100
101 XMLStyle_minidom = 0
102 """Use xml.dom.minidom for XML processing. This is the fastest, but does not
103 provide location information. It produces DOM instances."""
104
105 XMLStyle_saxdom = 1
106 """Use pyxb.utils.saxdom for XML processing. This is the slowest, but both
107 provides location information and generates a DOM instance."""
108
109 XMLStyle_saxer = 2
110 """Use pyxb.binding.saxer when converting documents to binding instances.
111 This style supports location information in the bindings. It produces binding
112 instances directly, without going through a DOM stage, so is faster than
113 XMLStyle_saxdom. However, since the pyxb.xmlschema.structures classes require
114 a DOM model, XMLStyle_saxdom will be used for pyxb.utils.domutils.StringToDOM
115 if this style is selected."""
116
117 _XMLStyle = XMLStyle_saxer
118 """The current XML processing style."""
119
120 _XMLStyleMap = { 'minidom' : XMLStyle_minidom,
121 'saxdom' : XMLStyle_saxdom,
122 'saxer' : XMLStyle_saxer }
123 _XMLStyleMapReverse = dict([ (_v, _k) for (_k, _v) in _XMLStyleMap.items() ])
124
125 _XMLStyle_envvar = 'PYXB_XML_STYLE'
126
128 """Set the interface used to parse XML content.
129
130 This can be invoked within code. The system default of L{XMLStyle_saxer}
131 can also be overridden at runtime by setting the environment variable
132 C{PYXB_XML_STYLE} to one of C{minidom}, C{saxdom}, or C{saxer}.
133
134 @param style: One of L{XMLStyle_minidom}, L{XMLStyle_saxdom},
135 L{XMLStyle_saxer}. If not provided, the system default is used.
136 """
137 global _XMLStyle
138 if style is None:
139 import os
140 style_name = os.environ.get(_XMLStyle_envvar)
141 if style_name is None:
142 style_name = 'saxer'
143 style = _XMLStyleMap.get(style_name)
144 if style is None:
145 raise PyXBException('Bad value "%s" for %s' % (style_name, _XMLStyle_envvar))
146 if _XMLStyleMapReverse.get(style) is None:
147 raise PyXBException('Bad value %s for _SetXMLStyle' % (style,))
148 _XMLStyle = style
149
150
151 _SetXMLStyle()
152
153 _GenerationRequiresValid = True
155 """Query or set a flag that controls validation checking in XML generation.
156
157 Normally any attempts to convert a binding instance to a DOM or XML
158 representation requires that the binding validate against the content
159 model, since only in this way can the content be generated in the correct
160 order. In some cases it may be necessary or useful to generate a document
161 from a binding that is incomplete. If validation is not required, the
162 generated documents may not validate even if the content validates,
163 because ordering constraints will be ignored.
164
165 @keyword value: If absent or C{None}, no change is made; otherwise, this
166 enables (C{True}) or disables (C{False}) the requirement that instances
167 validate before being converted to XML.
168 @type value: C{bool}
169
170 @return: C{True} iff attempts to generate XML for a binding that does not
171 validate should raise an exception. """
172 global _GenerationRequiresValid
173 if value is None:
174 return _GenerationRequiresValid
175 if not isinstance(value, bool):
176 raise TypeError(value)
177 _GenerationRequiresValid = value
178 return _GenerationRequiresValid
179
180 _ParsingRequiresValid = True
182 """Query or set a flag that controls validation checking in XML parsing.
183
184 Normally any attempts to convert XML to a binding instance to a binding
185 instance requires that the document validate against the content model.
186 In some cases it may be necessary or useful to process a document that is
187 incomplete. If validation is not required, the generated documents may
188 not validate even if the content validates, because ordering constraints
189 will be ignored.
190
191 @keyword value: If absent or C{None}, no change is made; otherwise, this
192 enables (C{True}) or disables (C{False}) the requirement that documents
193 validate when being converted to bindings.
194 @type value: C{bool}
195
196 @return: C{True} iff attempts to generate bindings for a document that
197 does not validate should raise an exception."""
198 global _ParsingRequiresValid
199 if value is None:
200 return _ParsingRequiresValid
201 if not isinstance(value, bool):
202 raise TypeError(value)
203 _ParsingRequiresValid = value
204 return _ParsingRequiresValid
205
206
207
208
209