pyxb.binding.saxer

1 # -*- coding: utf-8 -*- 2 # Copyright 2009-2012, Peter A. Bigot 3 # 4 # Licensed under the Apache License, Version 2.0 (the "License"); you may 5 # not use this file except in compliance with the License. You may obtain a 6 # copy of the License at: 7 # 8 # http://www.apache.org/licenses/LICENSE-2.0 9 # 10 # Unless required by applicable law or agreed to in writing, software 11 # distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 12 # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 13 # License for the specific language governing permissions and limitations 14 # under the License. 15 16 """This module contains support for generating bindings from an XML stream 17 using a SAX parser.""" 18 19 import xml.dom 20 import pyxb.namespace 21 import pyxb.utils.saxutils 22 import pyxb.utils.saxdom 23 import pyxb.utils.utility 24 from pyxb.binding import basis 25 from pyxb.namespace.builtin import XMLSchema_instance as XSI 26 import logging 27 28 _log = logging.getLogger(__name__) 29

30 -class _SAXElementState (pyxb.utils.saxutils.SAXElementState):

31 """State required to generate bindings for a specific element. 32 33 If the document being parsed includes references to unrecognized elements, 34 a DOM instance of the element and its content is created and treated as a 35 wildcard element. 36 """ 37 38 # An expanded name corresponding to xsi:nil 39 __XSINilTuple = XSI.nil.uriTuple() 40 41 # The binding instance being created for this element. When the 42 # element type has simple content, the binding instance cannot be 43 # created until the end of the element has been reached and the 44 # content of the element has been processed accumulated for use in 45 # the instance constructor. When the element type has complex 46 # content, the binding instance must be created at the start of 47 # the element, so contained elements can be properly stored. 48 __bindingInstance = None 49 50 # The schema binding for the element being constructed. 51 __elementBinding = None 52

53 - def setElementBinding (self, element_binding):

54 """Record the binding to be used for this element. 55 56 Generally ignored, except at the top level this is the only way to 57 associate a binding instance created from an xsi:type description with 58 a specific element.""" 59 self.__elementBinding = element_binding

60 61 # The nearest enclosing complex type definition

62 - def enclosingCTD (self):

63 """The nearest enclosing complex type definition, as used for 64 resolving local element/attribute names. 65 66 @return: An instance of L{basis.complexTypeDefinition}, or C{None} if 67 the element is top-level 68 """ 69 return self.__enclosingCTD

70 __enclosingCTD = None 71 72 # The factory that is called to create a binding instance for this 73 # element; None if the binding instance was created at the start 74 # of the element. 75 __delayedConstructor = None 76 77 # An xml.sax.xmlreader.Attributes instance providing the 78 # attributes for the element. 79 __attributes = None 80 81 # An xml.dom.Node corresponding to the (sub-)document 82 __domDocument = None 83 84 __domDepth = None 85

86 - def __init__ (self, **kw):

87 super(_SAXElementState, self).__init__(**kw) 88 self.__bindingInstance = None 89 parent_state = self.parentState() 90 if isinstance(parent_state, _SAXElementState): 91 self.__enclosingCTD = parent_state.enclosingCTD() 92 self.__domDocument = parent_state.__domDocument 93 if self.__domDocument is not None: 94 self.__domDepth = parent_state.__domDepth + 1

95

96 - def setEnclosingCTD (self, enclosing_ctd):

97 """Set the enclosing complex type definition for this element. 98 99 @param enclosing_ctd: The scope for a local element. 100 @type enclosing_ctd: L{basis.complexTypeDefinition} 101 @return: C{self} 102 """ 103 self.__enclosingCTD = enclosing_ctd

104 105 # Create the binding instance for this element.

106 - def __constructElement (self, new_object_factory, attrs, content=None):

