Customising Serialization
There are various scenarios whereby you may want to have more control over the structure (particularly in XML) that is generated when serializing an object, and thus understanding how to deserialize JSON or XML back to an object.
This library provides a number of meta methods that you can override in your Python classes to achieve this.
Property Name Mappings
You can directly control mapping of property names for properties in a Class by adding the decorators
serializable.json_name() or serializable.xml_name().
For example, you might have a property called isbn in your class, but when serialized to JSON it should be called isbn_number.
To implement this mapping, you would alter your class as follows adding the serializable.json_name()
decorator to the isbn property:
@serializable.serializable_class
class Book:
def __init__(self, title: str, isbn: str, publish_date: date, authors: Iterable[str],
...
@property
@serializable.json_name('isbn_number')
def isbn(self) -> str:
return self._isbn
Excluding Property from Serialization
Properties can be ignored during deserialization by including them in the serializable.serializable_class()
annotation as per the following example.
A typical use case for this might be where a JSON schema is referenced, but this is not part of the constructor for the class you are deserializing to.
@serializable.serializable_class(ignore_during_deserialization=['$schema'])
class Book:
...
Handling None Values
By default, None values will lead to a Property being excluded from the serialization process to keep the output
as concise as possible. There are many cases (and schemas) where this is however not the required behaviour.
You can force a Property to be serialized even when the value is None by annotating as follows:
@serializable.include_none
def email(self) -> Optional[str]:
return self._email
Customised Property Serialization
This feature allows you to handle, for example, serialization of datetime.date Python objects to and from
strings.
Depending on your use case, the string format could vary, and thus this library makes no assumptions. We have provided an some example helpers for (de-)serializing dates and datetimes.
To define a custom serializer for a property, add the serializable.type_mapping() decorator to the property.
For example, to have a property named created be use the serializable.helpers.Iso8601Date helper you
would add the following method to your class:
@serializable.serializable_class
class Book:
def __init__(self, title: str, isbn: str, publish_date: date, authors: Iterable[str],
...
@property
@serializable.type_mapping(Iso8601Date)
def publish_date(self) -> date:
return self._publish_date
Writing Custom Property Serializers
You can write your own custom property serializer. The only requirements are that it must extend
serializable.helpers.BaseHelper and therefore implement the serialize() and deserialize() class methods.
For examples, see serializable.helpers.
Serializing Lists & Sets
Particularly in XML, there are many ways that properties which return Lists or Sets could be represented. We can handle
this by adding the decorator serializable.xml_array() to the appropriate property in your class.
For example, given a Property that returns Set[Chapter], this could be serialized in one of a number of ways:
{
"chapters": [
{ /* chapter 1 here... */ },
{ /* chapter 2 here... */ },
// etc...
]
}
<chapters>
<chapter><!-- chapter 1 here... --></chapter>
<chapter><!-- chapter 2 here... --></chapter>
<!-- etc... -->
</chapters>
<chapter><!-- chapter 1 here... --></chapter>
<chapter><!-- chapter 2 here... --></chapter>
As we have only identified one possible structure for JSON at this time, the implementation of only affects XML (de-)serialization at this time.
For Example 2, you would add the following to your class:
@property
@serializable.xml_array(XmlArraySerializationType.NESTED, 'chapter')
def chapters(self) -> List[Chapter]:
return self._chapters
For Example 3, you would add the following to your class:
@property
@serializable.xml_array(XmlArraySerializationType.FLAT, 'chapter')
def chapters(self) -> List[Chapter]:
return self._chapters
Further examples are available in our unit tests.
Serialization Views
Many object models can be serialized to and from multiple versions of a schema or different schemas. In
py-serialization we refer to these as Views.
By default all Properties will be included in the serialization process, but this can be customised based on the View.
Defining Views
A View is a class that extends serializable.ViewType and you should create classes as required in your
implementation.
For example:
from serializable import ViewType
class SchemaVersion1(ViewType):
pass
Property Inclusion
Properties can be annotated with the Views for which they should be included.
For example:
@property
@serializable.view(SchemaVersion1)
def address(self) -> Optional[str]:
return self._address
Handling None Values
Further to the above, you can vary the None value per View as follows:
@property
@serializable.include_none(SchemaVersion2)
@serializable.include_none(SchemaVersion3, "RUBBISH")
def email(self) -> Optional[str]:
return self._email
The above example will result in None when serializing with the View SchemaVersion2, but the value RUBBISH
when serializing to the View SchemaVersion3 when email is not set.
Serializing For a View
To serialized for a specific View, include the View when you perform the serialisation.
ThePhoenixProject.as_json(view_=SchemaVersion1)
ThePhoenixProject.as_xml(view_=SchemaVersion1)
XML Element Ordering
Some XML schemas utilise sequence which requires elements to be in a prescribed order.
You can control the order properties are serialized to elements in XML by utilising the
serializable.xml_sequence() decorator. The default sort order applied to properties is 100 (where lower is
earlier in the sequence).
In the example below, the isbn property will be output first.
@property
@serializable.xml_sequence(1)
def isbn(self) -> str:
return self._isbn