Merge 0084ff3 into 715a4ad

docs/index.rst

@@ -21,7 +21,7 @@ Journey Usage
 
 *This step is only necessary if you plan on using the BlueprintBundle*
 
-Flask-Journey is managed through a ``Journey`` instance.
+The extension is managed through a ``Journey`` instance.
 If you're utilizing application factories, then you probably want to go the init_app() route:
 
 .. code-block:: python
@@ -37,25 +37,24 @@ If you're utilizing application factories, then you probably want to go the init
     journey.init_app(app)
 
 
-You may also set up ``Journey`` directly, passing a list of bundles to the constructor:
+You may also set up ``Journey`` directly, passing a list of bundles its constructor:
 
 .. code-block:: python
 
     app = Flask(__name__)
     journey = Journey(app, bundles=[bundle1, bundle2])
 
 
-Examples
-========
 
-Using the ``Journey.route`` decorator
--------------------------------------
+
+The route decorator
+===================
 
 The ``route`` component, as mentioned previously, is not dependent on the Journey blueprint manager.
 However, functions decorated with ``flask_journey.route`` can of course, just as ``flask.Blueprint.route``, be added to your app with the help of Journey.
 
 
-Regular marshmallow type schemas:
+**Marshmallow compatible schemas:**
 
 .. code-block:: python
 
@@ -75,8 +74,12 @@ Regular marshmallow type schemas:
         user_name = fields.String(required=True)
 
 
+    users = UserSchema(many=True)
+    user = UserSchema()
+    query = QuerySchema()
+
 
-...and the ``flask_journey.route`` decorator enables simple (de)serialization and validation:
+**...with the flask_journey.route decorator enables simple (de)serialization and validation:**
 
 .. code-block:: python
 
@@ -86,21 +89,24 @@ Regular marshmallow type schemas:
     from flask_journey import route
     from db import create_user, get_user
 
-    from .schemas import UserSchema, QuerySchema
+    from .schemas import user, users, query
 
     bp = Blueprint('users', __name__)
 
-    @route(bp, '/', methods=['GET'], query_schema=QuerySchema(strict=True), marshal_with=UserSchema(many=True))
-    def get_many(__query=None):
-        return get_users(**__query['data'])
+    @route(bp, '/', methods=['GET'], _query=query, marshal_with=users)
+    def get_many(_query=None):
+        return get_users(_query.data)
+
 
+    @route(bp, '/', methods=['POST'], _body=user, marshal_with=user)
+    def create(_body=None):
+        return create_user(_body.data)
 
-    @route(bp, '/', methods=['POST'], body_schema=UserSchema(strict=True), marshal_with=UserSchema())
-    def create(__body=None):
-        return create_user(**__body['data'])
 
 
-These can be registered either using the regular ``register_blueprint`` method of your app, or using ``BlueprintBundle`` with ``Journey.attach_bundle``.
+
+Blueprints
+==========
 
 
 Bundling blueprints
@@ -154,23 +160,22 @@ Importing and registering bundles (along with blueprints) is easy as pie:
     journey.init_app(app)
 
 
-Real examples
--------------
 
-Full and usable examples can be found `here <https://github.com/rbw0/flask-journey/tree/master/examples>`_
+API Documentation
+=================
 
 
-Route decorator
----------------
+Journey API
+-----------
 
-.. automodule:: flask_journey.utils
+.. autoclass:: flask_journey.Journey
     :members:
 
 
-Journey API
------------
+Route decorator
+---------------
 
-.. autoclass:: flask_journey.Journey
+.. automodule:: flask_journey.utils
     :members:
 
 

examples/full/app/api/pilots/schemas.py

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 
-from marshmallow import Schema, fields, validate
+from marshmallow import Schema, fields
 
 
 class QuerySchema(Schema):
@@ -10,3 +10,8 @@ class QuerySchema(Schema):
 class PilotSchema(Schema):
     id = fields.Integer(required=True)
     name = fields.String(required=True)
+
+
+pilots = PilotSchema(many=True)
+pilot = PilotSchema()
+query = QuerySchema()

