What is Elements

Elements is a Python library that provides simple parsing from XML or JSON to Python objects and back. It uses the well known ElementTree API to parse XML or JSON into Python objects. ElementTrees are very nice for parsing XML, but sometimes you want something even closer to Python. You want the XML to "magically" fill out your Python objects. This is what Elements does for you.

However, Elements does not work well for all kinds of XML documents. It's a compromise. It's very good for parsing XML over HTTP based protocols such as Atom, but may not work well for you when the ordering of the elements is significant such as for HTML or Apple Property Lists (PList). At first you might get the feeling of over-engineering when looking at Elements, but once your classes are defined, you will feel and enjoy the power of the this library.

History

Most of the idea, design and code has been taken from the Atom parser in the gdata-python-client library. I really liked the idea and wanted to make it easy to use with other applications and for other XML formats as well.

A number of changes have been made:

• Strings are stored as unicode internally
• Parse into basic types such as int, str and unicode without having to declare separate classes. This makes things less "chatty" when declaring classes
• Parse into lists of basic types
• Parse date strings into datetime objects and back
• Parse into dictionaries using a given subelement as key
• Removed support for extension elements and attributes. You should just use subclassing instead.
• Support XML without any namepace declarations
• Support for element ordering. Prints out elements in the same order as they are declared
• Pretty printing. Elements prints using default namespaces, so you don't get the <ns0:Tag xmlns:ns0="ns_uri"> style output from ElementTree.
• Added JsonElement. Converts to and from JSON (new).

Goals

• Stay compatible with the gdata-python-client
• Tighter integration with the ElementTree parser to get one-pass parsing if possible
• See if it's possible to preserve some of the element ordering (fixed)

Source

To browse the Elements library source code, visit the Source tab.

Example

A simple example. Lets say you want to parse the following XML document:

<Example version="1.0">
    <Name>Dag Brattli</Name>
    <Age>39</Age>
    <Hacker/>
</Example>

With Elements you have to declare a Python class for storing the information you are interested in. Unspecified elements and attributes will be ignored by the parser.

from elements import Element

class Example(Element):
    _tag = 'Example'
    _children = Element._children.copy()
    _attributes = Element._attributes.copy()

    _children['Hacker'] = ('hacker', bool)
    _children['Name'] = ('name', unicode)
    _children['Age'] = ('age', int)
    
    def __init__(self, version=None, name=None, age=None):
        self.version = version
        self.hacker = None
        self.name = None
        self.age = age
        
        self.text = None

Now you are ready for some action:

>>> e = Example()
>>> e.from_string(example) # The XML doc above
>>> print e.name
Dag Brattli
>>> print e.age
39
>>> print e.hacker
True

Nice! There are many other and more advanced features, so check out the documentation for details.

Enjoy

Dag Brattli