Package: pycereal
CerealSerialize objects, dicts, andDjango modelsto 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.InstallationCereal is available onPyPI:pipinstallpycerealorpipenvinstallpycerealSerializersFieldsIf you've ever used Django'sModelForms, Cereal should seem fairly familiar to you. A Serializer defines a set of attributes (Fields) that will be… serialized… into JSON.importcerealclassArticleSerializer(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 fieldsSometimes 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 theserialize_<field>format. The method will receive the data structure that is being serialized as the sole argument.importcerealclassArticleSerializer(cereal.Serializer):title=cereal.Field()defserialize_title(self,obj):returnobj['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.importcerealclassAuthorSerializer(cereal.Serializer):full_name=cereal.Field()defserialize_full_name(self,obj):returnf"{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 customfull_nameField, which is computed using theserialize_full_namemethod, and not thefirst_nameorlast_nameattributes. Of course, you can include all of the attributes too by defining them as Fields as well.Serializing objectsThe examples so far have involved serializing a dict to JSON, but thejsonmodule already does this, so what's the point? Cereal handles objects the exact same way as it does dicts.importcerealclassArticle:def__init__(self,_id,title):self.id=_idself.title=titleclassArticleSerializer(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 attributesThe 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.importcerealclassUserSerializer(cereal.Serializer):name=cereal.Field()classArticleSerializer(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 datetimesIf you've spent much time with thejsonmodule, 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, butjsondoesn'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.importdatetimeimportcerealclassEventSerializer(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"}Custom type handlersAs 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.importuuidimportcerealdefuuid_handler(u):returnu.hexclassUUIDSerializer(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 valuesWhen 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.Special FieldsConstantsThe ConstantField allows you to insert a new, constant value into the JSON.importcerealclassHumanSerializer(cereal.Serializer):name=cereal.Field()wants_tacos=cereal.ConstantField(True)data={'name':'Corey Spaceman',}HumanSerializer().serialize(data){"name":"Corey Spaceman","wants_tacos":true}IteratorsThe 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,Nonewill be used.fromitertoolsimportcountimportcerealclassThingSerializer(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 SerializationWhile 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.importcerealfromdjango.dbimportmodelsclassPost(models.Model):title=models.CharField(max_length=128)classPostSerializer(cereal.Serializer):exclude=('id',)classMeta:model=Postpost=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 theid.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.DeserializationYou may be wondering "What about deserialization?" Well, I had no need for it, so I didn't build it. Contributions are welcome, though!