root/trunk/RBFoundation/RBFoundation/XMLBuilder.py

#!/usr/bin/env python
##~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
##~ License 
##~ 
##- The RuneBlade Foundation library is intended to ease some 
##- aspects of writing intricate Jabber, XML, and User Interface (wxPython, etc.) 
##- applications, while providing the flexibility to modularly change the 
##- architecture. Enjoy.
##~ 
##~ Copyright (C) 2002  TechGame Networks, LLC.
##~ 
##~ This library is free software; you can redistribute it and/or
##~ modify it under the terms of the BSD style License as found in the 
##~ LICENSE file included with this distribution.
##~ 
##~ TechGame Networks, LLC can be reached at:
##~ 3578 E. Hartsel Drive #211
##~ Colorado Springs, Colorado, USA, 80920
##~
##~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

"""Abstract base classes for building Python object trees from an XML stream.

Classes:

    XMLBuilderObjectBase
    XMLBuilderMixin
    XMLBuilder

History:

    Please see XMLObjectify's history.
"""

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#~ Imports                                           
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

from xml.parsers.expat import ParserCreate as _ExpatParserCreate
from BindCallable import WeakBindCallable, Curry
from XMLNamespaceMap import XMLNamespaceMap

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#~ Classes
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

class ElementFactoryError(Exception): 
    pass

class XMLBuilderObjectBase(object):
    """Base class for objects created by XMLBuilderMixin derived classes."""
    def __init__(self, owner, parent, node, attributes, namespacemap): pass
    def _addElement(self, node, obj): pass
    def _addData(self, data): pass
    def _xmlInitStarted(self): pass 
    def _xmlInitFinalized(self): pass 
    def _xmlInitComplete(self): pass 
    def _xmlGetElement(self): return self
    def _xmlChildFactory(self, owner, parent, node, attributes, namespacemap): return None
    def _toXML(self, strSplit='', *args, **kw):
        if strSplit is not None: return strSplit.join([])
        else: return []

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
class XMLBuilderMixin(object): 
    """Abstract base class that guides the building of python objects from XML.  
    Depends upon the interface defined by XMLBuilderObjectBase."""

    #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    #~ Constants / Variables / Etc. 
    #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    _seperator = '.'
    NamespaceSynonyms = {}

    #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    #~ Special 
    #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    def __init__(self):
        self._elements = []
        self._current_namespacemap = XMLNamespaceMap()

    #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    #~ Protected Methods 
    #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    def _GetElementFactory(self, owner, element, node, attributes, namespacemap):
        """Allows a derived class to return an instance factory (a class, since python is so awesome) for 
        this particular data.  The template method makes no restrictions, except that the instance factory
        must be able to accept the same arguments as this method."""
        raise ElementFactoryError('No Class Registered for %r' % (node,))

    def _SaveStackState(self, bFull=0):
        """Returns a stack state token that can be given to _RestoreStackState"""
        if bFull:
            return self._elements[:]
        else:
            return len(self._elements)

    def _RestoreStackState(self, statetoken):
        """Uses the stack state token returned by _SaveStackState to restore the
        existing element stack to a prior level."""
        if isinstance(statetoken, int):
            self._elements[statetoken:] = []
        else:
            self._elements = statetoken

    def _GetOwner(self):
        """Used by _start_element to point to the owner of the node.  Derived classes should
        override this method the owner is different than the XMLBuilder"""
        return self

    def _GetElement(self, idx=-1):
        """Used by _start_element to point to the parent of the node.  Derived classes should
        override this method the owner is different than the XMLBuilder"""
        if self._elements:
            element = self._elements[idx]
            try: xmlGetResult = element._xmlGetElement
            except AttributeError: return element
            else: return xmlGetResult()
        else: return None 

    def _GetAttributes(self, node, attributes):
        result = {}
        for attrname, attrvalue in attributes.iteritems():
            attrnamespace, attrname = self._SplitQualifiedName(attrname)
            if not attrnamespace or attrnamespace == node[0]: 
                result[node[0], attrname] = attrvalue
                result[attrname] = attrvalue
            else: result[attrnamespace, attrname] = attrvalue
        return result

    def _start_namespace_decl_handler(self, prefix, uri):
        """Part of the tree-style template method, called at the before the beginning of an XML node parse 
        to manage namespaces."""
        # Don't forget to substitute our namespace synonyms!
        uri = self.NamespaceSynonyms.get(uri or None, uri) 
        # Add the prefix/uri to our current namespace mapping
        self._current_namespacemap.setxmlns(prefix, uri)

    def _end_namespace_decl_handler(self, prefix):
        """Part of the tree-style template method, called at the after the end of an XML node parse 
        to manage namespaces."""
        pass

    def _start_element(self, name, attributes):
        """Part of the tree-style template method, called at the beginning of an XML node parse.
        Instantiates the element returned by _GetElementFactory."""
        node = self._SplitQualifiedName(name)
        newattributes = self._GetAttributes(node, attributes)
        args = (self._GetOwner(), self._GetElement(), node, newattributes, self._current_namespacemap)
        self._current_namespacemap  = self._current_namespacemap.newchain()

        build_factory = self._GetElementFactory(*args)

        if isinstance(build_factory, tuple):
            newelement = Curry.callTuple(build_factory)
        else:
            newelement = build_factory(*args)

        if self._elements:
            self._elements[-1]._addElement(node, newelement._xmlGetElement())
        self._elements.append(newelement)

        self._elements[-1]._xmlInitStarted()
        return self._elements[-1]

    def _end_element(self, name):
        """Part of the tree-style template method, called at the closing of an XML node parse.
        Simply notifies the element that it is complete."""

        if self._elements:
            try: _xmlInitFinalized = self._elements[-1]._xmlInitFinalized
            except AttributeError: pass
            else: 
                _xmlInitFinalized()

            element = self._elements.pop()
            self._current_namespacemap = self._current_namespacemap.nextmap

            element._xmlInitComplete()

            # Get the appropriate result, if it is overriden
            try: xmlGetElement = element._xmlGetElement
            except AttributeError: result = element
            else: 
                result = xmlGetElement()
        else: 
            result = None
            self._current_namespacemap = XMLNamespaceMap()
        return result

    def _char_data(self, data):
        """Part of the tree-style template method, called when PCData is found."""
        self._elements[-1]._addData(data)

    def _SplitQualifiedName(self, combined):
        idx = combined.rfind(self._seperator)
        if idx < 0: 
            namespace = None
            name = combined
        else: 
            namespace = combined[0:idx]
            name = combined[idx + len(self._seperator):]
        namespace = self.NamespaceSynonyms.get(namespace or None, namespace)
        return namespace, name

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

