Skip to main content

Serialize/deserialize Python dataclasses to various other data formats

Project description


dataclasses_serialization provides serializers/deserializers for transforming between Python dataclasses, and JSON and BSON objects.

Basic Usage

Suppose we have the following dataclass:

from dataclasses import dataclass

class InventoryItem:
    name: str
    unit_price: float
    quantity_on_hand: int

Then we may serialize/deserialize it to/from JSON by using JSONSerializer

>>> from dataclasses_serialization.json import JSONSerializer
>>> JSONSerializer.serialize(InventoryItem("Apple", 0.2, 20))
{'name': 'Apple', 'unit_price': 0.2, 'quantity_on_hand': 20}

>>> JSONSerializer.deserialize(InventoryItem, {'name': 'Apple', 'unit_price': 0.2, 'quantity_on_hand': 20})
InventoryItem(name='Apple', unit_price=0.2, quantity_on_hand=20)


As Mongo collections store objects as BSON, you can use BSONSerializer to dump dataclasses directly into Mongo.

from dataclasses_serialization.bson import BSONSerializer


item = BSONSerializer.deserialize(InventoryItem, collection.find_one())

Custom Serializers

To create a custom serializer, create an instance of dataclasses_serialization.serializer_base.Serializer:

from dataclasses_serialization.serializer_base import noop_serialization, noop_deserialization, dict_serialization, dict_deserialization, list_deserialization, Serializer

