Request Handlers
A request handler is a neutral name for what some other frameworks call “controllers” or “views”. It is simply a Python function that accepts the request and response objects as parameters, and processes the request to generate a response in one way or another.
from diva.templating import output, render @output('index.html') def index(request, response): return render(message='Hello, world!')
This defines a function called index that will respond to requests by rendering the template index.html.
URL Parts as Parameters
Any dynamic parts of the URLs defined in the UrlRouting are passed to the request handler as additional parameters. For example:
from datetime import datetime from diva import app from diva.templating import output, render @output('index.html') def monthly(request, response, year, month): return render(month=datetime(year, month, 1)) app.routing.add('/archives/{year:\d+}/{month:\d+}/', monthly)
Note that in this particular case, the values for year and month are automatically converted to numbers, due to the use of the \d+ pattern in the route path.
Rendering Genshi Templates
The diva.templating module provides convenience functions for rendering Genshi templates.
First, there's the @output decorator, which you use to specify the name of the template file, the serialization method, the response MIME type and encoding, and other serialization options such as the DOCTYPE to use and so on.
from diva.templating import output, render @output('index.html', method='html', doctype='html-strict') def index(request, response): return render(message='Hello, world!')
Note that all of the arguments to @output are optional. For example, you can omit the template file name for a response that doesn't involve template rendering, and just use the mimetype and encoding options:
@caching(max_age=timedelta(days=7)) @output(mimetype='text/css', encoding='utf-8') def style(request, response, font_size=1): return 'html { font-size: %sem; }' % font_size
If you do want to render a template, use the render() function to return a Genshi stream from the request handler. You pass any template data into the render() function as keyword arguments, and it will generate an output stream from the template based on the template data. The render() function also lets you override the template filename specified using the @output decorator: simply pass the template name as the first (and only) positional argument into render().
Default Template Data
Diva makes a number of objects available for use in Genshi templates by default:
- app
- The Application object
- abs_url()
- Function for converting relative paths to absolute URLs
- attrgetter
- Function from the Python operator module
- classes()
- Helper function to generate CSS class names for use in HTML templates
- date
- Python date class from the datetime module
- datetime
- Python datetime class from the datetime module
- _() / gettext()
- Function for translating a message
- HTML()
- Function to parse a string as HTML and return a markup stream
- group()
- Helper function for splitting flat lists up into groups of items (like columns)
- groupby()
- Function from the Python itertools module
- itemgetter
- Function from the Python operator module
- ngettext()
- Function for translating a message including plural forms
- path_to()
- Function for generating URLs based on the routing configuration
- request
- The Request object (as provided by the webob package)
- response
- The Response object (as provided by the webob package)
- separated()
- Helper function that converts a list of strings into a single string with added separators
- time
- Python time class from the datetime module
- timedelta
- Python timedelta class from the datetime module
- truncate()
- Helper function that truncates a string to a specified limit of characters, taking word boundaries into account
- XML()
- Function to parse a string as XML and return a markup stream
Builtin Request Handlers
Diva comes with a couple of generic request handlers that can be used as-is with some parameterization in UrlRouting.
- diva.auth:login
- Handle a form-based authentication request
- diva.auth:logout
- Clears a previously set authentication cookie
- diva.routing:delegate
- Delegate request processing to a different WSGI application
- diva.routing:redirect
- Send an HTTP redirect to a different URL
- diva.static:directory
- Serve static files from a specific directory
- diva.static:file
- Serve a specific static file
- diva.templating:view
- Render a given template with the default context data
API Documentation
