blob: 44e7ec1d1fbde4d1776fe54a107a985a70bae2cc [file] [log] [blame]
# encoding: utf-8
# Licensed to the Apache Software Foundation (ASF) under one or more
# contributor license agreements. See the NOTICE.txt file distributed with
# this work for additional information regarding copyright ownership. The ASF
# licenses this file to you 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
# 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.
'''Object Oriented Data Technology XML utilities. These are some simple utilities
that make working with rather obtuse DOM API less painful.
__docformat__ = 'restructuredtext'
import string
import xml.dom
def text(node):
'''Return the text under the given node. Text and CDATA nodes simply return
their content. Otherwise, text is gathered in a depth-first left-to-right
traversal of the node, building up text as we go along.
>>> import xml.dom
>>> domImpl = xml.dom.getDOMImplementation()
>>> doc = domImpl.createDocument(None, None, None)
>>> root = doc.createElement('root')
>>> root.appendChild(doc.createTextNode('alpha')) # doctest: +ELLIPSIS
<DOM Text node...>
>>> text(root)
>>> child = root.appendChild(doc.createElement('child'))
>>> text(child.appendChild(doc.createCDATASection('beta')))
>>> text(root)
strings = []
_text0(node, strings)
return string.join(strings, '') # no separator
def _text0(node, strings):
'''Add the text under the given node to the list of strings.
if node.nodeType == xml.dom.Node.CDATA_SECTION_NODE:
elif node.nodeType == xml.dom.Node.TEXT_NODE:
for child in node.childNodes:
_text0(child, strings)
def add(node, elementName, value=None):
'''Add an element under the given node. Optionally, the value text is added to the element.
Returns the original node, handy for chaining calls together. If the value is a sequence,
then the element is added multiple times for each item in the sequence, using the item
as the text.
>>> from xml.dom.minidom import getDOMImplementation
>>> doc = getDOMImplementation().createDocument(None, None, None)
>>> root = doc.createElement('root')
>>> root.toxml()
>>> add(root, 'empty').toxml()
>>> add(root, 'full', 'of text').toxml()
'<root><empty/><full>of text</full></root>'
>>> add(root, 'item', [str(i) for i in range(1, 4)]).toxml()
'<root><empty/><full>of text</full><item>1</item><item>2</item><item>3</item></root>'
owner = node.ownerDocument
if isinstance(value, basestring):
elem = owner.createElement(elementName)
elif value is not None:
for i in value:
elem = owner.createElement(elementName)
return node
class DocumentableField(object):
'''A documentable field is an attribute of an object that we can serialize into XML.
def __init__(self, attrName, elemName, kind):
'''Initialize a documentable field with attrName (name of attribute in object),
elemName (name to use for XML element) and kind, which is one of the DOCUMENTABLE_*
self.attrName = attrName
self.elemName = elemName
if kind not in (DocumentableField.SINGLE_VALUE_KIND, DocumentableField.MULTI_VALUED_KIND,
raise ValueError('Invalid kind %d' % kind)
self.kind = kind
def __cmp__(self, other):
attrName = cmp(self.attrName, other.attrName)
if attrName < 0:
return -1
elif attrName == 0:
elemName = cmp(self.elemName, other.elemName)
if elemName < 0:
return -1
elif elemName == 0:
return cmp(self.kind, other.kind)
return 1
def __hash__(self):
return hash(self.attrName) ^ hash(self.elemName) ^ self.kind
class Documentable(object):
'''An object that can be documented into XML and parsed from an XML document.
def getDocumentElementName(self):
'''Get the XML tag name. Subclasses must override this
otherwise they get the tag name `UNKNOWN`.
return 'UNKNOWN'
def getDocumentableFields(self):
'''Get the sequence of documentable attributes. Subclasses should override this
with a sequence of `DocumentableField` objects. By default, we return an empty
return []
def toXML(self, owner):
'''Convert this object into XML owned by the given `owner` document.
root = owner.createElement(self.getDocumentElementName())
for df in self.getDocumentableFields():
if df.kind == DocumentableField.SINGLE_VALUE_KIND:
add(root, df.elemName, str(getattr(self, df.attrName)))
elif df.kind == DocumentableField.MULTI_VALUED_KIND:
add(root, df.elemName, [str(value) for value in getattr(self, df.attrName)])
root.appendChild(getattr(self, df.attrName).toXML(owner))
return root
def computeValueFromDocument(self, attrName, text):
'''Compute a value for the attribute named `attrName` from the
XML text representation `text`. Subclasses may wish to
override this in order to provide custom typing for certain
attributes, such as returning an integer or datetime value by
parsing the text. By default, the `text` is returned
unmodified as a string.
return text
def parse(self, node):
'''Initialize this object from the given XML DOM `node`.
if node.nodeName != self.getDocumentElementName():
raise ValueError('Expected %s element but got %s' % (self.getDocumentElementName(), node.nodeName))
fieldMap = dict(zip([i.elemName for i in self.getDocumentableFields()], self.getDocumentableFields()))
for child in filter(lambda n: n.nodeType == xml.dom.Node.ELEMENT_NODE, node.childNodes):
name = child.nodeName
if name in fieldMap:
field = fieldMap[name]
if field.kind == DocumentableField.SINGLE_VALUE_KIND:
setattr(self, field.attrName, self.computeValueFromDocument(field.attrName, text(child)))
elif field.kind == DocumentableField.MULTI_VALUED_KIND:
if not hasattr(self, field.attrName):
setattr(self, field.attrName, [])
getattr(self, field.attrName).append(self.computeValueFromDocument(field.attrName,
getattr(self, field.attrName).parse(child)
def __cmp__(self, other):
'''The documentable fields provide a bonus: we can use them to do comparisons.
for field in self.getDocumentableFields():
attrName = field.attrName
mine = getattr(self, attrName)
others = getattr(other, attrName)
rc = cmp(mine, others)
if rc < 0:
return -1
elif rc > 0:
return 1
return 0
def __hash__(self):
'''The documentable fields provide another bonus: we can use them
to do hashing.
return reduce(lambda x, y: hash(x) ^ hash(y), [getattr(self, i.attrName) for i in self.getDocumentableFields()],