Skip to main content

Extensions to DRY up Django Rest Framework serializers

Project description

Django REST framework serializer extensions

A collection of useful tools to DRY up your Django Rest Framework serializers

Full documentation: http://django-rest-framework-serializer-extensions.readthedocs.io/

build-status-image coverage-status-image pypi-version

Overview

Serializer extensions reduces the need for very similar serializers, by allowing the fields to be defined on a per-view/request basis. Fields can be whitelisted, blacklisted, and child serializers can be optionally expanded. Whatever fields you choose to use, your querysets can be optimized automatically to make the fewest database calls possible.

Support for HashIds is also provided. If you're currently exposing your internal IDs over a public API, we suggest you consider switching to HashIds instead.

:star: Lovingly open-sourced by Housekeep.

Requirements

Tested against:

Installation

Install using pip:

$ pip install djangorestframework-serializer-extensions

And add rest_framework_serializer_extensions to your INSTALLED_APPS setting:

INSTALLED_APPS = (
    ...
    'rest_framework_serializer_extensions'
)

Basic Usage

To activate the serializer extensions, add the SerializerExtensionsMixin to your serializers:

# serializers.py
from rest_framework.serializers import ModelSerializer
from rest_framework_serializer_extensions.serializers import SerializerExtensionsMixin

...

class OwnerSerializer(SerializerExtensionsMixin, ModelSerializer):
    class Meta:
        model = models.Owner
        fields = ('id', 'name')
        expandable_fields = dict(
            organization=OrganizationSerializer,
            cars=dict(
                serializer=SkuSerializer,
                many=True
            )
        )

And add the SerializerExtensionsAPIViewMixin to your API views:

from rest_framework.generics import RetrieveAPIView
from rest_framework_serializer_extensions.views import SerializerExtensionsAPIViewMixin

class RetriveOwnerAPIView(SerializerExtensionsAPIViewMixin, RetrieveAPIView):
    ...

Examples

Serializer extensions allows your API to re-use your serializers to fit a variety of use cases. The examples shown below use query parameters to modify the response, but individual views can interact with your serializers in much the same way.

>>> GET /owner/x4F/
{
  "id": 'x4F',
  "name": 'tyrell',
  "organization_id": 'kgD'
}
>>> GET /owner/x4F/?expand=organization
{
  "id": 'x4F',
  "name": 'tyrell',
  "organization_id": 'kgD',
  "organization": {
    "id": "kgD",
    "name": "E Corp"
  }
}
>>> GET /owner/x4F/?expand=cars__model&exclude=name
{
  "id": 'x4F',
  "organization_id": 'kgD',
  "cars": [
    {
      "id": "wf9",
      "variant": "P100D",
      "model": {
        "id": "ncX",
        "name": "Model S"
      }
    }
  ]
}
>>> GET /owner/x4F/?expand=cars&only=cars__variant
{
  "cars": [
    {
      "variant": "P100D",
    }
  ]
}

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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for djangorestframework-serializer-extensions, version 2.0.1
Filename, size File type Python version Upload date Hashes
Filename, size djangorestframework_serializer_extensions-2.0.1-py2.py3-none-any.whl (31.4 kB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size djangorestframework-serializer-extensions-2.0.1.tar.gz (14.6 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page