django-rest-marshmallow - GitLite

KO | EN

gitlite — search

#hacktoberfest #react #typescript #golang #android #deep-learning #linux #nodejs #macos #kubernetes #vue #security #pytorch #mcp

django-rest-marshmallow

(★ 215)

Marshmallow schemas for Django REST framework

File Explorer

Download Latest Version (.zip)

- - extra.css
- index.md
- pip-selfcheck.json
- __init__.py
- __init__.py
- conftest.py
- test_marshmallow.py
.gitignore
.travis.yml
LICENSE
MANIFEST.in
mkdocs.yml
README.md
requirements.txt
runtests.py
setup.cfg
setup.py
tox.ini

# Installation Guide

1. Get the code

git clone https://github.com/marshmallow-code/django-rest-marshmallow

Downloads the entire project code from GitHub to your computer.

cd django-rest-marshmallow

Moves into the project folder you just downloaded.

2. Python

Easy Recommended

Prerequisites

Git Needed to download the project code from GitHub.
Python 3 On Windows, be sure to check 'Add Python to PATH' during installation.

$ pip install django-rest-marshmallow

Installs the Python libraries listed in requirements.txt (or similar).

$ pip install -r requirements.txt

Installs the Python libraries listed in requirements.txt (or similar).

$ pip install mkdocs

Installs the Python libraries listed in requirements.txt (or similar).

✅ If it runs without errors and prints output in the terminal, it worked.

Pulled directly from this repo's README.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<div class="badges">
    <a href="http://travis-ci.org/marshmallow-code/django-rest-marshmallow">
        <img src="https://badgen.net/travis/marshmallow-code/django-rest-marshmallow/master"
        alt="Travis CI">
    </a>
    <a href="https://pypi.python.org/pypi/django-rest-marshmallow">
        <img src="https://badgen.net/pypi/v/django-rest-marshmallow"
        alt="django-rest-marshmallow on PyPI">
    </a>
    <a href="https://marshmallow.readthedocs.io/en/latest/upgrading.html">
        <img src="https://badgen.net/badge/marshmallow/2,3?list=1"
        alt="marshmallow 3 compatible">
    </a>
</div>

---

# [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/