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:
-
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.