pecan.hooks – Pecan Hooks

The pecan.hooks module includes support for creating Pecan hooks which are a simple way to hook into the request processing of requests coming into your application to perform cross-cutting tasks.

class pecan.hooks.HookController

Bases: object

A base class for controllers that would like to specify hooks on their controller methods. Simply create a list of hook objects called __hooks__ as a class attribute of your controller.

class pecan.hooks.PecanHook

Bases: object

A base class for Pecan hooks. Inherit from this class to create your own hooks. Set a priority on a hook by setting the priority attribute for the hook, which defaults to 100.

after(state)

Override this method to create a hook that gets called after the request has been handled by the controller.

Parameters:

state – The Pecan state object for the current request.

before(state)

Override this method to create a hook that gets called after routing, but before the request gets passed to your controller.

Parameters:

state – The Pecan state object for the current request.

on_error(state, e)

Override this method to create a hook that gets called upon an exception being raised in your controller.

Parameters:

  • state – The Pecan state object for the current request.

  • e – The Exception object that was raised.

on_route(state)

Override this method to create a hook that gets called upon the start of routing.

Parameters:

state – The Pecan state object for the current request.

class pecan.hooks.RequestViewerHook(config=None, writer=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, terminal=True, headers=True)

Bases: PecanHook

Parameters:

  • config – A (optional) dictionary that can hold items and/or blacklist keys.

  • writer – The stream writer to use. Can redirect output to other streams as long as the passed in stream has a write callable method.

  • terminal – Outputs to the chosen stream writer (usually the terminal)

  • headers – Sets values to the X-HTTP headers

Returns some information about what is going on in a single request. It accepts specific items to report on but uses a default list of items when none are passed in. Based on the requested url, items can also be blacklisted. Configuration is flexible, can be passed in (or not) and can contain some or all the keys supported.

items

This key holds the items that this hook will display. When this key is passed only the items in the list will be used. Valid items are any item that the request object holds, by default it uses the following:

  • path

  • status

  • method

  • controller

  • params

  • hooks

Note

This key should always use a list of items to use.

blacklist

This key holds items that will be blacklisted based on url. If there is a need to omit urls that start with /javascript, then this key would look like:

'blacklist': ['/javascript']

As many blacklisting items as needed can be contained in the list. The hook will verify that the url is not starting with items in this list to display results, otherwise it will get omitted.

Note

This key should always use a list of items to use.

For more detailed documentation about this hook, please see RequestViewerHook

after(state)

Override this method to create a hook that gets called after the request has been handled by the controller.

Parameters:

state – The Pecan state object for the current request.

format_hooks(hooks)

Tries to format the hook objects to be more readable Specific to Pecan (not available in the request object)

get_controller(state)

Retrieves the actual controller name from the application Specific to Pecan (not available in the request object)

class pecan.hooks.TransactionHook(start, start_ro, commit, rollback, clear)

Bases: PecanHook

Parameters:

  • start – A callable that will bind to a writable database and start a transaction.

  • start_ro – A callable that will bind to a readable database.

  • commit – A callable that will commit the active transaction.

  • rollback – A callable that will roll back the active transaction.

  • clear – A callable that will clear your current context.

A basic framework hook for supporting wrapping requests in transactions. By default, it will wrap all but GET and HEAD requests in a transaction. Override the is_transactional method to define your own rules for what requests should be transactional.

after(state)

Override this method to create a hook that gets called after the request has been handled by the controller.

Parameters:

state – The Pecan state object for the current request.

before(state)

Override this method to create a hook that gets called after routing, but before the request gets passed to your controller.

Parameters:

state – The Pecan state object for the current request.

is_transactional(state)

Decide if a request should be wrapped in a transaction, based upon the state of the request. By default, wraps all but GET and HEAD requests in a transaction, along with respecting the transactional decorator from :mod:pecan.decorators.

Parameters:

state – The Pecan state object for the current request.

on_error(state, e)

Override this method to create a hook that gets called upon an exception being raised in your controller.

Parameters:

  • state – The Pecan state object for the current request.

  • e – The Exception object that was raised.

on_route(state)

Override this method to create a hook that gets called upon the start of routing.

Parameters:

state – The Pecan state object for the current request.