.. _deserialization:
Deserialization
===============
``paxb`` implements an API for deserializing an xml string to a python object.
To serialize an object just pass a class and an xml string to a :py:func:`paxb.from_xml` method:
.. doctest::
>>> import paxb as pb
>>>
>>> @pb.model
... class User:
... name = pb.attribute()
... surname = pb.attribute()
... email = pb.field()
... phone = pb.field()
...
>>> xml_str = 'alex@gmail.com+79123457323'
>>> pb.from_xml(User, xml_str)
User(name='Alex', surname='Ivanov', email='alex@gmail.com', phone='+79123457323')
By default :py:func:`paxb.from_xml` method deserializes an object from a root element in an xml tree, class name
is used as an element name, the element namespace is empty. The default behaviour can be altered
using :py:func:`paxb.from_xml` additional arguments. Look at the example:
.. doctest::
>>> import paxb as pb
>>>
>>> @pb.model
... class User:
... name = pb.attribute()
... surname = pb.attribute()
... email = pb.field()
... phone = pb.field()
...
>>> xml_str = 'alex@gmail.com+79123457323'
>>> pb.from_xml(User, xml_str, envelope='root', name='user', ns='test', ns_map={'test': 'http://www.test.org'}, required=True)
User(name='Alex', surname='Ivanov', email='alex@gmail.com', phone='+79123457323')
The ``required`` argument tells the deserializer to raise an exception if the element not found in the xml tree,
otherwise ``None`` will be returned (see :ref:`Errors `).
By default all fields deserialized as :py:class:`str` types. The default behaviour can be altered using a
``converter`` parameter. See :py:func:`attr.ib`.
.. doctest::
>>> import datetime
>>> import paxb as pb
>>>
>>> @pb.model
... class User:
... age = pb.attribute(converter=int)
... birthdate = pb.field(converter=datetime.date.fromisoformat)
...
>>> xml_str = '1993-08-21'
>>> pb.from_xml(User, xml_str)
User(age=26, birthdate=datetime.date(1993, 8, 21))
To deserialize an object from a json document use python :py:mod:`json` package:
.. doctest::
>>> import json
>>> import paxb as pb
>>>
>>> @pb.model
... class User:
... name = pb.attribute()
... surname = pb.attribute()
... email = pb.field()
... phone = pb.field()
...
>>> json_str = '{"name": "Alex", "surname": "Ivanov", "email": "alex@gmail.com", "phone": "+79123457323"}'
>>> User(**json.loads(json_str))
User(name='Alex', surname='Ivanov', email='alex@gmail.com', phone='+79123457323')