:mod:`eulxml.xmlmap` -- Map XML to Python objects
==================================================
.. module:: eulxml.xmlmap
:mod:`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.
:class:`XmlObject` Instances
----------------------------
.. toctree::
:maxdepth: 1
Encoded Archive Description (EAD) XmlObject
Dublin Core XmlObject
Collaborative Electronic Records Project (CERP) XmlObject
Metadata Object Description Schema (MODS) XmlObject
Preservation Metadata Implementation Strategies (PREMIS) XmlObjects
General Usage
-------------
Suppose we have an XML object that looks something like this:
.. code-block:: xml
42
13
A
B
For this example, we want to access the value of the first ```` as a
Python integer and the second ```` as a string value. We also want to
access all of them (there may be lots on another ````) 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')
:attr:`first_baz`, :attr:`second_baz`, and :attr:`all_baz` here are
attributes of the :class:`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)
5
13
Q
B
C
Concepts
--------
:mod:`~eulxml.xmlmap` simplifies access to XML data in Python. Programs
can define new :class:`~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 :ref:`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.
:class:`XmlObject`
------------------
Most programs will use :mod:`~eulxml.xmlmap` by defining a subclass of
:class:`XmlObject` containing :ref:`field ` members.
.. autoclass:: XmlObject([node[, context]])
:members:
.. attribute:: _fields
A dictionary mapping field names to :ref:`field `
members. This dictionary includes all of the fields defined on the
class as well as those inherited from its parents.
:class:`~eulxml.xmlmap.core.XmlObjectType`
-------------------------------------------
.. autoclass:: eulxml.xmlmap.core.XmlObjectType
:members:
.. _xmlmap-field:
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 :class:`XmlObject`
definition and accessed with standard Python object attribute syntax. If a
:class:`Foo` class defines a :attr:`bar` attribute as an
:mod:`~eulxml.xmlmap` field object, then an object will reference it simply
as ``foo.bar``.
.. automodule:: eulxml.xmlmap.fields
:members:
Other facilities
----------------
.. autofunction:: eulxml.xmlmap.load_xmlobject_from_string
.. autofunction:: eulxml.xmlmap.load_xmlobject_from_file
.. autofunction:: eulxml.xmlmap.parseString
.. autofunction:: eulxml.xmlmap.parseUri
.. autofunction:: eulxml.xmlmap.loadSchema(uri, base_uri=None)