Cereal

Serialize objects, dicts, and Django models to JSON with ease.

I occasionally need to make very small APIs, maybe just an endpoint or two to provide a bit of data to a client. It always seems like overkill to use Django REST framework when a simple View will do. Unfortunately, the DRF serializer is really good and hand coding an object-to-JSON map can be fragile and gross. Cereal was created to be that trusty serializer when that's all you need.

Installation

Cereal is available on PyPI:

pip install pycereal

or

pipenv install pycereal

Serializers

Fields

If you've ever used Django's ModelForms, Cereal should seem fairly familiar to you. A Serializer defines a set of attributes (Fields) that will be… serialized… into JSON.

import cereal

class ArticleSerializer(cereal.Serializer):
    title = cereal.Field()

data = {
    'id': 1,
    'title': 'An Important Headline',
}

ArticleSerializer().serialize(data)

This will result in the JSON object:

{
    "title": "An Important Headline"
}

Customizing fields

Sometimes there's a need to transform a value before it is converted to JSON. Cereal provides an opportunity to hook into serialization by adding methods named with the serialize_<field> format. The method will receive the data structure that is being serialized as the sole argument.

import cereal

class ArticleSerializer(cereal.Serializer):
    title = cereal.Field()

    def serialize_title(self, obj):
        return obj['title'].upper()

data = {
    'id': 1,
    'title': 'An Important Headline',
}

ArticleSerializer().serialize(data)

Which will generate:

{
    "title": "AN IMPORTANT HEADLINE"
}

The field methods can also be used to create completely new values.

import cereal

class AuthorSerializer(cereal.Serializer):
    full_name = cereal.Field()

    def serialize_full_name(self, obj):
        return f"{obj['first_name']} {obj['last_name']}"

data = {
    'first_name': 'Corey',
    'last_name': 'Spaceman',
}

AuthorSerializer().serialize(data)

The generated JSON:

{
    "full_name": "Corey Spaceman"
}

The JSON only includes the custom full_name Field, which is computed using the serialize_full_name method, and not the first_name or last_name attributes. Of course, you can include all of the attributes too by defining them as Fields as well.

Serializing objects

The examples so far have involved serializing a dict to JSON, but the json module already does this, so what's the point? Cereal handles objects the exact same way as it does dicts.

import cereal

class Article:
    def __init__(self, _id, title):
        self.id = _id
        self.title = title

class ArticleSerializer(cereal.Serializer):
    title = cereal.Field()

obj = Article(1, 'An Important Headline')
ArticleSerializer().serialize(obj)

The resulting JSON shouldn't be much of a surprise.

{
    "title": "An Important Headline"
}

Nested attributes

The world is an imperfect place and not all of your data will be in a simple, flat structure. SerializerField can be used to attach another serializer to handle a nested data structure.

import cereal

class UserSerializer(cereal.Serializer):
    name = cereal.Field()

class ArticleSerializer(cereal.Serializer):
    title = cereal.Field()
    author = cereal.SerializerField(UserSerializer)

data = {
    'id': 1,
    'title': 'An Important Headline',
    'author': {
        'id': 2,
        'name': 'Corey',
    }
}

ArticleSerializer().serialize(data)

{
    "title": "An Important Headline",
    "author": {
        "name": "Corey"
    }
}

Dates and datetimes

If you've spent much time with the json module, you're probably quite familiar with date serialization errors. JSON does not have native support for dates, so they have to be transformed into string values, but json doesn't do this automatically. Cereal has built-in support for dates and datetimes, generating ISO 8601-formatted strings that will be used as the value.

import datetime
import cereal

class EventSerializer(cereal.Serializer):
    timestamp = cereal.Field()

data = {
    'timestamp': datetime.datetime(2018, 3, 8, 11, 57, 23, 129307)
}

EventSerializer().serialize(data)

{
    "timestamp": "2018-03-08T11:57:23.129307"
}

Renaming Fields

Sometimes all you want to do is rename a field, not change the value. The Field object takes an optional from_attr parameter that can override the attribute from which the value is obtained.

import cereal

class Author:
    def __init__(self, first_name):
        self.first_name = first_name

class AuthorSerializer(cereal.Serializer):
    firstName = cereal.Field(from_attr='first_name')

obj = Author('Scarlett')
AuthorSerializer().serialize(obj)

The resulting JSON shouldn't be much of a surprise.

{
    "firstName": "Scarlett"
}

Custom type handlers

As with dates, other data types outside of what is natively supported by JSON need to be converted to one of the native types during serialization. Cereal allows you to define handlers for additional data types to convert to a valid JSON format. The handler is a callable that receives the value and returns a value corresponding to a native JSON type.

import uuid
import cereal

def uuid_handler(u):
    return u.hex

class UUIDSerializer(cereal.Serializer):
    id = cereal.Field()

ser = UUIDSerializer()
ser.add_handler(uuid.UUID, uuid_handler)
ser.serialize({'id': uuid.uuid4()})

You guessed it, the JSON:

{
    "id": "45ebb187dbc240cabb07b775f63efd6f"
}

Single value vs. list of values

When serializing an attribute, the content can either be a single value or an array of values. The corresponding JSON will likewise be either a single value or an array of values. All of the values of the array will be transformed the same way an individual value would be, either through the default Field behavior, using the custom serialization method, the default SerializerField behavior, or a custom type handler. To be safe, just make sure all items in the array are of the same type and that type would serialize correctly as a single value.

Similarly passing a list or tuple of objects to the serializer will return the serialized versions of them as a JSON array. All of the objects must be of the same type (or work with the serializer).

Serialize to a dict instead of JSON

Cereal first converts an object to a dict before converting to JSON. If you would like this dict instead of a string of JSON, pass raw=True to the serializer.

serializer.serialize(obj, raw=True)

Special Fields

Constants

The ConstantField allows you to insert a new, constant value into the JSON.

import cereal

class HumanSerializer(cereal.Serializer):
    name = cereal.Field()
    wants_tacos = cereal.ConstantField(True)

data = {
    'name': 'Corey Spaceman',
}

HumanSerializer().serialize(data)

{
    "name": "Corey Spaceman",
    "wants_tacos": true
}

Iterators

The IteratorField allows you to define a generator, use a list, or pass any type of iterable that will be used to generate values. Each serialized object will pull a new value from the iterator. If the iterator is exhausted, None will be used.

from itertools import count
import cereal

class ThingSerializer(cereal.Serializer):
    id = cereal.Field()
    offset = cereal.IteratorField(count())

ser = ThingSerializer()
ser.serialize({'id': 1})
ser.serialize({'id': 2})

{
    "id": 1,
    "offset": 0
}
{
    "id": 2,
    "offset": 1
}

Django Model Serialization

While Cereal is usable in any Python project, I really made it to be used with Django projects. So, given my previous mention of being inspired by Django ModelForms, Cereal allows you to define a model that automatically defines the fields that will be serialized.

import cereal
from django.db import models

class Post(models.Model):
    title = models.CharField(max_length=128)

class PostSerializer(cereal.Serializer):
    exclude = ('id',)

    class Meta:
        model = Post

post = Post.objects.create(title='Breaking News')
PostSerializer().serialize(post)

{
    "title": "Breaking News"
}

In this example, we're inheriting the fields of the Post model, but excluding the id.

Beyond incorporating the fields from the model, the Serializer functions the same as any other non-model Serializer. You can define additional Fields and custom field serializer methods that modify both model fields and any others.

Deserialization

You may be wondering "What about deserialization?" Well, I had no need for it, so I didn't build it. Contributions are welcome, though!