107 kw = { '_from_xml' : True } 108 109 # Note whether the node is marked nil 110 if attrs.has_key(self.__XSINilTuple): 111 kw['_nil'] = pyxb.binding.datatypes.boolean(attrs.getValue(self.__XSINilTuple)) 112 113 if content is None: 114 content = [] 115 self.__bindingInstance = new_object_factory(*content, **kw) 116 if isinstance(self.__bindingInstance, pyxb.utils.utility.Locatable_mixin): 117 self.__bindingInstance._setLocation(self.location()) 118 119 # Record the namespace context so users of the binding can 120 # interpret QNames within the attributes and content. 121 self.__bindingInstance._setNamespaceContext(self.__namespaceContext) 122 123 # Set instance attributes 124 # NB: attrs implements the SAX AttributesNS interface, meaning 125 # that names are pairs of (namespaceURI, localName), just like we 126 # want them to be. 127 for attr_name in self.__attributes.getNames(): 128 attr_en = pyxb.namespace.ExpandedName(attr_name) 129 # Ignore xmlns and xsi attributes; we've already handled those 130 if attr_en.namespace() in ( pyxb.namespace.XMLNamespaces, XSI ): 131 continue 132 self.__bindingInstance._setAttribute(attr_en, attrs.getValue(attr_name)) 133 134 return self.__bindingInstance

135

136 - def inDOMMode (self):

137 return self.__domDocument is not None

138

139 - def enterDOMMode (self, attrs):

140 """Actions upon first encountering an element for which we cannot create a binding. 141 142 Invoking this transitions the parser into DOM mode, creating a new DOM 143 document that will represent this element including its content.""" 144 assert not self.__domDocument 145 self.__domDocument = pyxb.utils.saxdom.Document(namespace_context=self.namespaceContext()) 146 self.__domDepth = 0 147 return self.startDOMElement(attrs)

148

149 - def startDOMElement (self, attrs):

150 """Actions upon entering an element that is part of a DOM subtree.""" 151 self.__domDepth += 1 152 self.__attributes = pyxb.utils.saxdom.NamedNodeMap() 153 ns_ctx = self.namespaceContext() 154 for name in attrs.getNames(): 155 attr_en = pyxb.namespace.ExpandedName(name) 156 self.__attributes._addItem(pyxb.utils.saxdom.Attr(expanded_name=attr_en, namespace_context=ns_ctx, value=attrs.getValue(name), location=self.location()))

157

158 - def endDOMElement (self):

159 """Actions upon leaving an element that is part of a DOM subtree.""" 160 ns_ctx = self.namespaceContext() 161 element = pyxb.utils.saxdom.Element(namespace_context=ns_ctx, expanded_name=self.expandedName(), attributes=self.__attributes, location=self.location()) 162 for ( content, element_use, maybe_element ) in self.content(): 163 if isinstance(content, xml.dom.Node): 164 element.appendChild(content) 165 else: 166 element.appendChild(pyxb.utils.saxdom.Text(content, namespace_context=ns_ctx)) 167 self.__domDepth -= 1 168 if 0 == self.__domDepth: 169 self.__domDocument.appendChild(element) 170 #pyxb.utils.saxdom._DumpDOM(self.__domDocument) 171 self.__domDepth = None 172 self.__domDocument = None 173 parent_state = self.parentState() 174 parent_state.addElementContent(element, None) 175 return element

176

177 - def startBindingElement (self, type_class, new_object_factory, element_use, attrs):

178 """Actions upon entering an element that will produce a binding instance. 179 180 The element use is recorded. If the type is a subclass of 181 L{basis.simpleTypeDefinition}, a delayed constructor is recorded so 182 the binding instance can be created upon completion of the element; 183 otherwise, a binding instance is created and stored. The attributes 184 are used to initialize the binding instance (now, or upon element 185 end). 186 187 @param type_class: The Python type of the binding instance 188 @type type_class: subclass of L{basis._TypeBinding_mixin} 189 @param new_object_factory: A callable object that creates an instance of the C{type_class} 190 @param element_use: The element use with which the binding instance is associated. Will be C{None} for top-level elements 191 @type element_use: L{basis.element} 192 @param attrs: The XML attributes associated with the element 193 @type attrs: C{xml.sax.xmlreader.Attributes} 194 @return: The generated binding instance, or C{None} if creation is delayed 195 """ 196 self.__delayedConstructor = None 197 self.__elementUse = element_use 198 self.__attributes = attrs 199 if type_class._IsSimpleTypeContent(): 200 self.__delayedConstructor = new_object_factory 201 else: 202 self.__constructElement(new_object_factory, attrs) 203 return self.__bindingInstance

