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.1.3'
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
154
155
156 _OptimizationActive = False
157 try:
158 assert False
159 _OptimizationActive = True
160 except:
161 pass
162
163 _CorruptionDetectionEnabled = not _OptimizationActive
164 """If C{True}, blocks attempts to assign to attributes that are reserved for
165 PyXB methods.
166
167 Applies only at compilation time; dynamic changes are ignored.
168 """
169
170 _GenerationRequiresValid = True
172 """Query or set a flag that controls validation checking in XML generation.
173
174 Normally any attempts to convert a binding instance to a DOM or XML
175 representation requires that the binding validate against the content
176 model, since only in this way can the content be generated in the correct
177 order. In some cases it may be necessary or useful to generate a document
178 from a binding that is incomplete. If validation is not required, the
179 generated documents may not validate even if the content validates,
180 because ordering constraints will be ignored.
181
182 @keyword value: If absent or C{None}, no change is made; otherwise, this
183 enables (C{True}) or disables (C{False}) the requirement that instances
184 validate before being converted to XML.
185 @type value: C{bool}
186
187 @return: C{True} iff attempts to generate XML for a binding that does not
188 validate should raise an exception. """
189 global _GenerationRequiresValid
190 if value is None:
191 return _GenerationRequiresValid
192 if not isinstance(value, bool):
193 raise TypeError(value)
194 _GenerationRequiresValid = value
195 return _GenerationRequiresValid
196
197 _ParsingRequiresValid = True
199 """Query or set a flag that controls validation checking in XML parsing.
200
201 Normally any attempts to convert XML to a binding instance to a binding
202 instance requires that the document validate against the content model.
203 In some cases it may be necessary or useful to process a document that is
204 incomplete. If validation is not required, the generated documents may
205 not validate even if the content validates, because ordering constraints
206 will be ignored.
207
208 @keyword value: If absent or C{None}, no change is made; otherwise, this
209 enables (C{True}) or disables (C{False}) the requirement that documents
210 validate when being converted to bindings.
211 @type value: C{bool}
212
213 @return: C{True} iff attempts to generate bindings for a document that
214 does not validate should raise an exception."""
215 global _ParsingRequiresValid
216 if value is None:
217 return _ParsingRequiresValid
218 if not isinstance(value, bool):
219 raise TypeError(value)
220 _ParsingRequiresValid = value
221 return _ParsingRequiresValid
222
223
224
225
226