kyoukai.blueprint

A blueprint is a container - a collection of routes.

Kyoukai uses Blueprints to create a routing tree - a tree of blueprints that are used to collect routes together and match routes easily.

Classes

Blueprint(name: str, …)

A Blueprint is a “route container” - it contains 0 to N routes, and 0 to N child Blueprints that inherit from the parent.

class kyoukai.blueprint.Blueprint(name: str, parent: typing.Union[kyoukai.blueprint.Blueprint, NoneType] = None, prefix: str = '', *, host_matching: bool = False, host: str = None)

Bases: object

A Blueprint is a “route container” - it contains 0 to N routes, and 0 to N child Blueprints that inherit from the parent.

Parameters:

• name (str) – The name of this Blueprint. This is used when generating endpoints in the finalize stage.
• parent (Optional[Blueprint]) – The parent of this Blueprint. Parent blueprints will gather the routes of their children, and return a giant werkzeug.routing.Map object that contains all of the route maps in the children
• prefix (str) – The prefix to be added to the start of every route name. This is inherited from parents - the parent prefix will also be added to the start of every route.
• host_matching (bool) – Should host matching be enabled? This is implicitly True if host is non-None.
• host (Optional[str]) – The host of the Blueprint. Used for custom subdomain routing. If this is None, then this Blueprint will be used for all hosts.

name = None

The name of this Blueprint.

finalized = None

If this Blueprint is finalized or not. Finalization of a blueprint means gathering all of the Maps, and compiling a routing table which stores the endpoints.

routes = None

The list of routes. This is used in finalization.

map = None

The Map used for this blueprint.

errorhandlers = None

The error handler dictionary.

parent

Return type:Blueprint Returns:The parent Blueprint of this blueprint.

prefix

Return type:str Returns:The prefix of this Blueprint.

Changed in version 2.2.0: Moved prefix combination to computed_prefix.

computed_prefix

Return type:str Returns:The combined prefix (parent + ours) of this Blueprint.

New in version 2.2.0.

tree_routes

Return type:Generator[Route, None, None] Returns:A generator that yields all routes from the tree, from parent to children.

host

Return type:str Returns:The host for this Blueprint, or the host of any parent Blueprint.

get_submount()

Gets the werkzeug.routing.Submount for this Blueprint.

New in version 2.2.0.

Return type:Submount

traverse_tree()

Traverses the tree for children Blueprints.

Return type:Generator[Blueprint, None, None]

finalize(**map_options)

Called on the root Blueprint when all Blueprints have been registered and the app is starting.

This will automatically build a werkzeug.routing.Map of werkzeug.routing.Rule objects for each Blueprint.

Note

Calling this on sub-blueprints will have no effect, apart from generating a Map. It is recommended to only call this on the root Blueprint.

Changed in version 2.2.0: This now uses submounts instead of a giant rule amalgamation.

Parameters:map_options – The options to pass to the created Map. Return type:Map Returns:The werkzeug.routing.Map created from the routing tree.

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

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().

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.

wrap_route(cbl, *args, **kwargs)

Wraps a callable in a Route. This is required for routes to be added.

Parameters:cbl – The callable to wrap. Return type:Route Returns:A new Route object.

add_errorhandler(cbl, startcode, endcode=None, step=None)

Adds an error handler to the table of error handlers.

A blueprint can only have one error handler per code. If it doesn’t have an error handler for that code, it will try to fetch recursively the parent’s error handler.

Parameters:

• cbl – The callable error handler.
• startcode (int) – The error code to handle, for example 404. This also represents the start of an error range, if endcode is not None.
• endcode (Optional[int]) – The end of the error code range to handle. Error handlers will be added for all requests between startcode and endcode.
• step (Optional[int]) – The step for the error handler range.

get_errorhandler(exc)

Recursively acquires the error handler for the specified error.

Parameters:exc (Union[HTTPException, int]) – The exception to get the error handler for. This can either be a HTTPException object, or an integer. Return type:Union[None, Route] Returns:The Route object that corresponds to the error handler, or None if no error handler could be found.

get_hooks(type_)

Gets a list of hooks that match the current type.

These are ordered from parent to child.

Parameters:type (str) – The type of hooks to get (currently “pre” or “post”). Returns:An iterable of hooks to run.

add_hook(type_, hook)

Adds a hook to the current Blueprint.

Parameters:

• type (str) – The type of hook to add (currently “pre” or “post”).
• hook – The callable function to add as a hook.

after_request(func)

Convenience decorator to add a post-request hook.

before_request(func)

Convenience decorator to add a pre-request hook.

add_route(route, routing_url, methods=('GET', 'HEAD'))

Adds a route to the routing table and map.

Parameters:

• route (Route) –

  The route object to add.

  This can be gotten from Blueprint.wrap_route, or by directly creating a Route object.

• routing_url (str) –

  The Werkzeug-compatible routing URL to add this route under.

  For more information, see http://werkzeug.pocoo.org/docs/0.11/routing/.

• methods (Sequence[str]) – An iterable of valid method this route can be called with.

Returns:

The unmodified Route object.

get_route(endpoint)

Gets the route associated with an endpoint.

Return type:Optional[Route]

add_route_group(group)

Adds a route group to the current Blueprint.

Parameters:group (RouteGroup) – The RouteGroup to add.

url_for(environment, endpoint, *, method=None, **kwargs)

Gets the URL for a specified endpoint using the arguments of the route.

This works very similarly to Flask’s url_for.

It is not recommended to invoke this method directly - instead, url_for is set on the context object that is provided to your user function. This will allow you to invoke it with the correct environment already set.

Parameters:

• environment (dict) – The WSGI environment to use to bind to the adapter.
• endpoint (str) – The endpoint to try and retrieve.
• method (Optional[str]) – If set, the method to explicitly provide (for similar endpoints with different allowed routes).
• kwargs – Keyword arguments to provide to the route.

Return type:

str

Returns:

The built URL for this endpoint.

match(environment)

Matches with the WSGI environment.

Warning

You should not be using this method yourself.

Changed in version 2.2.0: This will now return the werkeug.routing.Rule as well.

Parameters:environment (dict) – The environment dict to perform matching with. You can use the environ argument of a Request to get the environment back. Return type:Tuple[Route, Container[Any], Rule] Returns:A Route object, which can be invoked to return the right response, and the parameters to invoke it with.