204

205 - def endBindingElement (self):

206 """Perform any end-of-element processing. 207 208 For simple type instances, this creates the binding instance. 209 @return: The generated binding instance 210 """ 211 if self.__delayedConstructor is not None: 212 args = [] 213 for (content, element_use, maybe_element) in self.__content: 214 assert not maybe_element 215 assert element_use is None 216 assert isinstance(content, basestring) 217 args.append(content) 218 assert 1 >= len(args), 'Unexpected STD content %s' % (args,) 219 self.__constructElement(self.__delayedConstructor, self.__attributes, args) 220 else: 221 for (content, element_use, maybe_element) in self.__content: 222 self.__bindingInstance.append(content, element_use, maybe_element, require_validation=pyxb._ParsingRequiresValid) 223 parent_state = self.parentState() 224 if parent_state is not None: 225 parent_state.addElementContent(self.__bindingInstance, self.__elementUse) 226 # As CreateFromDOM does, validate the resulting element 227 if self.__bindingInstance._element() is None: 228 self.__bindingInstance._setElement(self.__elementBinding) 229 if pyxb._ParsingRequiresValid: 230 self.__bindingInstance.validateBinding() 231 return self.__bindingInstance

232

233 -class PyXBSAXHandler (pyxb.utils.saxutils.BaseSAXHandler):

234 """A SAX handler class which generates a binding instance for a document 235 through a streaming parser. 236 237 An example of using this to parse the document held in the string C{xmls} is:: 238 239 import pyxb.binding.saxer 240 import StringIO 241 242 saxer = pyxb.binding.saxer.make_parser() 243 handler = saxer.getContentHandler() 244 saxer.parse(StringIO.StringIO(xml)) 245 instance = handler.rootObject() 246 247 """ 248 249 # Whether invocation of handler methods should be traced 250 __trace = False 251 252 # An expanded name corresponding to xsi:type 253 __XSITypeTuple = XSI.type.uriTuple() 254 255 __domHandler = None 256 __domDepth = None 257

258 - def rootObject (self):

259 """Return the binding object corresponding to the top-most 260 element in the document 261 262 @return: An instance of L{basis._TypeBinding_mixin} (most usually a 263 L{basis.complexTypeDefinition}. 264 265 @raise pyxb.UnrecognizedElementError: No binding could be found to 266 match the top-level element in the document.""" 267 if not isinstance(self.__rootObject, basis._TypeBinding_mixin): 268 # Happens if the top-level element got processed as a DOM instance. 269 raise pyxb.UnrecognizedElementError(dom_node=self.__rootObject) 270 return self.__rootObject

271 __rootObject = None 272

273 - def reset (self):

274 """Reset the state of the handler in preparation for processing a new 275 document. 276 277 @return: C{self} 278 """ 279 super(PyXBSAXHandler, self).reset() 280 self.__rootObject = None 281 return self

282

283 - def __init__ (self, **kw):

284 """Create a parser instance for converting XML to bindings. 285 286 @keyword element_state_constructor: Overridden with the value 287 L{_SAXElementState} before invoking the L{superclass 288 constructor<pyxb.utils.saxutils.BaseSAXHandler.__init__>}. 289 """ 290 291 kw.setdefault('element_state_constructor', _SAXElementState) 292 super(PyXBSAXHandler, self).__init__(**kw) 293 self.reset()

294

295 - def startElementNS (self, name, qname, attrs):

