Skip to content
Marshmallow schemas for Django REST framework
Branch: master
Clone or download
dependabot-preview Bump pytest from 4.6.2 to 4.6.3
Bumps [pytest](https://github.com/pytest-dev/pytest) from 4.6.2 to 4.6.3.
- [Release notes](https://github.com/pytest-dev/pytest/releases)
- [Changelog](https://github.com/pytest-dev/pytest/blob/master/CHANGELOG.rst)
- [Commits](pytest-dev/pytest@4.6.2...4.6.3)

Signed-off-by: dependabot-preview[bot] <support@dependabot.com>
Latest commit 80d723a Jun 12, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs Bump version and update changelog Feb 14, 2019
env First pass Sep 11, 2015
rest_marshmallow Bump version and update changelog Feb 14, 2019
tests Add support for fields.Nested with many=True Jan 24, 2019
.gitignore First pass Sep 11, 2015
.travis.yml Remove sudo: in .travis.yml Jan 16, 2019
LICENSE
MANIFEST.in First pass Sep 11, 2015
README.md Bump license year; update badges Jan 2, 2019
mkdocs.yml Docs: fix syntax highlighting in README; update repo links Jul 19, 2017
requirements.txt Bump pytest from 4.6.2 to 4.6.3 Jun 12, 2019
runtests.py Configure flake8 in setup.cfg Oct 9, 2016
setup.cfg Set up automatic PyPI releases Jul 19, 2017
setup.py Bump up required versions of Python, DRF, and marshmallow May 26, 2018
tox.ini Don't test marshmallow 3 x Python 2 May 5, 2019

README.md


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
You can’t perform that action at this time.