Module eoxserver.core.util.xmltools

This module contains utils for XML encoding, decoding and printing.

XML Decoding Schemas

XML decoding schemas can be defined following the general rules for schemas defined in the Module eoxserver.core.util.decoders. The XML decoder expects xml_location for the location parameter and xml_type for the type definition parameter. That means, XML decoding schemas generally have the form:

PARAM_SCHEMA = {
    "<parameter_name>": {
        "xml_location": "<xpath_expr>",
        "xml_type": "<type_definition>"
    },
    ...
}

where

• xpath_expr is an XPath expression which designates the element or attribute to be evaluated,
• type_definition is a valid type definition as defined in Module eoxserver.core.util.decoders.

EOxServer only supports a small subset of XPath expressions, see the class documentation of XPath below. Relative XPath expressions are interpreted to be refer to the document root element. The valid base type names for XML decoders are:

• string: the string value of the parameter is returned as is,
• int: the value will be typecasted to an integer; an exception is raised if the cast fails
• float: the value will be typecasted to a float; an exception is raised if the cast fails
• intlist: the value is expected to be a list of integers separated by whitespace; a list of integers will be returned; if typecasting fails, an exception is raised
• floatlist: the value is expected to be a list of floats separated by whitespace; a list of floats will be returned; if typecasting fails, an exception is raised.
• tagName: return the tag name of the designated element
• localName: return the local name of the designated element
• element: return the designated DOM Element
• attr: return the designated DOM Attribute mode
• dict: return a dictionary of values; the values will be retrieved according to a subschema given by the entry xml_dict_elements; the subschema follows the same rules as any decoding schema with the exception that relative XPath expressions are rooted at the element designated by xml_location instead of the document root element

Minimum and maximum occurrences can be defined as described for the Module eoxserver.core.util.decoders and will be validated.

XML Decoder

class eoxserver.core.util.xmltools.XMLDecoder

This class provides XML Decoding facilities.

XMLDecoder(params=None, schema=None)

The constructor accepts two optional arguments:

• params is expected to be either a string containing well-formed XML;
• schema is expected to be a schema as described under XML Decoding Schemas above.

setParams(params)

This method accepts one mandatory parameter params which is expected to be a string containing well-formed XML.

The input params is parsed into a DOM structure using Python’s xml.dom.minidom module.

setSchema(schema)

This method accepts an XML decoding schema as described under XML Decoding Schemas above and sets the internal schema to this value.

Internally, the schema is parsed into a node structure. InternalError is raised in case the schema does not validate.

getValue(expr, default=None)

This method accepts an expression expr and a default value default as input.

If no schema has been defined, expr will be interpreted as an XPath expression. The string value of the element text is returned; if the value is missing default is returned.

If a schema has been defined, expr will be looked up in the schema, and the according value will be returned. If it is not found, default will be returned.

This method raises a XMLNodeOccurrenceError if the minimum or maximum occurrence bounds for the given XML element are violated. In case the text value of the XML element or attribute could not be casted to the expected type XMLTypeError is raised. In case expr is not defined in the schema InternalError is raised.

getValueStrict(expr)

This method accepts an expression expr as input.

If no schema has been defined, expr will be interpreted as an XPath expression. The string value of the element text is returned; if the value is missing XMLNodeNotFound will be raised.

If a schema has been defined, expr will be looked up in the schema, and the according value will be returned. If it is not found, XMLNodeNotFound will be raised.

This method raises a XMLNodeOccurrenceError if the minimum or maximum occurrence bounds for the given XML element are violated. In case the text value of the XML element or attribute could not be casted to the expected type XMLTypeError is raised. In case expr is not defined in the schema InternalError is raised.

getParams()

Returns the input XML.

getParamType()

Returns "xml".

XML Decoding Utilities

class eoxserver.core.util.xmltools.XPath(init_data)

This class represents an XPath expression. It provides methods for decoding an encoding XPath expressions as well as looking up the specified nodes in an XML structure.

The constructor accepts either an XPath expression or a list of locators as generated by XPathExprToList() as input.

Note that this implementation supports only a small subset of XPath expressions, namely parts of the abbreviated notation.

xpath_expr        ::=  "/" | ["/"] locator_list
locator_list      ::=  (element_locator "/")* node_locator
node_locator      ::=  element_locator | attribute_locator
element_locator   ::=  locator | "*"
attribute_locator ::=  "@" locator | "@*"
locator           ::=  prefix ":" localname | ["{" namespaceuri "}"] localname
prefix            ::=  NCName
localname         ::=  NCName
namespaceuri      ::=  URI | "*"

classmethod XPathExprToList(xpath_expr)

This method converts an XPath expression to a list of locators.

append(other)

Append another XPath expression and return the result.

getNodeType()

Returns "element" if the XPath expression points to an element, or "attribute" if it points to an attribute.

getNodes(context_element)

Return all the nodes designated by the XPath expression.

isAbsolute()

Returns True if the XPath expression is absolute, False otherwise.

classmethod listToXPathExpr(xpath)

This method converts a list of locators to an XPath expression.

classmethod reverse(node)

Generate an absolute XPath expression for the given node from the DOM.

XML Encoder

class eoxserver.core.util.xmltools.XMLEncoder(schemas=None)

This is the base class for XML encoders. It is intended to be subclassed by concrete encoder implementations which can use its utility methods to compose XML documents.

_initializeNamespaces()

This method must be overridden by descendants in order to initialize the namespace dictionary of the object. The dictionary keys are interpreted as namespace prefixes whereas the values contain the namespace URIs.

The return value is the namespace dictionary.

_makeElement(prefix, tag_name, content)

This method creates elements. It expects three arguments as input:

• the namespace prefix of the element; this can be the empty string for the default namespace or unqualified names.
• the tag name of the element
• the content of the element

If the content is

• a DOM Element; it will be appended to the newly created element’s child nodes;
• a list of node definitions; these nodes will be created and then appended to the newly created element
• some other argument, it will be converted to a string and be appended to the element as text value.

Node definition lists contain tuples that describe the elements or attributes to be created and/or to be appended to the parent element. 3-tuples of (prefix, tag_name, content) will be interpreted in the same way as the input parameters.

If the prefix or tag_name parameters start with a @ an attribute will be created and appended to the parent element. If the prefix or tag_name parameters contain @@ a text node will be created.

The content parameter can contain a node definition list as well.

Alternatively, 1-tuples containing a DOM Element can be specified. The DOM Element will be appended to the respective parent element.

Functions

eoxserver.core.util.xmltools.DOMElementToXML(element, nsmap=None)

This function takes a DOM element as input and returns an XML document with the input element as root encoded as ISO-8859-1 string. This function is namespace aware.

The optional nsmap parameter may contain a dictionary of XML prefixes and namespace URIs; these namespace definitions will be appended to the document root elements list of xmlns attributes. In case it is missing, the namespaces used throughout the document are automatically determined and the corresponding xmlns attributes will be created.

eoxserver.core.util.xmltools.DOMtoXML(xmldom, nsmap=None)

Takes a DOM document as input and returns the corresponding XML (no pretty printing) encoded as ISO-8859-1 string. This function is namespace aware.

The optional nsmap parameter may contain a dictionary of XML prefixes and namespace URIs; these namespace definitions will be appended to the document root elements list of xmlns attributes. In case it is missing, the namespaces used throughout the document are automatically determined and the corresponding xmlns attributes will be created.