Marshmallow schemas for Django REST framework.

django-rest-marshmallow provides an alternative serializer implementation to the built-in serializers, by using the python marshmallow library, but exposing the same API as REST framework's Serializer class.

• Python (3.6+)
• Django REST framework (3.8+)
• Marshmallow (3.0.0+)

Install using pip...

$ pip install django-rest-marshmallow

Define your schemas as you would with marshmallow, but importing the Schema class from rest_marshmallow instead.

from rest_marshmallow import Schema, fields class CustomerSchema(Schema): name = fields.String() email = fields.Email() created_at = fields.DateTime()

The Schema class has the same interface as a Django REST framework serializer, so you can use it in your generic views...

class CustomerListView(generics.ListAPIView): queryset = Customer.objects.all() serializer_class = CustomerSchema

Or use the serializer API directly, for either serialization...

serializer = CustomerSchema(queryset, many=True) return Response(serializer.data)

Or for validation...

serializer = CustomerSchema(data=request.data) serializer.is_valid(raise_exception=True) serializer.validated_data

If you want to support serializer.save() you'll need to define the .create() and/or .update() methods explicitly.

class CustomerSchema(Schema): name = fields.String() email = fields.Email() created_at = fields.DateTime() def create(self, validated_data): return Customer.objects.create(**validated_data) def update(self, instance, validated_data): for key, value in validated_data.items(): setattr(instance, key, value) instance.save() return instance

You can now use .save() from your view code…

serializer = CustomerSchema(data=request.data) serializer.is_valid(raise_exception=True) serializer.save() return Response(serializer.data, status=status.HTTP_201_CREATED)

Or use the schema together with generic views that create or update instances...

class CustomerListView(generics.ListCreateAPIView): queryset = Customer.objects.all() serializer_class = CustomerSchema

Note that you should always use the create() and update() methods instead of overriding the make_object() marshmallow method.

For nested representations, use marshmallow's standard Nested field as usual.

from rest_marshmallow import fields, Schema class ArtistSchema(Schema): name = fields.String() class AlbumSchema(Schema): title = fields.String() release_date = fields.Date() artist = fields.Nested(ArtistSchema)

The marshmallow only and exclude arguments are also valid as serializer arguments:

serializer = CustomerSchema(queryset, many=True, only=('name', 'email')) return Response(serializer.data)

Install testing requirements.

$ pip install -r requirements.txt

Run with runtests.

$ ./runtests.py

You can also use the excellent tox testing tool to run the tests against all supported versions of Python and Django. Install tox globally, and then simply run:

$ tox

To build the documentation, you'll need to install mkdocs.

$ pip install mkdocs

To preview the documentation:

$ mkdocs serve Running at: http://127.0.0.1:8000/

To build the documentation:

$ mkdocs build