Flask-Journey¶
The two core components of Journey, namely route
and BlueprintBundle
, are not dependent of each other.
However, there might be non-breaking code implemented in the future that enables the components integrate, either
in a unidirectional or bidirectional way.
This, and the fact that they operate in the same field, was the reason for adding them both to this extension.
Usage¶
Flask-Journey is managed through a Journey
instance.
This component and procedure is only necessary if you plan on using the journey.BlueprintBundle
for managing blueprints.
Anyway - if you do want to use it and you’re utilizing the application factory pattern, then you probably want to set up Journey
with init_app():
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 it up directly, passing a list of bundles to the Journey
constructor:
app = Flask(__name__)
journey = Journey(app, bundles=[bundle1, bundle2])
Examples¶
Bundling blueprints¶
There are various benefits of using the Journey BlueprintBundle, and in many 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 logically.
- It allows you to utilize the Journey API (currently only to list 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 .danger import bp as danger
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')
v2 = BlueprintBundle(path='/api/v2', description="API v2, beta")
v2.attach_bp(users, description='Users CRUD')
v2.attach_bp(groups)
v2.attach_bp(companies, description='Companies API')
v2.attach_bp(danger, description='Dangerous testing API, not for production use')
Importing bundles¶
Importing and registering bundles (and along with their blueprints) is easy as pie:
# file: api/__init__.py
from flask import Flask
from .bundles import v1, v2
app = Flask(__name__)
journey = Journey()
journey.attach_bundle(v1)
journey.attach_bundle(v2)
journey.init_app(app)
Using the Journey.route
decorator¶
The route
component, as mentioned previously, is not dependent of 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:
# 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)
The flask_journey.route
enables easy (de)serialization and validation with the help of the Marshmallow library.
# api/users/views.py
from flask import Blueprint
from flask_journey import route
from db import create_user, get_user
from .schema import UserSchema
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=['POST'], body_schema=UserSchema(strict=True), marshal_with=UserSchema())
def create(__body=None):
return create_user(**__body['data'])
Route decorator¶
-
flask_journey.utils.
route
(bp, *args, **kwargs)¶ Journey route decorator
Enables simple serialization, deserialization and validation of Flask routes with the help of Marshmallow.
If a schema (body_schema and/or query_schema) was passed to the decorator, the corresponding :class`marshmallow.Schema` object gets passed to the decorated function:
__query - kwarg if query_schema was passed __body - kwarg if body_schema was passed
Parameters: - bp –
flask.Blueprint
object - args – args to pass along to Blueprint.route
- kwargs –
strict_slashes: Enable / disable strict slashes (default False) body_schema: Deserialize JSON body with this schema query_schema: Deserialize Query string with this schema marshal_with: Serialize the output with this schema
- bp –
Journey API¶
-
class
flask_journey.
Journey
(app=None, bundles=None)¶ Central controller class. Registers bundles and exposes properties for listing routes.
Parameters: app – App to pass directly to Journey -
attach_bundle
(bundle)¶ Attaches a bundle object
Parameters: bundle –
flask_journey.BlueprintBundle
objectRaises: - IncompatibleBundle if the bundle is not of type BlueprintBundle
-
static
get_blueprint_routes
(app, base_path)¶ Returns detailed information about registered blueprint routes matching the BlueprintBundle path
Parameters: - app – App instance to obtain rules from
- base_path – Base path to return detailed route info for
Returns: List of route detail dicts
-
static
get_child_path
(bp)¶ Strips leading slashes from url_prefix, if it has been set, and returns. If not, return Blueprint.name.
Parameters: bp – flask.Blueprint
objectReturns: blueprint name
-
init_app
(app)¶ Initializes Journey extension
Parameters: app – App passed from constructor or directly to init_app
-
routes_detailed
¶ Returns a detailed list bundles and its blueprints and routes
Returns: List of blueprint routes
-
routes_simple
¶ Returns simple info about registered blueprints
Returns: Tuple containing endpoint, path and allowed methods for each route
-
BlueprintBundle API¶
-
class
flask_journey.
BlueprintBundle
(path='/', description='')¶ Creates a BlueprintBundle at the path specified
Parameters: path – blueprint base path -
attach_bp
(bp, description='')¶ Attaches a flask.Blueprint to the bundle
Parameters: - bp –
flask.Blueprint
object - description – Optional description string
- bp –
-
static
sanitize_path
(path)¶ Performs sanitation of the route path after validating
Parameters: path – path to sanitize Returns: sanitized path
-