django-xml is a python module which provides an abstraction to lxml's XPath and XSLT functionality in a manner resembling django database models.

• Installation
• Example
• Advanced Example
• XmlModel Meta options
  • namespaces
  • parser_opts
  • extension_ns_uri
• @lxml_extension reference
  • ns_uri
  • name
• XPathField options
  • xpath_query
  • required
  • extra_namespaces
  • extensions
• XPathSingleNodeField options
  • ignore_extra_nodes
• XsltField options
  • xslt_file, xslt_string
  • parser
  • extensions
• XmlModel field reference

To install the latest stable release of django-xml, use pip or easy_install

pip install django-xml
easy_install django-xml

For the latest development version, install from source with pip:

pip install -e git+git://github.com/theatlantic/django-xml#egg=django-xml

If the source is already checked out, install via setuptools:

python setup.py develop

import math
from djxml import xmlmodels

class NumbersExample(xmlmodels.XmlModel):

    class Meta:
        extension_ns_uri = "urn:local:number-functions"
        namespaces = {"fn": extension_ns_uri,}

    all_numbers  = xmlmodels.XPathIntegerListField("//num")
    even_numbers = xmlmodels.XPathIntegerListField("//num[fn:is_even(.)]")
    sqrt_numbers = xmlmodels.XPathFloatListField("fn:sqrt(//num)")

    @xmlmodels.lxml_extension
    def is_even(self, context, number_nodes):
        numbers = [getattr(n, 'text', n) for n in number_nodes]
        return all([bool(int(num) % 2 == 0) for num in numbers])

    @xmlmodels.lxml_extension
    def sqrt(self, context, number_nodes):
        sqrts = []
        for number_node in number_nodes:
            number = getattr(number_node, 'text', number_node)
            sqrts.append(repr(math.sqrt(int(number))))
        return sqrts


def main():
    numbers_xml = u"""
    <numbers>
        <num>1</num>
        <num>2</num>
        <num>3</num>
        <num>4</num>
        <num>5</num>
        <num>6</num>
        <num>7</num>
    </numbers>"""

    example = NumbersExample.create_from_string(numbers_xml)

    print "all_numbers  = %r" % example.all_numbers
    print "even_numbers = %r" % example.even_numbers
    print "sqrt_numbers = [%s]" % ', '.join(['%.3f' % n for n in example.sqrt_numbers])
    # all_numbers  = [1, 2, 3, 4, 5, 6, 7]
    # even_numbers = [2, 4, 6]
    # sqrt_numbers = [1.000, 1.414, 1.732, 2.000, 2.236, 2.449, 2.646]

if __name__ == '__main__':
    main()

An example of django-xml usage which includes XsltField and @lxml_extension methods can be found here.

Metadata for an XmlModel is passed as attributes of an internal class named Meta. Listed below are the options that can be set on the Meta class.

A dict of prefix / namespace URIs key-value pairs that is passed to lxml.etree.XPathEvaluator() for all XPath fields on the model.

A dict of keyword arguments to pass to lxml.etree.XMLParser()

The default namespace URI to use for extension functions created using the @lxml_extension decorator.

def lxml_extension(method=None, ns_uri=None, name=None)

The @lxml_extension decorator is for registering model methods as lxml extensions which can be used in XPathFields and XsltFields. All keyword arguments to it are optional.

The namespace uri for the function. If used in an XPathField, this uri will need to be one of the values in the namespaces attribute of the XmlModel's internal Meta class. If used in an XSLT, the namespace will need to be defined in the xslt file or string.

Defaults to the value of the extension_ns_uri attribute of the XmlModel's internal Meta class, if defined. If neither the extension_ns_uri attribute of XmlModel.Meta is set, nor is the ns_uri keyword argument passed, an ExtensionNamespaceException will be thrown.

The name of the function to register. Defaults to the method's name.

The following arguments are available to all XPath field types. All but the first are optional.

The XPath query string to perform on the document. Required.

If True, a DoesNotExist exception will be thrown if no nodes match the XPath query for the field. Defaults to True.

A dict of extra prefix/uri namespace pairs to pass to lxml.etree.XPathEvaluator().

Extra extensions to pass on to lxml.etree.XSLT. See the lxml documentation for details on how to form the extensions keyword argument.

If True return only the first node of the XPath evaluation result, even if it evaluates to more than one node. If False, accessing an xpath field which evaluates to more than one node will throw a MultipleObjectsExist exception Defaults to False.

To return the full list of nodes, Use an XPathListField

The first positional argument to XsltField is the path to an xslt file. Alternatively, the xslt can be passed as a string using the xslt_string keyword argument. It is required to specify one of these fields.

An instance of lxml.etree.XMLParser to override the one created by the XmlModel class. To override parsing options for the entire class, use the parser_opts attribute of the XmlModel internal Meta class.

Extra extensions to pass on to the constructor of lxml.etree.XSLT. See the lxml documentation for details on how to form the extensions keyword argument.

class XsltField(xslt_file=None, xslt_string=None, parser=None, extensions=None)

Field which abstracts the creation of lxml.etree.XSLT objects. This field's return type is a callable which accepts keyword arguments that are passed as parameters to the stylesheet.

class XPathField(xpath_query, required=False, extra_namespaces=None, extensions=None)

Base field for abstracting the retrieval of node results from the xpath evaluation of an xml etree.

class XPathField(xpath_query, required=False, extra_namespaces=None, extensions=None)

Base field for abstracting the retrieval of node results from the xpath evaluation of an xml etree.

class XPathListField(xpath_query, required=False, extra_namespaces=None, extensions=None)

Field which abstracts retrieving a list of nodes from the xpath evaluation of an xml etree.

class XPathSingleItemField(xpath_query, required=False, extra_namespaces=None,
                           extensions=None, ignore_extra_nodes=False)

Field which abstracts retrieving the first node result from the xpath evaluation of an xml etree.

class XPathTextField(XPathSingleNodeField)

Returns a unicode value when accessed.

class XPathIntegerField(XPathSingleNodeField)

Returns an int value when accessed.

class XPathFloatField(XPathSingleNodeField)

Returns a float value when accessed.

class XPathDateTimeField(XPathSingleNodeField)

Returns a datetime.datetime value when accessed.

class XPathTextListField(XPathListField)

Returns a list of unicode values when accessed.

class XPathIntegerListField(XPathListField)

Returns a list of int values when accessed.

class XPathFloatListField(XPathListField)

Returns a list of float values when accessed.

class XPathDateTimeListField(XPathListField)

Returns a list of datetime.datetime values when accessed.