ecoxipy - The ECoXiPy API

The package ecoxipy contains the basic API for creating XML. The central MarkupBuilder provides the interface you use, through an instance of this class all XML creation is done. An instance of Output you give to the MarkupBuilder (if you don’t an instance of ecoxipy.pyxom.output.PyXOMOutput is created) does all the actual work and creates data in its XML representation. This way the same code can create XML as:

• ecoxipy.pyxom structures, those can create xml.sax events or can be serialized to byte or Unicode strings, besides being easily navigateable.
• Strings using ecoxipy.string_output.
• xml.dom structures using ecoxipy.dom_output.
• xml.etree structures using ecoxipy.etree_output.
• Any other data you can think of by implementing your own Output class.

XML Creation

You use instances of MarkupBuilder to create XML, which use the Output implementation given on initialization. The following subsections explain how to use the builder.

Attribute and Item Retrieval - Elements

To create elements use attribute or item retrieval on a MarkupBuilder instance, this returns a method which on calling creates an element in the output representation determined by the used Output subclass instance. The name of the element is the attribute name, or the item key converted to a Unicode string for item retrieval respectively. The element children are the positional arguments of the method call, the attributes are determined by the named attributes and by children of a mapping type.

These virtual (not in the C sense) methods have the following signature (with element_name being substituted by the name of the element to create):

.method_name(self, *children, **attributes)

Creates an element in the output representation with the name method_name.

Parameters:

• children – The children of the element.
• attributes – Each entry of this mapping defines an attribute of the created element, the name being the key and the value being the value identified by the key. Keys and values are converted to Unicode, byte strings are decoded using the input encoding.

Each item of children is preprocessed as follows, before it is given to the Output instance:

1. If the item is native to the output representation, it is left unchanged.
2. If the item is a Unicode or byte string, it is replace by a text node created from it. Byte strings are first decoded with the given input encoding.
3. If the item is of a mapping type (i.e. it has a keys() method and supports item retrieval for the keys), the entries define attributes. Entries from children mappings overwrite attributes defined by mappings more to the left. The entries of attributes overwrite entries from children items. Keys and values are converted to Unicode values, byte strings are decoded with the input encoding.
4. If the item is iterable, it is replaced with its items after they have been preprocessed.
5. If the item is a callable allowing no arguments, it is replaced with the result of its call, after this has been preprocessed.
6. All other items are converted to Unicode strings and create text nodes.

It is the responsibility of the caller to ensure that no infinite recursion occurs in steps 4 and 5.

Each failed attribute retrieval on an instance of MarkupBuilder returns such a method, thus you should not create elements with names starting with _ in this way, as MarkupBuilder instances may have such attributes. Of course only elements with names conforming to the Python identifier syntax can be created using attribute access, for creating other elements use the subscript syntax for item access.

Slicing - Processing Instructions and Documents

On a MarkupBuilder instance you can use slicing to create processing instructions or documents.

You create processing instructions by using the slicing operator with a start argument, which becomes the target. If the end argument is specified it becomes the content. So the slice ['xml-stylesheet':'href="style.css"'] becomes a processing instruction with target xml-stylesheet and content href="style.css".

