1*****************
2Flask-Marshmallow
3*****************
4
5|pypi-package| |build-status| |docs| |marshmallow23| |black|
6
7Flask + marshmallow for beautiful APIs
8======================================
9
10Flask-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. It also (optionally) integrates with `Flask-SQLAlchemy <http://flask-sqlalchemy.pocoo.org/>`_.
11
12Get it now
13----------
14::
15
16    pip install flask-marshmallow
17
18
19Create your app.
20
21.. code-block:: python
22
23    from flask import Flask
24    from flask_marshmallow import Marshmallow
25
26    app = Flask(__name__)
27    ma = Marshmallow(app)
28
29Write your models.
30
31.. code-block:: python
32
33    from your_orm import Model, Column, Integer, String, DateTime
34
35
36    class User(Model):
37        email = Column(String)
38        password = Column(String)
39        date_created = Column(DateTime, auto_now_add=True)
40
41
42Define your output format with marshmallow.
43
44.. code-block:: python
45
46
47    class UserSchema(ma.Schema):
48        class Meta:
49            # Fields to expose
50            fields = ("email", "date_created", "_links")
51
52        # Smart hyperlinking
53        _links = ma.Hyperlinks(
54            {
55                "self": ma.URLFor("user_detail", values=dict(id="<id>")),
56                "collection": ma.URLFor("users"),
57            }
58        )
59
60
61    user_schema = UserSchema()
62    users_schema = UserSchema(many=True)
63
64
65Output the data in your views.
66
67.. code-block:: python
68
69    @app.route("/api/users/")
70    def users():
71        all_users = User.all()
72        return users_schema.dump(all_users)
73
74
75    @app.route("/api/users/<id>")
76    def user_detail(id):
77        user = User.get(id)
78        return user_schema.dump(user)
79
80
81    # {
82    #     "email": "fred@queen.com",
83    #     "date_created": "Fri, 25 Apr 2014 06:02:56 -0000",
84    #     "_links": {
85    #         "self": "/api/users/42",
86    #         "collection": "/api/users/"
87    #     }
88    # }
89
90
91http://flask-marshmallow.readthedocs.io/
92========================================
93
94Learn More
95==========
96
97To learn more about marshmallow, check out its `docs <http://marshmallow.readthedocs.io/en/latest/>`_.
98
99
100
101Project Links
102=============
103
104- Docs: https://flask-marshmallow.readthedocs.io/
105- Changelog: http://flask-marshmallow.readthedocs.io/en/latest/changelog.html
106- PyPI: https://pypi.python.org/pypi/flask-marshmallow
107- Issues: https://github.com/marshmallow-code/flask-marshmallow/issues
108
109License
110=======
111
112MIT licensed. See the bundled `LICENSE <https://github.com/marshmallow-code/flask-marshmallow/blob/master/LICENSE>`_ file for more details.
113
114
115.. _Flask: http://flask.pocoo.org
116.. _marshmallow: http://marshmallow.readthedocs.io
117
118.. |pypi-package| image:: https://badgen.net/pypi/v/flask-marshmallow
119    :target: https://pypi.org/project/flask-marshmallow/
120    :alt: Latest version
121.. |build-status| image:: https://dev.azure.com/sloria/sloria/_apis/build/status/marshmallow-code.flask-marshmallow?branchName=dev
122    :target: https://dev.azure.com/sloria/sloria/_build/latest?definitionId=14&branchName=dev
123    :alt: Build status
124.. |docs| image:: https://readthedocs.org/projects/flask-marshmallow/badge/
125   :target: https://flask-marshmallow.readthedocs.io/
126   :alt: Documentation
127.. |marshmallow23| image:: https://badgen.net/badge/marshmallow/2,3?list=1
128    :target: https://marshmallow.readthedocs.io/en/latest/upgrading.html
129    :alt: marshmallow 3 compatible
130.. |black| image:: https://badgen.net/badge/code%20style/black/000
131    :target: https://github.com/ambv/black
132    :alt: code style: black
133