Request filters are Python functions that can act on the request/response before/after the actual request handler is invoked. The application establishes a chain of request filters that are to be applied. Request filters generally look as follows:
from diva.core import register_filter @register_filter('mine', requires='error-handling') def my_filter(request, response, chain): # Here you do anything you need to do before the request handler kicks in try: return chain.next()(request, response, chain) finally: # Here you do anything you want after the request handler has processed the request pass
The chain parameter is simply an iterator over the request filter functions, and the last function is the actual request handler.
A request filter can of course also manipulate the return value of the handler. For example, if the return value is a Genshi markup stream, it could apply stream filters.
The @register_filter decorator is used to determine the order in which filters are applied. The first argument defines the abstract service provided by the filter, while dependencies on other filters are specified with the requires argument.
Default Request Filters
The following request filters are active by default unless you remove them:
- diva.errors.error_filter (“error-handling”)
- Intercepts exceptions and displays either a friendly error page or the debugging page
- diva.templating.template_filter (“templating”)
- Serializes Genshi template output streams
- diva.i18n.l10n_filter (“localization”)
- Handles locale negotiation and makes the corresponding translations catalog available
- diva.http.caching_filter (“caching”)
- Adds default cache control headers to responses
- diva.forms.form_filter (“form-processing”)
- Automatically populates HTML forms from previously entered data, and provides optional CSRF protection
- diva.session.session_filter (“session”)
- Makes a session dictionary available to the application, and loads/stores the session data from/to a cookie.
In addition, the following request filters are available but not enabled by default:
- diva.auth.authn_filter (“authentication”)
- Performs HTTP or cookie-based authentication
Setting up Request Filters
To customize which request filters are run, you can override the get_filters() method of the Application class. For example:
from diva.core import Application from diva.errors import error_filter from diva.http import caching_filter from diva.templating import template_filter class MyApp(Application): def get_filters(self, environ): return [ error_filter, template_filter, caching_filter ]
This implementation removes a number of the default filters. You could also add any custom filters you may have, etc.
When to Use Request Filters
Some things that you may be tempted to implement as request filters would be better done by using WSGI middleware or features of the web server. For example, GZIP compression is available in Apache as a module, and there are various implementations of GZIP compression as WSGI middleware.
A good rule of thumb is that request filters are better suited if the functionality needs access to parts of the application or framework.