Marshmallow schemas for Django REST framework
django-rest-marshmallow-Marshmallow schemas for Django REST framework
Python Web开发框架
共193Star
详细介绍
django-rest-marshmallow
Marshmallow schemas for Django REST framework.
Overview
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.
Requirements
- Python (2.7, 3.5+)
- Django REST framework (3.8+)
- Marshmallow (2.15+ and 3.0.0b18+)
Installation
Install using pip
...
$ pip install django-rest-marshmallow
Usage
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
Instance create and update
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.
Nested representations
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)
Excluding fields
The marshmallow only
and exclude
arguments are also valid as serializer arguments:
serializer = CustomerSchema(queryset, many=True, only=('name', 'email'))
return Response(serializer.data)
Testing
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
Documentation
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