API Documentation

XmlModels is based on Django database models in terms of functionality and interface.

Manager

class xml_models.xml_models.ModelManager(model, finders)

Handles what can be queried for, and acts as the entry point for querying.

The API and usage is intended to be familiar to Django users however it does not support the complete Django ModelManager API.

all(**kw)

Get all models.

Example: 
Model.objects.all()

How the actual HTTP request is handled is determined by Finders.

Parameters:kw – optional key value pairs of field name and value
Returns:lazy query
count()

Get a count

Returns:int
filter(**kw)

Filter models by key-value pairs.

Example: 
Model.objects.filter(attr1=value1,attr2=value2)

How the actual HTTP request is handled is determined by Finders.

Parameters:kw – key value pairs of field name and value
Returns:lazy query
filter_custom(url)

Set a URL to be called when querying

Parameters:url – full URL
Returns:lazy query
get(**kw)

Get a single object.

This can be called directly with key-value pairs or after setting some filters

Parameters:kw –
Returns:

Model

class xml_models.xml_models.Model(xml=None, dom=None)

A model is a representation of the XML source, consisting of a number of Fields. It can be constructed with either an xml string, or an etree.Element.

Example: 
class Person(xml_models.Model):
    namespace="urn:my.default.namespace"
    name = xml_models.CharField(xpath"/Person/@Name", default="John")
    nicknames = xml_models.CollectionField(CharField, xpath="/Person/Nicknames/Name")
    addresses = xml_models.CollectionField(Address, xpath="/Person/Addresses/Address")
    date_of_birth = xml_models.DateField(xpath="/Person/@DateOfBirth", date_format="%d-%m-%Y")

If you define Finders on your model you will also be able to retreive models from an API endpoint using a familiar Django-esque object manager style of access with chainable filtering etc.

to_tree()

etree.Element representation of Model

Return type:lxml.etree.Element
to_xml(pretty=False)

XML representation of Model

Return type:string
validate_on_load()

Perform validation when the model is instantiated.

Override on your model to perform validation when the XML data is first passed in.

Note

You will need to raise appropriate exceptions as no checking of the return value occurs

Fields

class xml_models.xml_models.BaseField(**kw)

Base class for Fields. Should not be used directly

class xml_models.xml_models.CharField(**kw)

Returns the single value found by the xpath expression, as a string

parse(xml, namespace)
Parameters:
  • xml – the etree.Element to search in
  • namespace – not used yet
Return type:

string
class xml_models.xml_models.IntField(**kw)

Returns the single value found by the xpath expression, as an int

parse(xml, namespace)
Parameters:
  • xml – the etree.Element to search in
  • namespace – not used yet
Return type:

DateTime, may be timezone aware or naive
class xml_models.xml_models.FloatField(**kw)

Returns the single value found by the xpath expression, as a float

parse(xml, namespace)
Parameters:
  • xml – the etree.Element to search in
  • namespace – not used yet
Return type:

float
class xml_models.xml_models.DateField(date_format=None, **kw)

Returns the single value found by the xpath expression, as a datetime.

By default, expects dates that match the ISO8601 date format. If a date_format keyword arg is supplied, that will be used instead. date_format should conform to strptime formatting options.

If the XML contains UTC offsets then a timezone aware datetime object will be returned.

parse(xml, namespace)
Parameters:
  • xml – the etree.Element to search in
  • namespace – not used yet
Return type:

DateTime, may be timezone aware or naive
class xml_models.xml_models.OneToOneField(field_type, **kw)

Returns a subclass of Model from the xpath expression.

parse(xml, namespace)
Parameters:
  • xml – the etree.Element to search in
  • namespace – not used yet
Return type:

as defined by self.field_type
class xml_models.xml_models.CollectionField(field_type, order_by=None, **kw)

Returns a collection found by the xpath expression.

Requires a field_type to be supplied, which can either be a field type, e.g. IntField, which returns a collection ints, or it can be a Model type e.g. Person may contain a collection of Address objects.

parse(xml, namespace)

Find all nodes matching the xpath expression and create objects from each the matched node.

If order_by has been defined then the resulting list will be ordered.

Parameters:
  • xml – the etree.Element to search in
  • namespace – not used yet
Return type:

as defined by self.field_type