JSONSerializer = Serializer(
        dict: lambda dct: dict_serialization(dct, key_serialization_func=JSONSerializer.serialize, value_serialization_func=JSONSerializer.serialize),
        list: lambda lst: list(map(JSONSerializer.serialize, lst)),
        (str, int, float, bool, type(None)): noop_serialization
        dict: lambda cls, dct: dict_deserialization(cls, dct, key_deserialization_func=JSONSerializer.deserialize, value_deserialization_func=JSONSerializer.deserialize),
        list: lambda cls, lst: list_deserialization(cls, lst, deserialization_func=JSONSerializer.deserialize),
        (str, int, float, bool, type(None)): noop_deserialization



A collection of utilities to make it easier to create serializers.

  • isinstance(o, t), issubclass(cls, clsinfo)

    Extended versions of the builtin isinstance and issubclass, to treat dataclass as a superclass for dataclasses, and to be usable with supported typing types.

  • noop_serialization(obj), noop_deserialization(cls, obj)

    The trivial serialization/deserialization functions, which serialize by doing nothing.

  • dict_to_dataclass(cls, dct, deserialization_func=noop_deserialization)

    The inverse of dataclasses.asdict, which deserializes a dictionary dct to a dataclass cls, using deserialization_func to deserialize the fields of cls.

    Fields are deserialized using the type provided by the dataclass. So bound generic dataclasses may be deserialized, while unbound ones may not.

  • union_deserialization(type_, obj, deserialization_func=noop_deserialization)

    Deserialize a Union type_, by trying each type in turn, and returning the first that does not raise a DeserializationError.

    As Optionals are implemented as Unions, this function also works for them.

  • dict_serialization(obj, key_serialization_func=noop_serialization, value_serialization_func=noop_serialization), dict_deserialization(type_, obj, key_deserialization_func=noop_deserialization, value_deserialization_func=noop_deserialization)

    Serialize/deserialize a dictionary obj by applying the appropriate serialization/deserialization functions to keys and values.

  • list_deserialization(type_, obj, deserialization_func=noop_deserialization)

    Deserialize a list obj by applying the deserialization function to its values.

  • Serializer(serialization_functions, deserialization_functions)

    The general serialization class.

    Takes two dictionaries of serialization and deserialization functions, and defers to them appropriately when serializing/deserializing and object by the serialize and deserialize methods. Serializer functions take a single parameter, the object to be serialized, and returns a serialized version of it. Deserializer functions take two parameters, the desired type of the deserialized object, and the object to be deserialized.

    If an object's type cannot be found directly in the serialization/deserialization functions, the Serializer uses its closest ancestor - raising an error in case of ambiguity.

    By default dataclasses are serialized as though they are dicts. Similarly, dataclasses are deserialized using dict_to_dataclass, and Unions using union_deserialization, using itself as the nested deserialization function.

    Serialize a Python object with serializer.serialize(obj), and deserialize with serializer.deserialize(cls, serialized_obj).

    Register more serialization/deserialization functions with serializer.register_serializer(cls, func), serializer.register_deserializer(cls, func), and serializer.register(cls, serialization_func, deserialization_func). They can also be used as decorators like so:

    def int_serializer(obj):
    def int_deserializer(cls, obj):
  • SerializationError, DeserializationError

    Errors to be raised when serialization/deserialization fails, respectively.


  • JSONSerializer

    Serializer/deserializer between Python dataclasses and JSON objects.

    >>> JSONSerializer.serialize(InventoryItem("Apple", 0.2, 20))
    {'name': 'Apple', 'unit_price': 0.2, 'quantity_on_hand': 20}
    >>> JSONSerializer.deserialize(InventoryItem, {'name': 'Apple', 'unit_price': 0.2, 'quantity_on_hand': 20})
    InventoryItem(name='Apple', unit_price=0.2, quantity_on_hand=20)
  • JSONSerializerMixin

    Adds as_json and from_json methods to dataclasses when used as a mixin.

    class InventoryItem(JSONSerializerMixin):
    >>> InventoryItem("Apple", 0.2, 20).as_json()
    {'name': 'Apple', 'unit_price': 0.2, 'quantity_on_hand': 20}
    >>> InventoryItem.from_json({'name': 'Apple', 'unit_price': 0.2, 'quantity_on_hand': 20})
    InventoryItem(name='Apple', unit_price=0.2, quantity_on_hand=20)
  • JSONStrSerializer

    Serializer/deserializer between Python dataclasses and JSON strings.

    >>> JSONStrSerializer.serialize(InventoryItem("Apple", 0.2, 20))
    '{"name": "Apple", "unit_price": 0.2, "quantity_on_hand": 20}'
    >>> JSONStrSerializer.deserialize(InventoryItem, '{"name": "Apple", "unit_price": 0.2, "quantity_on_hand": 20}')
    InventoryItem(name='Apple', unit_price=0.2, quantity_on_hand=20)
  • JSONStrSerializerMixin

    Adds as_json_str and from_json_str methods to dataclasses when used as a mixin.

    class InventoryItem(JSONStrSerializerMixin):
    >>> InventoryItem("Apple", 0.2, 20).as_json_str()
    '{"name": "Apple", "unit_price": 0.2, "quantity_on_hand": 20}'
    >>> InventoryItem.from_json_str('{"name": "Apple", "unit_price": 0.2, "quantity_on_hand": 20}')
    InventoryItem(name='Apple', unit_price=0.2, quantity_on_hand=20)


  • BSONSerializer

    Serializer/deserializer between Python dataclasses and BSON objects.

    >>> BSONSerializer.serialize(InventoryItem("Apple", 0.2, 20))
    {'name': 'Apple', 'unit_price': 0.2, 'quantity_on_hand': 20}
    >>> BSONSerializer.deserialize(InventoryItem, {'name': 'Apple', 'unit_price': 0.2, 'quantity_on_hand': 20})
    InventoryItem(name='Apple', unit_price=0.2, quantity_on_hand=20)
  • BSONSerializerMixin

    Adds as_bson and from_bson methods to dataclasses when used as a mixin.

    class InventoryItem(BSONSerializerMixin):
    >>> InventoryItem("Apple", 0.2, 20).as_bson()
    {'name': 'Apple', 'unit_price': 0.2, 'quantity_on_hand': 20}
    >>> InventoryItem.from_bson({'name': 'Apple', 'unit_price': 0.2, 'quantity_on_hand': 20})
    InventoryItem(name='Apple', unit_price=0.2, quantity_on_hand=20)
  • BSONStrSerializer

    Serializer/deserializer between Python dataclasses and binary BSON strings.

  • BSONStrSerializerMixin

    Adds as_bson_str and from_bson_str methods to dataclasses when used as a mixin.

    class InventoryItem(BSONStrSerializerMixin):


Install and update using the standard Python package manager pip:

pip install dataclasses_serialization

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for dataclasses-serialization, version 1.3.1
Filename, size File type Python version Upload date Hashes
Filename, size dataclasses_serialization-1.3.1-py3-none-any.whl (12.8 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size dataclasses_serialization-1.3.1.tar.gz (9.9 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page