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.
As soon as 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:
-
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()
- cls – nested object class. cls must be an instance of
-
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
orxml.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 otherwiseNone
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 apaxb.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:
-
paxb.encoder.
encode
(value)¶ Default
paxb
value encoder. Encodes attributes or element text data during serialization. Supportsstr
,bytes
,datetime.date
anddatetime.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.