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('Bad request', 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:
@falcon.before(extract_project_id)
class Message(object):
def on_post(self, req, resp, project_id):
pass
def on_get(self, req, resp, project_id):
pass
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('Bad request', 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(object):
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.
-
falcon.
before
(action, *args, **kwargs)[source]¶ Decorator to execute the given action function before the responder.
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.Note
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('Invalid ID', 'ID was not valid.') params['answer'] = 42
- *args – Any additional arguments will be passed to action in the order given, immediately following the req, resp, resource, and params arguments.
- **kwargs – Any additional keyword arguments will be passed through to action.
- action (callable) –
-
falcon.
after
(action, *args, **kwargs)[source]¶ Decorator to 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, resource, and params arguments.
- **kwargs – Any additional keyword arguments will be passed through to action.
- action (callable) – A function of the form