class XMLExpatBuilderMixin(object):
    #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    #~ Constants / Variables / Etc. 
    #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    _encoding = 'ASCII'

    #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    #~ Public Methods 
    #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    def Parse(self, *args, **kw):
        """Starts the building of python objects using the XML parser.  Assumes first argument is string-like object."""
        self._elements, self._LastCompleteElement  = [], None
        parser = self._CreateParser()

        self._do_parse(parser.Parse, *args, **kw)

        result, self._LastCompleteElement = self._LastCompleteElement, None
        return result

    def ParseFile(self, *args, **kw):
        """Starts the building of python objects using the XML parser.  Assumes first argument is a file-like object."""
        self._elements, self._LastCompleteElement  = [], None
        parser = self._CreateParser()

        self._do_parse(parser.ParseFile, *args, **kw)

        result, self._LastCompleteElement = self._LastCompleteElement, None
        return result

    #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    #~ Protected Methods 
    #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    def _CreateParser(self):
        """Creates the Expat parser in a python-OO way."""
        parser = _ExpatParserCreate(self._encoding, self._seperator)
        try: 
            #if using python 2.3 or above, the buffer text should speed things up
            parser.buffer_text = True
        except AttributeError: 
            # Otherwise, ignore the set attribute error
            pass

        parser.returns_unicode = self._encoding != 'ASCII' and 1 or 0
        parser.StartElementHandler = self._start_element
        parser.EndElementHandler = self._end_element_ex
        parser.CharacterDataHandler = self._char_data
        parser.StartNamespaceDeclHandler = self._start_namespace_decl_handler
        parser.EndNamespaceDeclHandler = self._end_namespace_decl_handler
        return parser

    def _end_element_ex(self, name):
        """Manages the _LastCompleteElement variable."""
        self._LastCompleteElement = self._end_element(name)

    def _do_parse(self, call, *args, **kw):
        try:
            call(*args, **kw)
        except StandardError, err:
            setattr(err, 'xmlsource', getattr(err, 'xmlsource', args[0]))
            raise

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

class XMLBuilder(XMLBuilderMixin, XMLExpatBuilderMixin):
    """Abstract base class closer to actualizing python object building.  
    See XMLObjectify, or XMLClassBuilder for more concrete builders."""

    #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    #~ Special 
    #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    def __call__(self, *args, **kw):
        """Calls ParseFile if the first argument is an open file, and Parse otherwise."""
        if isinstance(args[0], file):
            return self.ParseFile(*args, **kw)
        else: return self.Parse(*args, **kw)