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.
Cereal is available on PyPI:
pip install pycerealor
pipenv install pycerealIf 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"
}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.
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"
}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"
}
}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"
}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"
}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"
}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).
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)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
}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
}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.
You may be wondering "What about deserialization?" Well, I had no need for it, so I didn't build it. Contributions are welcome, though!