Hooks#

Falcon supports before and after hooks. You install a hook simply by applying one of the decorators below, either to an individual responder or to an entire resource.

For example, consider this hook that validates a POST request for an image resource:

def validate_image_type(req, resp, resource, params):
    if req.content_type not in ALLOWED_IMAGE_TYPES:
        msg = 'Image type not allowed. Must be PNG, JPEG, or GIF'
        raise falcon.HTTPBadRequest(title='Bad request', description=msg)

You would attach this hook to an on_post responder like so:

@falcon.before(validate_image_type)
def on_post(self, req, resp):
    pass

Or, suppose you had a hook that you would like to apply to all responders for a given resource. In that case, you would simply decorate the resource class:

def extract_project_id(req, resp, resource, params):
    params['project_id'] = None
    if req.content_type == falcon.MEDIA_JSON:
        params['project_id'] = req.get_media().get('projectId')

@falcon.before(extract_project_id)
class Message:
    def on_post(self, req, resp, project_id):
        pass

    def on_get(self, req, resp, project_id):
        pass

In addition to just running your logic before all responders of this resource, the extract_project_id hook also injects the project_id parameter – see falcon.before() for a more elaborate explanation.

Note

When decorating an entire resource class, all method names that resemble responders, including suffixed (see also add_route()) ones, are decorated. If, for instance, a method is called on_get_items, but it is not meant for handling GET requests under a route with the suffix items, the easiest workaround for preventing the hook function from being applied to the method is renaming it not to clash with the responder pattern.

Note also that you can pass additional arguments to your hook function as needed:

def validate_image_type(req, resp, resource, params, allowed_types):
    if req.content_type not in allowed_types:
        msg = 'Image type not allowed.'
        raise falcon.HTTPBadRequest(title='Bad request', description=msg)

@falcon.before(validate_image_type, ['image/png'])
def on_post(self, req, resp):
    pass

Falcon supports using any callable as a hook. This allows for using a class instead of a function:

class Authorize:
    def __init__(self, roles):
        self._roles = roles

    def __call__(self, req, resp, resource, params):
        pass

@falcon.before(Authorize(['admin']))
def on_post(self, req, resp):
    pass

Falcon middleware components can also be used to insert logic before and after requests. However, unlike hooks, middleware components are triggered globally for all requests.

Tip

In order to pass data from a hook function to a resource function use the req.context and resp.context objects. These context objects are intended to hold request and response data specific to your app as it passes through the framework.

You can also create your own decorators to wrap responder methods without needing to use hooks.

Here’s an example of a custom decorator that logs request/response information:

def log_access(responder):
    @functools.wraps(responder)
    def wrapper(resource, req, resp, *args, **kwargs) -> None:
        # Call the original responder
        responder(resource, req, resp, *args, **kwargs)

        # Log after the responder has been called
        logging.info(
            f'[{type(resource).__name__}] {req.method} {req.relative_uri}'
            f' => HTTP {resp.status_code}'
        )

    return wrapper

class HelloResource:
    @log_access
    def on_get(self, req, resp) -> None:
        resp.media = {"Hello": "World"}

In this example, the log_access decorator will log information about each request after the responder completes.

Note

The @functools.wraps(responder) ensures that the wrapper function preserves the original method’s name and attributes.

You can also create parameterized decorators:

def log_access(level=logging.INFO):
    def decorator(responder):
        @functools.wraps(responder)
        def wrapper(resource, req, resp, *args, **kwargs) -> None:
            responder(resource, req, resp, *args, **kwargs)

            logging.log(
                level,
                f'[{type(resource).__name__}] {req.method} {req.relative_uri}'
                f' => HTTP {resp.status_code}'
            )

        return wrapper

    return decorator

class HelloResource:
    @log_access(level=logging.DEBUG)
    def on_get(self, req, resp) -> None:
        resp.media = {"Hello": "World"}

Before Hooks#

falcon.before(action: Callable[Concatenate[wsgi.Request, wsgi.Response, Resource, dict[str, Any], None] | Callable[Concatenate[asgi.Request, asgi.Response, Resource, dict[str, Any], Awaitable[None]], *args: _FN.args, **kwargs: _FN.kwargs) → Callable[[_R], _R][source]#

Execute the given action function before the responder.

The params argument that is passed to the hook contains only the fields from the URI template path; it does not include query string values.

Hooks may inject extra params as needed. For example:

def do_something(req, resp, resource, params):
    try:
        params['id'] = int(params['id'])
    except ValueError:
        raise falcon.HTTPBadRequest(title='Invalid ID',
                                    description='ID was not valid.')

    params['answer'] = 42

Parameters:

action (callable) – A function of the form func(req, resp, resource, params), where resource is a reference to the resource class instance associated with the request and params is a dict of URI template field names, if any, that will be passed into the resource responder as kwargs.
*args – Any additional arguments will be passed to action in the order given, immediately following the req, resp, resource, and params arguments.

Keyword Arguments:

**kwargs – Any additional keyword arguments will be passed through to action.

After Hooks#

falcon.after(action: Callable[Concatenate[wsgi.Request, wsgi.Response, Resource, None] | Callable[Concatenate[asgi.Request, asgi.Response, Resource, Awaitable[None]], *args: _FN.args, **kwargs: _FN.kwargs) → Callable[[_R], _R][source]#

Execute the given action function after the responder.

Parameters:

action (callable) – A function of the form func(req, resp, resource), where resource is a reference to the resource class instance associated with the request
*args – Any additional arguments will be passed to action in the order given, immediately following the req, resp and resource arguments.

Keyword Arguments:

**kwargs – Any additional keyword arguments will be passed through to action.

Configuration of Hooks#

falcon.hooks.decorate_on_request = False#

Apply class-level hooks to on_request (and on_request_{suffix}) methods.

This module-level attribute is disabled by default; wrapping default responders with class-level hooks can be enabled by setting the value of decorate_on_request to True:

import falcon.hooks
falcon.hooks.decorate_on_request = True

The value of this attribute must be patched before importing a module where resource classes are actually decorated. In the case setting this value beforehand is not possible, wrapping default responders with class-level hooks can also be enabled by setting the FALCON_DECORATE_ON_REQUEST environment variable to a truthy value. For example:

$ export FALCON_DECORATE_ON_REQUEST=1