Getting Started

A simple example

Just to get started, this is an example of taking an XML representation of an Address that might be returned from a GET request to an external REST api.

<Address id="2">
  <street>Acacia Avenue</street>
  <postcode>IM6 66B</postcode>

class Address(xml_models.Model):
  number = xml_models.IntField(xpath="/Address/number")
  street = xml_models.CharField(xpath="/Address/street")
  city = xml_models.CharField(xpath="/Address/city")
  country = xml_models.CharField(xpath="/Address/country")
  postcode = xml_models.CharField(xpath="/Address/postcode")

This example would be used as follows:-

>>> print "address is %s, %s" % (address.number, address.street)
"22, Acacia Avenue"

XML Mapping options

The available field mappings are as follows

  • CharField(xpath="...", default="...") -- returns string data
  • IntField(xpath="...", default="...") -- returns integers
  • DateField(xpath="...", default="...", date_format="%Y-%m-%dT%H:%M:%S") -- returns a date from using the supplied date_format mask
  • FloatField(xpath="...", default="...") -- returns a floating point number
  • BoolField(xpath="...", default="...") -- returns a boolean
  • Collection(fieldtype, order_by=None, xpath="...", default="...") -- returns a collection of either one of the above types, or an xml_model.Model subclass

The first five fields are fairly self explanatory. The sixth field is where it gets interesting. This is what allows you to map collections of nested entities, such as:-

<Person id="112">
  <occupation>Code Geek</occupation>
    <contact type="telephone">
      <info>(555) 555-5555</info>
      <description>Cell phone, but no calls during work hours</description>
    <contact type="email">
      <description>Where possible, contact me by email</description>
    <contact type="telephone">
      <description>Toll free work number for during office hours.</description>

This can be mapped using a Person and a ContactInfo model:-

class Person(xml_models.Model):
  id = IntField(xpath="/Person/@id")
  firstName = CharField(xpath="/Person/firstName")
  lastName = CharField(xpath="/Person/lastName")
  contacts = Collection(ContactInfo, order_by="contact_type", xpath="/Person/contact-info/contact")

class ContactInfo(xml_models.Model):
  contact_type = CharField(xpath="/contact/@type")
  info = CharField(xpath="/contact/info")
  description = CharField(xpath="/contact/description", default="No description supplied")

This leads to the usage of a person as :-

>>> person.contacts[0].info

Querying the REST api

An external REST api will present a limited number of options for querying data. Because the different options do not have to follow any specific convention, the model must define what finders are available and what parameters they accept. This still attempts to follow a Django-esque approach

class Person(xml_models.Model:
    finders = { (firstName, lastName): "http://person/firstName/%s/lastName/%s",
                (id,): "http://person/%s"}

The above defines two query options. The following code exercises these options

>>> people = Person.objects.filter(firstName='Chris', lastName='Tarttelin')
>>> people.count()
>>> person = Person.objects.get(id=123)
>>> person.firstName

When using a filter, a collection of 0 or more results are expected. The expectation is that the results are within a single enclosing tag, such as:-

  <address> ...</address>

This would allow you to iterate over the results for models whose root tag is the
element. This pattern works for us at the moment, but we plan to support custom approaches in the future. The parser streams the results as they are pulled from the REST call so as to avoid upfront loading and potential memory issues.

Support for Namespaces

There is a primitive level of namespace support. By adding a namespace attribute to your model, all the xpaths will use this namespace, which allows the following to work

<address xmlns="">
  <street>Letsbe Avenue</street>

class Address(xml_models.Model):
  namespace = ""
  houseNumber = IntField(xpath="/address/houseNumber")
  street = CharField(xpath="/address/street")
  city = CharField(xpath="/address/city")

The namespace attribute assumes that all elements are within the same namespace. So far, nothing more complex has occurred, so we have not done anything extra. Because we version our REST apis, there is little benefit in using namespaces, so we tend not to.


In some applications, we only want to deal with a subset of the records returned because some are not valid in our circumstance. We have on load validation baked in, so when the model is constructed, it will be validated and an exception will be raised if validation fails.

def validate_on_load(self):
        if not self.street:
            raise XmlValidationError("An address without a street cannot be processed")

When iterating over a collection of addresses, if one doesn't have a street, an exception is thrown. This can then be caught and handled as appropriate.

Writing to the REST api

The file contains a rest client that supports PUTting and POSTing to a REST api. The xml_model does not provide anything to assist in this at this point. We haven't yet decided how best to handle PUTs etc, but the current favorite approach is to use a template to construct the XML, and then use the rest client to dispatch it. We will be creating patterns for this in the near future.