# -*- coding: utf-8 -*- # Copyright 2009-2013, Peter A. Bigot # # Licensed under the Apache License, Version 2.0 (the "License"); you may # not use this file except in compliance with the License. You may obtain a # copy of the License at: # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, WITHOUT # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the # License for the specific language governing permissions and limitations # under the License. """This module contains support for generating bindings from an XML stream using a SAX parser.""" import logging import xml.dom import pyxb.namespace import pyxb.utils.saxutils import pyxb.utils.saxdom import pyxb.utils.utility from pyxb.binding import basis from pyxb.namespace.builtin import XMLSchema_instance as XSI _log = logging.getLogger(__name__) class _SAXElementState (pyxb.utils.saxutils.SAXElementState): """State required to generate bindings for a specific element. If the document being parsed includes references to unrecognized elements, a DOM instance of the element and its content is created and treated as a wildcard element. """ # An expanded name corresponding to xsi:nil __XSINilTuple = XSI.nil.uriTuple() # The binding instance being created for this element. When the # element type has simple content, the binding instance cannot be # created until the end of the element has been reached and the # content of the element has been processed accumulated for use in # the instance constructor. When the element type has complex # content, the binding instance must be created at the start of # the element, so contained elements can be properly stored. __bindingInstance = None # The schema binding for the element being constructed. __elementBinding = None def setElementBinding (self, element_binding): """Record the binding to be used for this element. Generally ignored, except at the top level this is the only way to associate a binding instance created from an xsi:type description with a specific element.""" self.__elementBinding = element_binding # The nearest enclosing complex type definition def enclosingCTD (self): """The nearest enclosing complex type definition, as used for resolving local element/attribute names. @return: An instance of L{basis.complexTypeDefinition}, or C{None} if the element is top-level """ return self.__enclosingCTD __enclosingCTD = None # The factory that is called to create a binding instance for this # element; None if the binding instance was created at the start # of the element. __delayedConstructor = None # An xml.sax.xmlreader.Attributes instance providing the # attributes for the element. __attributes = None # An xml.dom.Node corresponding to the (sub-)document __domDocument = None __domDepth = None def __init__ (self, **kw): super(_SAXElementState, self).__init__(**kw) self.__bindingInstance = None parent_state = self.parentState() if isinstance(parent_state, _SAXElementState): self.__enclosingCTD = parent_state.enclosingCTD() self.__domDocument = parent_state.__domDocument if self.__domDocument is not None: self.__domDepth = parent_state.__domDepth + 1 def setEnclosingCTD (self, enclosing_ctd): """Set the enclosing complex type definition for this element. @param enclosing_ctd: The scope for a local element. @type enclosing_ctd: L{basis.complexTypeDefinition} @return: C{self} """ self.__enclosingCTD = enclosing_ctd # Create the binding instance for this element. def __constructElement (self, new_object_factory, attrs, content=None): kw = { '_from_xml' : True, '_location' : self.location() } # Note whether the node is marked nil if self.__XSINilTuple in attrs: kw['_nil'] = pyxb.binding.datatypes.boolean(attrs.getValue(self.__XSINilTuple)) if content is None: content = [] self.__bindingInstance = new_object_factory(*content, **kw) if isinstance(self.__bindingInstance, pyxb.utils.utility.Locatable_mixin): self.__bindingInstance._setLocation(self.location()) # Record the namespace context so users of the binding can # interpret QNames within the attributes and content. self.__bindingInstance._setNamespaceContext(self.__namespaceContext) # Set instance attributes # NB: attrs implements the SAX AttributesNS interface, meaning # that names are pairs of (namespaceURI, localName), just like we # want them to be. for attr_name in self.__attributes.getNames(): attr_en = pyxb.namespace.ExpandedName(attr_name) # Ignore xmlns and xsi attributes; we've already handled those if attr_en.namespace() in ( pyxb.namespace.XMLNamespaces, XSI ): continue # The binding instance may be a simple type that does not support # attributes; the following raises an exception in that case. self.__bindingInstance._setAttribute(attr_en, attrs.getValue(attr_name)) return self.__bindingInstance def inDOMMode (self): return self.__domDocument is not None def enterDOMMode (self, attrs): """Actions upon first encountering an element for which we cannot create a binding. Invoking this transitions the parser into DOM mode, creating a new DOM document that will represent this element including its content.""" assert not self.__domDocument self.__domDocument = pyxb.utils.saxdom.Document(namespace_context=self.namespaceContext()) self.__domDepth = 0 return self.startDOMElement(attrs) def startDOMElement (self, attrs): """Actions upon entering an element that is part of a DOM subtree.""" self.__domDepth += 1 self.__attributes = pyxb.utils.saxdom.NamedNodeMap() ns_ctx = self.namespaceContext() for name in attrs.getNames(): attr_en = pyxb.namespace.ExpandedName(name) self.__attributes._addItem(pyxb.utils.saxdom.Attr(expanded_name=attr_en, namespace_context=ns_ctx, value=attrs.getValue(name), location=self.location())) def endDOMElement (self): """Actions upon leaving an element that is part of a DOM subtree.""" ns_ctx = self.namespaceContext() element = pyxb.utils.saxdom.Element(namespace_context=ns_ctx, expanded_name=self.expandedName(), attributes=self.__attributes, location=self.location()) for info in self.content(): if isinstance(info.item, xml.dom.Node): element.appendChild(info.item) else: element.appendChild(pyxb.utils.saxdom.Text(info.item, namespace_context=ns_ctx)) self.__domDepth -= 1 if 0 == self.__domDepth: self.__domDocument.appendChild(element) #pyxb.utils.saxdom._DumpDOM(self.__domDocument) self.__domDepth = None self.__domDocument = None parent_state = self.parentState() parent_state.addElementContent(self.location(), element, None) return element def startBindingElement (self, type_class, new_object_factory, element_decl, attrs): """Actions upon entering an element that will produce a binding instance. The element use is recorded. If the type is a subclass of L{basis.simpleTypeDefinition}, a delayed constructor is recorded so the binding instance can be created upon completion of the element; otherwise, a binding instance is created and stored. The attributes are used to initialize the binding instance (now, or upon element end). @param type_class: The Python type of the binding instance @type type_class: subclass of L{basis._TypeBinding_mixin} @param new_object_factory: A callable object that creates an instance of the C{type_class} @param element_decl: The element use with which the binding instance is associated. Will be C{None} for top-level elements @type element_decl: L{basis.element} @param attrs: The XML attributes associated with the element @type attrs: C{xml.sax.xmlreader.Attributes} @return: The generated binding instance, or C{None} if creation is delayed """ self.__delayedConstructor = None self.__elementDecl = element_decl self.__attributes = attrs if type_class._IsSimpleTypeContent(): self.__delayedConstructor = new_object_factory else: try: pyxb.namespace.NamespaceContext.PushContext(self.namespaceContext()) self.__constructElement(new_object_factory, attrs) finally: pyxb.namespace.NamespaceContext.PopContext() return self.__bindingInstance def endBindingElement (self): """Perform any end-of-element processing. For simple type instances, this creates the binding instance. @return: The generated binding instance """ if self.__delayedConstructor is not None: args = [] for info in self.content(): if info.maybe_element or (info.element_decl is not None): raise pyxb.NonElementValidationError(info.item, info.location) args.append(info.item) try: pyxb.namespace.NamespaceContext.PushContext(self.namespaceContext()) self.__constructElement(self.__delayedConstructor, self.__attributes, args) except pyxb.ValidationError as e: if e.location is None: e.location = self.location() raise finally: pyxb.namespace.NamespaceContext.PopContext() else: for info in self.content(): self.__bindingInstance.append(info.item, _element_decl=info.element_decl, _maybe_element=info.maybe_element, _location=info.location) parent_state = self.parentState() if parent_state is not None: parent_state.addElementContent(self.location(), self.__bindingInstance, self.__elementDecl) # As CreateFromDOM does, validate the resulting element if self.__bindingInstance._element() is None: self.__bindingInstance._setElement(self.__elementBinding) return self.__bindingInstance._postDOMValidate() class PyXBSAXHandler (pyxb.utils.saxutils.BaseSAXHandler): """A SAX handler class which generates a binding instance for a document through a streaming parser. An example of using this to parse the document held in the (unicode) text value C{xmlt} is:: import pyxb.binding.saxer import io saxer = pyxb.binding.saxer.make_parser() handler = saxer.getContentHandler() saxer.parse(io.StringIO(xmlt)) instance = handler.rootObject() """ # Whether invocation of handler methods should be traced __trace = False # An expanded name corresponding to xsi:type __XSITypeTuple = XSI.type.uriTuple() __domHandler = None __domDepth = None def rootObject (self): """Return the binding object corresponding to the top-most element in the document @return: An instance of L{basis._TypeBinding_mixin} (most usually a L{basis.complexTypeDefinition}. @raise pyxb.[UnrecognizedDOMRootNodeError: No binding could be found to match the top-level element in the document.""" if not isinstance(self.__rootObject, basis._TypeBinding_mixin): # Happens if the top-level element got processed as a DOM instance. assert isinstance(self.__rootObject, xml.dom.Node) raise pyxb.UnrecognizedDOMRootNodeError(self.__rootObject) return self.__rootObject._postDOMValidate() __rootObject = None def reset (self): """Reset the state of the handler in preparation for processing a new document. @return: C{self} """ super(PyXBSAXHandler, self).reset() self.__rootObject = None return self def __init__ (self, **kw): """Create a parser instance for converting XML to bindings. @keyword element_state_constructor: Overridden with the value L{_SAXElementState} before invoking the L{superclass constructor}. """ kw.setdefault('element_state_constructor', _SAXElementState) super(PyXBSAXHandler, self).__init__(**kw) self.reset() def startElementNS (self, name, qname, attrs): (this_state, parent_state, ns_ctx, name_en) = super(PyXBSAXHandler, self).startElementNS(name, qname, attrs) # Delegate processing if in DOM mode if this_state.inDOMMode(): return this_state.startDOMElement(attrs) # Resolve the element within the appropriate context. Note # that global elements have no use, only the binding. if parent_state.enclosingCTD() is not None: (element_binding, element_decl) = parent_state.enclosingCTD()._ElementBindingDeclForName(name_en) else: element_decl = None element_binding = name_en.elementBinding() this_state.setElementBinding(element_binding) # Non-root elements should have an element use, from which we can # extract the binding if we couldn't find one elsewhere. (Keep any # current binding, since it may be a member of a substitution group.) if (element_decl is not None) and (element_binding is None): assert self.__rootObject is not None element_binding = element_decl.elementBinding() assert element_binding is not None # Start knowing nothing type_class = None if element_binding is not None: element_binding = element_binding.elementForName(name) type_class = element_binding.typeDefinition() # Process an xsi:type attribute, if present if self.__XSITypeTuple in attrs: (did_replace, type_class) = XSI._InterpretTypeAttribute(attrs.getValue(self.__XSITypeTuple), ns_ctx, self.fallbackNamespace(), type_class) if did_replace: element_binding = None if type_class is None: # Bother. We don't know what this thing is. But that's not an # error, if the schema accepts wildcards. For consistency with # the DOM-based interface, we need to build a DOM node. return this_state.enterDOMMode(attrs) if element_binding is not None: # Invoke binding __call__ method not Factory, so can check for # abstract elements. new_object_factory = element_binding else: new_object_factory = type_class.Factory # Update the enclosing complex type definition for this # element state. assert type_class is not None if issubclass(type_class, pyxb.binding.basis.complexTypeDefinition): this_state.setEnclosingCTD(type_class) else: this_state.setEnclosingCTD(parent_state.enclosingCTD()) # Process the element start. This may or may not return a # binding object. binding_object = this_state.startBindingElement(type_class, new_object_factory, element_decl, attrs) # If the top-level element has complex content, this sets the # root object. If it has simple content, see endElementNS. if self.__rootObject is None: self.__rootObject = binding_object def endElementNS (self, name, qname): this_state = super(PyXBSAXHandler, self).endElementNS(name, qname) if this_state.inDOMMode(): # Delegate processing if in DOM mode. Note that completing this # element may take us out of DOM mode. In any case, the returned # binding object is a DOM element instance. binding_object = this_state.endDOMElement() else: # Process the element end. This will return a binding object, # either the one created at the start or the one created at # the end. binding_object = this_state.endBindingElement() assert binding_object is not None # If we don't have a root object, save it. No, there is not a # problem doing this on the close of the element. If the # top-level element has complex content, the object was # created on start, and the root object has been assigned. If # it has simple content, then there are no internal elements # that could slip in and set this before we get to it here. # # Unless we're still in DOM mode, in which case this isn't really the # root object. Then the real root object will be the one that caused # us to enter DOM mode. if (self.__rootObject is None) and not this_state.inDOMMode(): self.__rootObject = binding_object def make_parser (*args, **kw): """Extend L{pyxb.utils.saxutils.make_parser} to change the default C{content_handler_constructor} to be L{PyXBSAXHandler}. """ kw.setdefault('content_handler_constructor', PyXBSAXHandler) return pyxb.utils.saxutils.make_parser(*args, **kw) ## Local Variables: ## fill-column:78 ## End: