close Warning: Can't synchronize with repository "(default)" (Unsupported version control system "svn": No module named svn). Look in the Trac log for more information.

Changes between Initial Version and Version 1 of RequestFilters


Ignore:
Timestamp:
Jun 25, 2008, 1:52:52 PM (14 years ago)
Author:
cmlenz
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • RequestFilters

    v1 v1  
     1= Request Filters =
     2
     3Request filters are Python functions that can act on the request/response before/after the actual [RequestHandlers request handler] is invoked. The application establishes a chain of request filters that are to be applied. Request filters generally look as follows:
     4
     5{{{
     6#!python
     7def my_filter(request, response, chain):
     8    # Here you do anything you need to do before the request handler kicks in
     9    try:
     10        return chain.next()(request, response, chain)
     11    finally:
     12        # Here you do anything you want after the request handler has processed the request
     13}}}
     14
     15The `chain` parameter is simply an iterator over the request filter functions, and the last function is the actual request handler.
     16
     17A 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.
     18
     19== Default Request Filters ==
     20
     21The following request filters are available by default unless you remove them:
     22
     23 `diva.errors.error_filter`:: Intercepts exceptions and displays either a friendly error page or the debugging page
     24 `diva.templating.template_filter`:: Serializes Genshi template output streams
     25 `diva.ui.chrome.chrome_filter`:: Injects any programmatically added scripts, style sheets, and links into the output stream
     26 `diva.i18n.l10n_filter`:: Handles locale negotiation and makes the corresponding translations catalog available
     27 `diva.http.caching_filter`:: Adds default cache control headers to responses
     28 `diva.forms.form_filter`:: Automatically populates HTML forms from previously entered data, and provides optional CSRF protection
     29
     30== Setting up Request Filters ==
     31
     32To customize which request filters are run, you can override the `get_filters()` method of the `Application` class. For example:
     33
     34{{{
     35#!python
     36from diva.core import Application
     37from diva.errors import error_filter
     38from diva.http import caching_filter
     39from diva.templating import template_filter
     40
     41class MyApp(Application):
     42
     43    def get_filters(self, environ):
     44        return [
     45            error_filter,
     46            template_filter,
     47            caching_filter
     48        ]
     49}}}
     50
     51This implementation removes a number of the default filters. You could also add any custom filters you may have, etc.
     52
     53Note that the ordering of request filters is quite important. For example, if you insert your custom filter before the `error_filter`, an exception raised in your filter function will not result in a friendly error page, but rather see the exception propagated all the way up. If you insert your filter before the `template_filter`, you will not get a Genshi stream as return value of the next function in the chain, but rather the rendered text.
     54
     55Generally it makes the most sense to add custom filters close to the end of the list.
     56
     57== When to Use Request Filters ==
     58
     59Some 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.
     60
     61A good rule of thumb is that request filters are better suited if the functionality needs access to parts of the application or framework.
     62