Skip to content

Latest commit

 

History

History
149 lines (110 loc) · 4.35 KB

xmlmap.rst

File metadata and controls

149 lines (110 loc) · 4.35 KB
Raw

eulxml.xmlmap -- Map XML to Python objects

eulxml.xmlmap

eulxml.xmlmap makes it easier to map XML to Python objects. The Python DOM does some of this, of course, but sometimes it's prettier to wrap an XML node in a typed Python object and assign attributes on that object to reference subnodes by XPath expressions. This module provides that functionality.

XmlObject Instances

Encoded Archive Description (EAD) XmlObject <xmlmap/ead> Dublin Core XmlObject <xmlmap/dc> Collaborative Electronic Records Project (CERP) XmlObject <xmlmap/cerp> Metadata Object Description Schema (MODS) XmlObject <xmlmap/mods> Preservation Metadata Implementation Strategies (PREMIS) XmlObjects <xmlmap/premis>

General Usage

Suppose we have an XML object that looks something like this:

<foo>
  <bar>
    <baz>42</baz>
  </bar>
  <bar>
    <baz>13</baz>
  </bar>
  <qux>A</qux>
  <qux>B</qux>
</foo>

For this example, we want to access the value of the first <baz> as a Python integer and the second <baz> as a string value. We also want to access all of them (there may be lots on another <foo>) as a big list of integers. We can create an object to map these fields like this:

from eulxml import xmlmap

class Foo(xmlmap.XmlObject):
    first_baz = xmlmap.IntegerField('bar[1]/baz')
    second_baz = xmlmap.StringField('bar[2]/baz')
    qux = xmlmap.StringListField('qux')

first_baz, second_baz, and all_baz here are attributes of the Foo object. We can access them in later code like this:

>>> foo = xmlmap.load_xmlobject_from_file(foo_path, xmlclass=Foo)
>>> foo.first_baz
42
>>> foo.second_baz
'13'
>>> foo.qux
['A', 'B']
>>> foo.first_baz=5
>>> foo.qux.append('C')
>>> foo.qux[0] = 'Q'
>>> print foo.serialize(pretty=True)
<foo>
  <bar>
    <baz>5</baz>
  </bar>
  <bar>
    <baz>13</baz>
  </bar>
  <qux>Q</qux>
  <qux>B</qux>
<qux>C</qux></foo>

Concepts

~eulxml.xmlmap simplifies access to XML data in Python. Programs can define new ~eulxml.xmlmap.XmlObject subclasses representing a type of XML node with predictable structure. Members of these classes can be regular methods and values like in regular Python classes, but they can also be special field <xmlmap-field> objects that associate XPath expressions with Python data elements. When code accesses these fields on the object, the code evaluates the associated XPath expression and converts the data to a Python value.

XmlObject

Most programs will use ~eulxml.xmlmap by defining a subclass of XmlObject containing field <xmlmap-field> members.

XmlObject([node[, context]])

_fields

A dictionary mapping field names to field <xmlmap-field> members. This dictionary includes all of the fields defined on the class as well as those inherited from its parents.

~eulxml.xmlmap.core.XmlObjectType

eulxml.xmlmap.core.XmlObjectType

Field types

There are several predefined field types. All of them evaluate XPath expressions and map the resultant XML nodes to Python types. They differ primarily in how they map those XML nodes to Python objects as well as in whether they expect their XPath expression to match a single XML node or a whole collection of them.

Field objects are typically created as part of an XmlObject definition and accessed with standard Python object attribute syntax. If a Foo class defines a bar attribute as an ~eulxml.xmlmap field object, then an object will reference it simply as foo.bar.

eulxml.xmlmap.fields

Other facilities

eulxml.xmlmap.load_xmlobject_from_string

eulxml.xmlmap.load_xmlobject_from_file

eulxml.xmlmap.parseString

eulxml.xmlmap.parseUri

eulxml.xmlmap.loadSchema(uri, base_uri=None)