Serializer classes are capable of performing serialization and deserialization of data.

Serialization is the transformation of data in a native format (in our case Python data types) into a serialized format (e.g. text). For example, this could be transforming a native Python Datetime instance containing a date into a string.

Deserialization is the transformation of data in a serialized format (e.g. text) into a native format. For example, this could be transforming a string containing a date into a native Python Datetime instance.



Data serialization is done in the background when tapioca is executing the request. It will traverse any data structure passed to the data param of the request and convert Python data types into serialized types.

>>> reponse = cli.the_resource().post(data={'date':})

In this example, will be converted into a string formatted date just before the request is executed.


To deserialize data, you need to transform your client into an executor and then call a deserialization method from it:

>>> reponse = cli.the_resource().get()
>>> print(response.created_at())
<TapiocaClientExecutor object
>>> print(respose.created_at().to_datetime())
2015-10-25 22:34:51+00:00
>>> print(type(respose.created_at().to_datetime()))

Swapping the default serializer

Clients might have the default SimpleSerializer, some custom serializer designed by the wrapper creator, or even no serializer. Either way, you can swap it for one of your own even if you were not the developer of the library. For this, you only need to pass the desired serializer class during the client initialization:

from my_serializers import MyCustomSerializer

cli = MyServiceClient(


class SimpleSerializer

SimpleSerializer is a very basic and generic serializer. It is included by default in adapters unless explicitly removed. It supports serialization from Decimal and datetime and deserialization methods to those two types as well. Here is it’s full code:

class SimpleSerializer(BaseSerializer):

def to_datetime(self, value):
        return arrow.get(value).datetime

def to_decimal(self, value):
        return Decimal(value)

def serialize_decimal(self, data):
        return str(data)

def serialize_datetime(self, data):
        return arrow.get(data).isoformat()

As you can see, datetime values will be formatted to iso format.

Writing a custom serializer

To write a custom serializer, you just need to extend the BaseSerializer class and add the methods you want. But you can also extend from SimpleSerializer to inherit its functionalities.


To allow serialization of any desired data type, add a method to your serializer named using the following pattern: serialize_ + name_of_your_data_type_in_lower_case. For example:

class MyCustomDataType(object):
        message = ''

class MyCustomSerializer(SimpleSerializer):

        def serialize_mycustomdatatype(self, data):
                return data.message


Any method starting with to_ in your custom serializer class will be available for data deserialization. It also accepts key word arguments.

from tapioca.serializers import BaseSerializer

class MyCustomSerializer(BaseSerializer):

        def to_striped(self, value, **kwargs):
                return value.strip()

Here’s a usage example for it:

from my_serializers import MyCustomSerializer

cli = MyServiceClient(

response = cli.the_resource().get()

striped_data = response.the_data().to_striped()