If the slicing start argument is not specified, a function creating a XML document is returned. The arguments of that function become the document root nodes and are preprocessed the same as with element children, except for attribute handling. The slicing end argument (if specified) denotes the document type declaration content. It can either be a 3-tuple() containing the document element name, the public ID and the system ID or a single object to be used as the document element name. If the slicing step argument is True, the XML declaration is omitted and the document encoding is UTF-8. Otherwise the slicing step denotes the document encoding and the XML declaration is not omitted. If no step is specified, the encoding is UTF-8 and the XML declaration is not omitted. So the slice [:('html', '-//W3C//DTD XHTML 1.0 Strict//EN', 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'):True] creates a XHTML 1.0 Strict document without a XML declaration.

Calling - XML Fragments

You can also call MarkupBuilder instances to parse XML fragments (lists of XML Nodes). As with the element children, the arguments are preprocessed, but here attribute creation is not handled and each of the Unicode strings is parsed as XML using ecoxipy.parsing.XMLFragmentParser (this will raise a xml.sax.SAXException if the XML is not well-formed).

Operators - Text and Comments

The following operators create special nodes from their argument on a MarkupBuilder instance:

&

Creates a text node.

|

Creates a comment.

Classes

class ecoxipy.MarkupBuilder(output=None, in_encoding='UTF-8', parser=None)

A builder for creating XML in a pythonic way. All byte strings given are are decoded with the input encoding specified on instanciation.

Parameters:

• output (Output) – The output to use. If this is None, ecoxipy.pyxom.output.PyXOMOutput is used.
• in_encoding – The input encoding to be used to decode byte strings to Unicode.
• parser (xml.sax.xmlreader.XMLReader) – The SAX parser to use for parsing XML. If it is None the default of ecoxipy.parsing.XMLFragmentParser is used.

__getattr__(name)

Return an element-creating function.

Parameters:name – The element name. Returns:An element in the output representation.

__getitem__(key)

Return an element-creating function for item access or either a processing instruction or a document for slicing.

Parameters:key – The element name or slicing values. Returns:An element, a processing instruction or a document in the output representation.

__call__(*content)

Parses the content items as XML fragments, if they are not output representation objects. See Calling - XML Fragments for more information.

Parameters:content – The XML fragments to parse or objects of the output representation. Returns:Objects of the output representation.

__and__(content)

Creates a text node. See Operators - Text and Comments for more information.

__or__(content)

Creates a comment. See Operators - Text and Comments for more information.

class ecoxipy.Output

Abstract base class defining the MarkupBuilder output interface.

The abstract methods are called by MarkupBuilder instances to create XML representations. All data is assumed to be given as Unicode strings if not otherwise stated, MarkupBuilder takes care of that.

An output implementation may specify a preprocessing callable (e.g. a method) in the attribute preprocess, which is called with every content object as the single argument. This attribute may also be None.

An output implementation may specify a callable (e.g. a method) to create XML fragments in the attribute fragment, which is called with one argument containing the content objects in a collections.deque instance. This attribute may also be None.

is_native_type(content)

Tests if an object is native to the output representation. This is used by MarkupBuilder to test children of elements and documents if they can be fed to the Output implementation without conversion.

Parameters:content – The object to test. Returns:True for an object native to the output representation, False otherwise.

element(name, children, attributes)

Creates an element representation.

Parameters:

• name (Unicode string) – The name of the element to create.
• children (collections.deque) – The children to add to the element to create. This contains only objects native to the output representation.
• attributes (dict) – The mapping of attributes of the element to create. Keys and values are Unicode strings.

Returns:

The element representation created.

text(content)

Creates a text node representation.

Parameters:content (Unicode string) – The text. Returns:The created text representation.

comment(content)

Creates a comment representation.

Parameters:content (Unicode string) – The content of the comment. Returns:The created comment representation.

processing_instruction(target, content)

Creates a processing instruction representation.

Parameters:

• target (Unicode string) – The target of the processing instruction.
• content (Unicode string) – The content of the processing instruction.

Returns:

The created processing instruction representation.

document(doctype_name, doctype_publicid, doctype_systemid, children, omit_xml_declaration, encoding)

Creates a XML document representation.

Parameters:

• doctype_name (Unicode string) – The document element name.
• doctype_publicid (Unicode string) – The document type system ID.
• doctype_systemid (Unicode string) – The document type system ID.
• children (collections.deque) – The root nodes of the document to create. This contains only objects are native to the output representation.
• omit_xml_declaration (bool()) – If True the XML declaration is omitted.

Returns:

The created document representation.

class ecoxipy.XMLWellFormednessException

Indicates XML is not well-formed.

This is used by ecoxipy.string_output.StringOutput and ecoxipy.pyxom.