index.rst

Flask-Journey

flask_journey

The two core components of Journey, route and BlueprintBundle, are not dependent on each other, however, there might be code added in the future that will enable them to integrate.

This, and the fact that they operate in the same field was the motivation for adding both to this extension.

Installation

Use pip to install the extension:

$ pip install flask-journey

Journey Usage

This step is only necessary if you plan on using the BlueprintBundle

The extension is managed through a Journey instance. If utilizing application factories, then you probably want to go the init_app() route:

from flask import Flask
from flask_journey import Journey

from .bundles import bundle1, bundle2

app = Flask(__name__)
journey = Journey()
journey.attach_bundle(bundle1)
journey.attach_bundle(bundle2)
journey.init_app(app)

You may also set up Journey directly, passing a list of bundles its constructor:

app = Flask(__name__)
journey = Journey(app, bundles=[bundle1, bundle2])

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.

Marshmallow compatible schemas:

# file: api/users/schemas.py

from marshmallow import Schema, fields, validate

class QuerySchema(Schema):
    first_name = fields.String(required=False)
    last_name = fields.String(required=False)


class UserSchema(Schema):
    id = fields.Integer(required=True)
    first_name = fields.String(required=True)
    last_name = fields.String(required=True)
    user_name = fields.String(required=True)


users = UserSchema(many=True)
user = UserSchema()
query = QuerySchema()

...with the flask_journey.route decorator enables simple (de)serialization and validation:

# api/users/views.py

from flask import Blueprint
from flask_journey import route

from .services import create_user, get_user, update_user
from .schemas import user, users, query

bp = Blueprint('users', __name__)

@route(bp, '/', methods=['GET'], _query=query, marshal_with=users)
def get_users(_query):
    return get_users(_query.data)


@route(bp, '/', methods=['POST'], _body=user, marshal_with=user)
def create_user(_body):
    return create_user(_body.data)


@route(bp, '/<user_id>', methods=['PUT'], _body=user, marshal_with=user)
def update_user(user_id, _body):
    return update_user(user_id, _body.data)

Blueprints

Bundling blueprints

There are various benefits of using the Journey BlueprintBundle, and in most cases just one BlueprintBundle is enough.

• It can be used to easily segregate your blueprint registration code from the other parts of your application.
• It helps you group blueprints in a logical manner.
• It enables you to utilize the Journey API (currently only for blueprint bundle registration and listing routes)

# file: api/bundles.py

from flask_journey import BlueprintBundle

from .users import bp as users
from .groups import bp as groups
from .companies import bp as companies
from .stuff import bp as stuff

v1 = BlueprintBundle(path='/api/v1', description="API v1, stable")
v1.attach_bp(users, description='Users CRUD')
v1.attach_bp(groups)
v1.attach_bp(companies, description='Companies API')

other = BlueprintBundle(path='/other')
other.attach_bp(stuff)

Importing bundles

Importing and registering bundles (along with blueprints) is easy as pie:

# file: api/__init__.py

from flask import Flask
from .bundles import v1, other

app = Flask(__name__)
journey = Journey()
journey.attach_bundle(v1)
journey.attach_bundle(other)
journey.init_app(app)

API Documentation

Journey API

flask_journey.Journey

Route decorator

flask_journey.utils

BlueprintBundle API

flask_journey.BlueprintBundle

Exceptions

flask_journey.exceptions