JSON API 1.0 (https://jsonapi.org) formatting with marshmallow
Project description
Homepage: http://marshmallow-jsonapi.rtfd.org/
JSON API 1.0 (https://jsonapi.org) formatting with marshmallow.
marshmallow-jsonapi provides a simple way to produce JSON API-compliant data in any Python web framework.
from marshmallow_jsonapi import Schema, fields
class PostSchema(Schema):
id = fields.Str(dump_only=True)
title = fields.Str()
author = fields.HyperlinkRelated(
'/authors/{author_id}',
url_kwargs={'author_id': '<author.id>'},
)
comments = fields.HyperlinkRelated(
'/posts/{post_id}/comments',
url_kwargs={'post_id': '<id>'},
# Include resource linkage
many=True, include_data=True,
type_='comments'
)
class Meta:
type_ = 'posts'
post_schema = PostSchema()
post_schema.dump(post).data
# {
# "data": {
# "id": "1",
# "type": "posts"
# "attributes": {
# "title": "JSON API paints my bikeshed!"
# },
# "relationships": {
# "author": {
# "links": {
# "related": "/authors/9"
# }
# },
# "comments": {
# "links": {
# "related": "/posts/1/comments/"
# }
# "data": [
# {"id": 5, "type": "comments"},
# {"id": 12, "type": "comments"}
# ],
# }
# },
# }
# }Error formatting
Schema.load and Schema.validate will return JSON API-formatted Error objects.
from marshmallow import validate
from marshmallow_jsonapi import Schema, fields
class AuthorSchema(Schema):
id = fields.Str(dump_only=True)
first_name = fields.Str(required=True)
last_name = fields.Str(required=True)
password = fields.Str(load_only=True, validate=validate.Length(6))
twitter = fields.Str()
class Meta:
type_ = 'people'
schema = AuthorSchema()
schema.validate({'first_name': 'Dan', 'password': 'short'})
# {
# "errors": [
# {
# "detail": "Shorter than minimum length 6.",
# "source": {"pointer": "/data/attributes/password"}
# },
# {
# "detail": "Missing data for required field.",
# "source": {"pointer": "/data/attributes/last_name"}
# }
# ]
# }Inflection
You can optionally specify a function to transform attribute names. For example, you may decide to follow JSON API’s recommendation to use “dasherized” names.
from marshmallow_jsonapi import Schema, fields
def dasherize(text):
return text.replace('_', '-')
class AuthorSchema(Schema):
id = fields.Str(dump_only=True)
first_name = fields.Str(required=True)
last_name = fields.Str(required=True)
class Meta:
type_ = 'people'
inflect = dasherize
result = AuthorSchema().dump(author)
result.data
# {
# 'data': {
# 'id': '9',
# 'type': 'people',
# 'attributes': {
# 'first-name': 'Dan',
# 'last-name': 'Gebhardt'
# }
# }
# }Flask integration
Marshmallow-jsonapi includes optional utilities to integrate with Flask.
For example, the HyperlinkRelated field in the marshmallow_jsonapi.flask module allows you to pass an endpoint name instead of a path template.
The above schema could be rewritten in a Flask application like so:
from marshmallow_jsonapi import Schema, fields
from marshmallow_jsonapi.flask import HyperlinkRelated
class PostSchema(Schema):
id = fields.Str(dump_only=True)
title = fields.Str()
author = HyperlinkRelated(
# Flask endpoint name, passed to url_for
endpoint='author_detail',
url_kwargs={'author_id': '<author.id>'},
)
comments = HyperlinkRelated(
endpoint='posts_comments',
url_kwargs={'post_id': '<id>'},
# Include resource linkage
many=True, include_data=True,
type_='comments'
)
class Meta:
type_ = 'posts'See here for a full example.
Installation
pip install marshmallow-jsonapi
Documentation
Full documentation is available at https://marshmallow-jsonapi.readthedocs.org/.
Requirements
Python >= 2.7 or >= 3.3
Project Links
License
MIT licensed. See the bundled LICENSE file for more details.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file marshmallow-jsonapi-0.2.0.tar.gz.
File metadata
- Download URL: marshmallow-jsonapi-0.2.0.tar.gz
- Upload date:
- Size: 15.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 92be9dc245c9a52c5730f65c4014e073860c8e9112bb886ee4510bc16dc88560 |
|
| MD5 | 54e8ca9494479a0c8e779f924fa2b96f |
|
| BLAKE2b-256 | 9f8a1be5eaefca47a7d860d9381fdec69a7779d270afb2a2b176d6235ad2c8aa |
Provenance
File details
Details for the file marshmallow_jsonapi-0.2.0-py2.py3-none-any.whl.
File metadata
- Download URL: marshmallow_jsonapi-0.2.0-py2.py3-none-any.whl
- Upload date:
- Size: 12.2 kB
- Tags: Python 2, Python 3
- Uploaded using Trusted Publishing? No
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 1737aa9e47cd49911799779749951dc59fc380e1f583592f5db41aaf461eea2f |
|
| MD5 | 54d44fe51ec032d3caf19dcccd2109fc |
|
| BLAKE2b-256 | d5a36ae4e31eb0d55f1c019b608901f7778933d08f64de95ee4e312053dfb43a |