examples/full/app/api/pilots/views.py

@@ -5,19 +5,19 @@
 
 from app.fake_data.pilots import get_pilots, get_pilot
 
-from .schemas import PilotSchema, QuerySchema
+from .schemas import pilot, pilots, query
 
 
 bp = Blueprint('pilots', __name__)
 
 
-@route(bp, '/<pilot_id>', methods=['GET'], marshal_with=PilotSchema())
+@route(bp, '/<pilot_id>', methods=['GET'], marshal_with=pilot)
 def get_one(pilot_id):
     return get_pilot(pilot_id)
 
 
-@route(bp, '/', methods=['GET'], query_schema=QuerySchema(strict=False), marshal_with=PilotSchema(many=True))
-def get_many(__query=None):
-    pilot_name = __query['data'].get('name', None)
+@route(bp, '/', methods=['GET'], _query=query, marshal_with=pilots, validate=False)
+def get_many(_query=None):
+    pilot_name = _query.data.get('name', None)
     return get_pilots(pilot_name)
 

examples/full/app/api/planes/README.rst

@@ -3,6 +3,6 @@ Planes API
 
 This API heavily utilizes Marshmallow and exposes full CRUD functionality with:
 
-- Query string / parameters deserialization + validation (route.query_schema)
-- JSON data (body) deserialization + validation (route.body_schema)
+- Query string / parameters deserialization + validation (route._query)
+- JSON data (body) deserialization + validation (route._body)
 - Response marshalling (route.marshal_with)

examples/full/app/api/planes/schemas.py

@@ -11,3 +11,8 @@ class PlaneSchema(Schema):
     id = fields.Integer(required=True)
     wings = fields.Integer(required=True)
     name = fields.String(required=True)
+
+
+planes = PlaneSchema(many=True)
+plane = PlaneSchema()
+query = QuerySchema()

examples/full/app/api/planes/views.py

@@ -5,34 +5,34 @@
 
 from app.fake_data.planes import get_plane, get_planes, create_plane, update_plane, delete_plane
 
-from .schemas import PlaneSchema, QuerySchema
+from .schemas import plane, planes, query
 
 
 bp = Blueprint('silly_planes', __name__, url_prefix='/planes')
 
 
-@route(bp, '/<plane_id>', methods=['GET'], marshal_with=PlaneSchema())
+@route(bp, '/<plane_id>', methods=['GET'], marshal_with=plane)
 def get_one(plane_id):
     return get_plane(plane_id)
 
 
-@route(bp, '/<plane_id>', methods=['PUT'], body_schema=PlaneSchema(strict=True), marshal_with=PlaneSchema())
-def update(plane_id, __body=None):
-    return update_plane(plane_id, __body['data'])
+@route(bp, '/<plane_id>', methods=['PUT'], _body=plane, marshal_with=plane)
+def update(plane_id, _body=None):
+    return update_plane(plane_id, _body.data)
 
 
 @route(bp, '/<plane_id>', methods=['DELETE'])
 def delete(plane_id):
     return jsonify(delete_plane(plane_id))
 
 
-@route(bp, '/', methods=['GET'], query_schema=QuerySchema(strict=True), marshal_with=PlaneSchema(many=True))
-def get_many(__query=None):
-    return get_planes(__query['data']['min_wings'])
+@route(bp, '/', methods=['GET'], _query=query, marshal_with=planes)
+def get_many(_query=None):
+    return get_planes(_query.data['min_wings'])
 
 
-@route(bp, '/', methods=['POST'], body_schema=PlaneSchema(strict=True), marshal_with=PlaneSchema())
-def create(__body=None):
-    return create_plane(__body['data'])
+@route(bp, '/', methods=['POST'], _body=plane, marshal_with=plane)
+def create(_body=None):
+    return create_plane(_body.data)
 
 

examples/full/requirements.txt

@@ -1,2 +1,3 @@
 Flask>=0.12.2
+flask-script>=2.0.6
 Flask-Journey>=0.1.0