Developer Interface

paxb is a library that provides an API for mapping between XML documents and Python objects.

paxb library implements the following functionality:

  • Deserialize XML documents to Python objects
  • Validate deserialized data
  • Access and update Python object fields
  • Serialize Python objects to XML documents

paxb provides an efficient way of mapping between an XML document and a Python object. Using paxb developers can write less boilerplate code emphasizing on application business logic.

Since paxb based on attrs library paxb and attrs API can be mixed together.

Binding

paxb.attribute(name=None, **kwargs)

The Function maps a class field to an XML attribute. The field name is used as a default attribute name. The default name can be altered using the name argument.

Parameters:
  • name (str) – attribute name. If None field name will be used
  • kwargs – arguments that will be passed to attr.ib()
paxb.field(name=None, ns=None, ns_map=None, idx=None, **kwargs)

The Function maps a class field to an XML element. The field name is used as a default element name. The default name can be altered using name argument. The ns argument defines the namespace of the element.

Internally the decorator adds some metainformation to attr.ib.metadata.

Parameters:
  • name (str) – element name. If None field name will be used
  • ns (str) – element namespace. If None the namespace is inherited from the containing model
  • ns_map (dict) – mapping from a namespace prefix to a full name.
  • idx (int) – element index in the xml document. If None 1 is used
  • kwargs – arguments that will be passed to attr.ib()
paxb.nested(cls, name=None, ns=None, ns_map=None, idx=None, **kwargs)

The Function maps a class to an XML element. nested is used when a paxb.model() decorated class contains another one as a field.

Parameters:
  • cls – nested object class. cls must be an instance of paxb.model() decorated class
  • name (str) – element name. If None model decorator name attribute will be used
  • ns (str) – element namespace. If None model decorator ns attribute will be used
  • ns_map (dict) – mapping from a namespace prefix to a full name. It is applied to the current model and it’s elements and all nested models
  • idx (int) – element index in the xml document. If None 1 is used
  • kwargs – arguments that will be passed to attr.ib()
paxb.as_list(wrapped)

The Function maps a class list field to an XML element list. Wrapped element can be field or nested model.

Parameters:wrapped – list element type
paxb.wrapper(path, wrapped, ns=None, ns_map=None, idx=None)

The Function is used to map a class field to an XML element that is contained by a subelement.

Parameters:
  • path (str) – full path to the wrapped element. Element names are separated by slashes
  • wrapped – a wrapped element
  • ns (str) – element namespace. If None the namespace is inherited from the containing model
  • ns_map (dict) – mapping from a namespace prefix to a full name. It is applied to the current model and it’s elements and all nested models
  • idx (int) – element index in the xml document. If None 1 is used
paxb.attr

Alias for paxb.attribute()

paxb.wrap

Alias for paxb.wrapper()

paxb.lst

Alias for paxb.as_list()

Serialization/Deserialization

paxb.from_xml(cls, xml, envelope=None, name=None, ns=None, ns_map=None, required=True)

Deserializes xml string to object of cls type. cls must be a paxb.model() decorated class.

Parameters:
  • cls – class the deserialized object is instance of
  • xml (str or xml.etree.ElementTree.ElementTree) – xml string or xml tree to deserialize the object from
  • envelope (str) – root tag where the serializing object will be looked for
  • name (str) – name of the serialized object element. If None model decorator name argument will be used
  • ns (str) – namespace of the serialized object element. If None model decorator ns argument will be used
  • ns_map (dict) – mapping from a namespace prefix to a full name
  • required (bool) – is the serialized object element required. If element not found and required is True paxb.exceptions.DeserializationError will be raised otherwise None is returned
Returns:

deserialized object
paxb.to_xml(obj, envelope=None, name=None, ns=None, ns_map=None, encoder=default_encoder, **kwargs)

Serializes a paxb model object to an xml string. Object must be an instance of a paxb.model() decorated class.

Parameters:
  • obj – object to be serialized
  • envelope (str) – root tag name the serialized object element will be added inside. If None object element will be a root
  • name (str) – name of the serialized object element. If None model decorator name argument will be used
  • ns (str) – namespace of the serialized object element. If None model decorator ns argument will be used
  • ns_map (dict) – mapping from a namespace prefix to a full name.
  • encoder – value encoder. If None paxb.encoder.encode() is used
  • kwargs – arguments that will be passed to xml.etree.ElementTree.tostring() method
Returns:

serialized object xml string
Return type:

bytes or str
paxb.encoder.encode(value)

Default paxb value encoder. Encodes attributes or element text data during serialization. Supports str, bytes, datetime.date and datetime.datetime types.

Parameters:value – value to be encoded
Returns:encoded value string
Return type:str

Exceptions

Package errors.

exception paxb.exceptions.BaseError

Base package exception. All package exception are inherited from it.

exception paxb.exceptions.DeserializationError

Deserialization error. Raised when any deserialization error occurs.

exception paxb.exceptions.SerializationError

Serialization error. Raised when any serialization error occurs.