Blueprints

New in version 1.5.

Changed in version 2.1.2: Host Matching is now supported. See Host Matching.

In Kyoukai, routes are stored inside a tree structure consisting of multiple Blueprint objects with a parent and children. Each Blueprint contains a group of routes stored on it, which inherit the request hooks and the API prefix of all of its parents.

Blueprints are instantiated similar to app objects, with a name.

my_blueprint = Blueprint("my_blueprint")

Additionally, blueprints take an additional set of parameters which can be used to more finely control the behaviour.

• prefix: The URL prefix to add to every request.

  For example, if this is set to /api/v1`, every request attached to this blueprint will only be accessible via ``/api/v1/<route>.

A note on the tree

Blueprints are stored inside a tree structure - that means that all Blueprints have a parent blueprint and 0 to N children blueprints.

When registering an error handler, or a request hook, children blueprints automatically inherit these unless they are overridden on the child level.

Routing

Routing with Blueprints is incredibly similar to routing with a bare app object. Internally, an @app.route maps to routing on an underlying Blueprint object used as the “root” blueprint.

@my_blueprint.route("/some/route")
async def some_route(ctx: HTTPRequestContext):
    return "Some route"

Blueprint.route(routing_url, methods=('GET', 'HEAD'), **kwargs)

Convenience decorator for adding a route.

This is equivalent to:

route = bp.wrap_route(func, **kwargs)
bp.add_route(route, routing_url, methods)

Changed in version 2.2.0: Now accepts a Route as the function to decorate - this will add a new routing url and method pair to Route.add_route().

Error handlers

Error handlers with Blueprints are handled exactly the same as error handlers on bare app objects. The difference between these however is that error handlers are local to the Blueprint and its children.

@my_blueprint.errorhandler(500)
async def e500(ctx: HTTPRequestContext, err: Exception):
    return "Handled an error"

Blueprint.errorhandler(code, endcode=None, step=None)

Helper decorator for adding an error handler.

This is equivalent to:

route = bp.add_errorhandler(cbl, code)

Parameters:

• code (int) – The error handler code to use.
• endcode (Optional[int]) – The end of the error code range to handle. Error handlers will be added for all requests between code and endcode. If this is not provided, only one code will be handled.
• step (Optional[int]) – The step for the error handler range.

Registering blueprints

If, after creating your blueprint, you attempt to navigate to /some/route you will find a 404 error living there instead. This is because you did not register the Blueprint to your application.

app.register_blueprint(my_blueprint)

Internally, this adds a child to the root blueprint, and sets the parent of the child to the root blueprint. If you have a blueprint that you wish to inherit from, you must register your Blueprint as a child of the Blueprint you wish to inherit from.

my_blueprint.add_child(my_other_blueprint)

Kyoukai.register_blueprint(child)

Registers a child blueprint to this app’s root Blueprint.

This will set up the Blueprint tree, as well as setting up the routing table when finalized.

Parameters:child (Blueprint) – The child Blueprint to add. This must be an instance of Blueprint.

Blueprint.add_child(blueprint)

Adds a Blueprint as a child of this one. This is automatically called when using another Blueprint as a parent.

Parameters:blueprint (Blueprint) – The blueprint to add as a child. Return type:Blueprint