296 (this_state, parent_state, ns_ctx, name_en) = super(PyXBSAXHandler, self).startElementNS(name, qname, attrs) 297 298 # Delegate processing if in DOM mode 299 if this_state.inDOMMode(): 300 return this_state.startDOMElement(attrs) 301 302 # Resolve the element within the appropriate context. Note 303 # that global elements have no use, only the binding. 304 if parent_state.enclosingCTD() is not None: 305 (element_binding, element_use) = parent_state.enclosingCTD()._ElementBindingUseForName(name_en) 306 else: 307 element_use = None 308 element_binding = name_en.elementBinding() 309 this_state.setElementBinding(element_binding) 310 311 # Non-root elements should have an element use, from which we can 312 # extract the binding if we couldn't find one elsewhere. (Keep any 313 # current binding, since it may be a member of a substitution group.) 314 if (element_use is not None) and (element_binding is None): 315 assert self.__rootObject is not None 316 element_binding = element_use.elementBinding() 317 assert element_binding is not None 318 319 # Start knowing nothing 320 type_class = None 321 if element_binding is not None: 322 element_binding = element_binding.elementForName(name) 323 type_class = element_binding.typeDefinition() 324 325 # Process an xsi:type attribute, if present 326 if attrs.has_key(self.__XSITypeTuple): 327 (did_replace, type_class) = XSI._InterpretTypeAttribute(attrs.getValue(self.__XSITypeTuple), ns_ctx, self.fallbackNamespace(), type_class) 328 if did_replace: 329 element_binding = None 330 331 if type_class is None: 332 # Bother. We don't know what this thing is. But that's not an 333 # error, if the schema accepts wildcards. For consistency with 334 # the DOM-based interface, we need to build a DOM node. 335 return this_state.enterDOMMode(attrs) 336 337 if element_binding is not None: 338 # Invoke binding __call__ method not Factory, so can check for 339 # abstract elements. 340 new_object_factory = element_binding 341 else: 342 new_object_factory = type_class.Factory 343 344 # Update the enclosing complex type definition for this 345 # element state. 346 assert type_class is not None 347 if issubclass(type_class, pyxb.binding.basis.complexTypeDefinition): 348 this_state.setEnclosingCTD(type_class) 349 else: 350 this_state.setEnclosingCTD(parent_state.enclosingCTD()) 351 352 # Process the element start. This may or may not return a 353 # binding object. 354 binding_object = this_state.startBindingElement(type_class, new_object_factory, element_use, attrs) 355 356 # If the top-level element has complex content, this sets the 357 # root object. If it has simple content, see endElementNS. 358 if self.__rootObject is None: 359 self.__rootObject = binding_object

360

361 - def endElementNS (self, name, qname):

362 this_state = super(PyXBSAXHandler, self).endElementNS(name, qname) 363 if this_state.inDOMMode(): 364 # Delegate processing if in DOM mode. Note that completing this 365 # element may take us out of DOM mode. In any case, the returned 366 # binding object is a DOM element instance. 367 binding_object = this_state.endDOMElement() 368 else: 369 # Process the element end. This will return a binding object, 370 # either the one created at the start or the one created at 371 # the end. 372 binding_object = this_state.endBindingElement() 373 assert binding_object is not None 374 375 # If we don't have a root object, save it. No, there is not a 376 # problem doing this on the close of the element. If the 377 # top-level element has complex content, the object was 378 # created on start, and the root object has been assigned. If 379 # it has simple content, then there are no internal elements 380 # that could slip in and set this before we get to it here. 381 if self.__rootObject is None: 382 self.__rootObject = binding_object

383

384 -def make_parser (*args, **kw):

385 """Extend L{pyxb.utils.saxutils.make_parser} to change the default 386 C{content_handler_constructor} to be L{PyXBSAXHandler}. 387 """ 388 kw.setdefault('content_handler_constructor', PyXBSAXHandler) 389 return pyxb.utils.saxutils.make_parser(*args, **kw)

390 391 ## Local Variables: 392 ## fill-column:78 393 ## End: 394

Source Code for Module pyxb.binding.saxer