flask-marshmallow 0.4.0

Flask + marshmallow for beautiful APIs

Flask + marshmallow for beautiful APIs

Flask-Marshmallow is a thin integration layer for Flask (a Python web framework) and marshmallow (an object serialization/deserialization library) that adds additional features to marshmallow, including URL and Hyperlinks fields for HATEOAS-ready APIs.

Create your app.

from flask import Flask, jsonify
from flask.ext.marshmallow import Marshmallow

app = Flask(__name__)
ma = Marshmallow(app)

Write your models.

from your_orm import Model, Column, Integer, String, DateTime

class User(Model):
    email = Column(String)
    password = Column(String)
    date_created = Column(DateTime, auto_now_add=True)

Define your output format with marshmallow.

class UserSchema(ma.Schema):
    class Meta:
        # Fields to expose
        fields = ('email', 'date_created', '_links')
    # Smart hyperlinking
    _links = ma.Hyperlinks({
        'self': ma.URLFor('author_detail', id='<id>'),
        'collection': ma.URLFor('authors')
    })

user_schema = UserSchema()
users_schema = UserSchema(many=True)

Output the data in your views.

@app.route('/api/users/')
def users():
    all_users = User.all()
    result = users_schema.dump(all_users)
    return jsonify(result.data)

@app.route('/api/users/<id>')
def user_detail(id):
    user = User.get(id)
    result = user_schema.dump(user)
    return jsonify(result.data)
# {
#     "email": "[e-mail]",
#     "date_created": "Fri, 25 Apr 2014 06:02:56 -0000",
#     "_links": {
#         "self": "/api/authors/42",
#         "collection": "/api/authors/"
#     }
# }

Learn More

To learn more about marshmallow, check out its docs.

Get it now

pip install flask-marshmallow

http://flask-marshmallow.readthedocs.org/

License

MIT licensed. See the bundled LICENSE file for more details.

Changelog

0.4.0 (2014-12-22)

• Backwards-incompatible: Rename URL and AbsoluteURL to URLFor and AbsoluteURLFor, respectively, to prevent overriding marshmallow’s URL field. Thanks @svenstaro for the suggestion.

• Fix bug that raised an error when deserializing Hyperlinks and URL fields. Thanks @raj-kesavan for reporting.

Deprecation:

• Schema.jsonify is deprecated. Use flask.jsonify on the result of Schema.dump instead.

• The MARSHMALLOW_DATEFORMAT and MARSHMALLOW_STRICT config values are deprecated. Use a base Schema class instead.

0.3.0 (2014-10-19)

• Supports marshmallow >= 1.0.0-a.

0.2.0 (2014-05-12)

• Implementation as a proper class-based Flask extension.

• Serializer and fields classes are available from the Marshmallow object.

0.1.0 (2014-04-25)

• First release.

• Hyperlinks, URL, and AbsoluteURL fields implemented.

• Serializer#jsonify implemented.