Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/marshmallow-code/django-rest-marshmallow
Marshmallow schemas for Django REST framework
https://github.com/marshmallow-code/django-rest-marshmallow
django django-rest-marshmallow marshmallow rest-api schema serialization
Last synced: about 2 months ago
JSON representation
Marshmallow schemas for Django REST framework
- Host: GitHub
- URL: https://github.com/marshmallow-code/django-rest-marshmallow
- Owner: marshmallow-code
- License: isc
- Archived: true
- Created: 2015-09-11T11:40:23.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2021-06-07T05:12:48.000Z (over 3 years ago)
- Last Synced: 2024-10-30T00:00:14.004Z (2 months ago)
- Topics: django, django-rest-marshmallow, marshmallow, rest-api, schema, serialization
- Language: Python
- Homepage: https://marshmallow-code.github.io/django-rest-marshmallow/
- Size: 774 KB
- Stars: 217
- Watchers: 8
- Forks: 15
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-django-performance - django-rest-marshmallow - Marshmallow schemas for Django REST framework. (Serialization / Tools)
- starred-awesome - django-rest-marshmallow - Marshmallow schemas for Django REST framework (Python)
README
---
# [django-rest-marshmallow](https://marshmallow-code.github.io/django-rest-marshmallow/)
[Marshmallow schemas][marshmallow] 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 (3.6+)
* Django REST framework (3.8+)
* Marshmallow (3.0.0+)
## Installation
Install using `pip`...
```bash
$ pip install django-rest-marshmallow
```
---
## Usage
Define your schemas as you would with marshmallow, but importing the `Schema` class from `rest_marshmallow` instead.
```python
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...
```python
class CustomerListView(generics.ListAPIView):
queryset = Customer.objects.all()
serializer_class = CustomerSchema
```
Or use the serializer API directly, for either serialization...
```python
serializer = CustomerSchema(queryset, many=True)
return Response(serializer.data)
```
Or for validation...
```python
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.
```python
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…
```python
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...
```python
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.
```python
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:
```python
serializer = CustomerSchema(queryset, many=True, only=('name', 'email'))
return Response(serializer.data)
```
---
## Testing
Install testing requirements.
```bash
$ pip install -r requirements.txt
```
Run with runtests.
```bash
$ ./runtests.py
```
You can also use the excellent [tox](http://tox.readthedocs.org/en/latest/) testing tool to run the tests against all supported versions of Python and Django. Install tox globally, and then simply run:
```bash
$ tox
```
## Documentation
To build the documentation, you'll need to install `mkdocs`.
```bash
$ pip install mkdocs
```
To preview the documentation:
```bash
$ mkdocs serve
Running at: http://127.0.0.1:8000/
```
To build the documentation:
```bash
$ mkdocs build
```
[marshmallow]: https://marshmallow.readthedocs.org/en/latest/