pecan/docs/source/hooks.rst

Hooks

Pecan Hooks are a nice way to interact with the framework itself without having to write WSGI middleware.

There is nothing wrong with WSGI Middleware, and actually, it is really easy to use middleware with Pecan, but it can be hard (sometimes impossible) to have access to Pecan's internals from within middleware. Hooks make this easier.

Hooks allow you to execute code at key points throughout the life cycle of your request:

• on_route: called before Pecan attempts to route a request to a controller
• before: called after routing, but before controller code is run
• after: called after controller code has been run
• on_error: called when a request generates an exception

Implementation

In the below example, we will write a simple hook that will gather some information about the request and print it to stdout.

Your hook implementation needs to import PecanHook so it can be used as a base class. From there, you'll need to override the on_route, before, after, or on_error methods:

from pecan.hooks import PecanHook

class SimpleHook(PecanHook):

    def before(self, state):
        print "\nabout to enter the controller..."

    def after(self, state):
        print "\nmethod: \t %s" % state.request.method
        print "\nresponse: \t %s" % state.response.status

on_route, before, and after are each passed a shared state object which includes useful information about the request, such as the request and response object, and which controller was chosen by Pecan's routing.

on_error is passed a shared state object and the original exception.

Attaching Hooks --------------Hooks can be attached in a project-wide manner by specifying a list of hooks in your project's app.py file:

from application.root import RootController
from my_hooks import SimpleHook

app = make_app(
    RootController(),
    hooks = [SimpleHook()]
)

Hooks can also be applied selectively to controllers and their sub-controllers using the __hooks__ attribute on one or more controllers:

from pecan import expose
from my_hooks import SimpleHook

class SimpleController(object):

    __hooks__ = [SimpleHook()]

    @expose('json')
    def index(self):
        print "DO SOMETHING!"
        return dict()

Now that our SimpleHook is included, let's see what happens when we run the app and browse the application from our web browser:

pecan serve config.py
serving on 0.0.0.0:8080 view at http://127.0.0.1:8080

about to enter the controller...
DO SOMETHING!
method:      GET
response:    200 OK