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

diva.http

Various objects and functions for working with HTTP exchanges.

abort(status, message='', headers=None)

Aborts the request processing immediately by raising an HTTP exception corresponding to the specified status code.

>>> abort(404)
Traceback (most recent call last):
  ...
HTTPNotFound: 404 Not Found
Content-Type: text/html; charset=UTF-8
Content-Length: 0
<BLANKLINE>
<BLANKLINE>

>>> abort(301, headers=[('Location', 'http://example.org/')])
Traceback (most recent call last):
  ...
HTTPMovedPermanently: 301 Moved Permanently
Content-Type: text/html; charset=UTF-8
Content-Length: 0
Location: http://example.org/
<BLANKLINE>
<BLANKLINE>
param status:the HTTP status code
param message:an optional message to be displayed to the user (for example on the error page)
param headers:a list of (name, value) tuples that define any headers that should be included with the response

allow(*methods)

Decorator for request handlers that handle only requests using the specified methods.

Requests using a method not in the allowed list result in a 405 Method Not Allowed error response.

Note that allowing GET implies allowing HEAD.

param methods:the allowed request methods as strings

caching(max_age=None, vary_on=None, **options)

Decorator that allows controlling HTTP headers related to caching.

param max_age:the maximum number of seconds the output should be cached
param vary_on:a list of HTTP header names that should be taken into account by cache
keyword options:
 any additional keyword arguments are added to the "Cache-Control" header of the response if they have a truth value; for example, must_revalidate=1 would add the "must-revalidate" flag to the header

match(etag=None, last_modified=None)

Checks the current request for conditional GET semantics based on the "If-Modified-Since" and/or "If-None-Match" headers.

If the request includes one of those headers, and their value matches the given parameters, a "204 Not Modified" response is sent. Otherwise, the headers "Last-Modified" and/or "ETag" are headers are added to the response.

param etag:the entity tag value
param last_modified:
 the last modification date (either as a datetime object or as a numeric timestamp)

caching_filter(request, response, chain)

Request filter that adds standard cache disabling headers to responses that have no explicit cache control.

diva.templating

Helpers for templating and output serialization using the Genshi template engine.

output(templatename=None, method=None, mimetype=None, encoding=None, **options)

Decorator to specify template and output serialization.

param templatename:
 the name of the template file
param method:the serialization method (one of "xml", "xhtml", "html", or "text")
param mimetype:the content-type of the generated output
param encoding:the encoding (character set) of the generated output

classes(**args, *kwargs)

Helper function for dynamically assembling a list of CSS class names in templates.

Any positional arguments are added to the list of class names. All positional arguments must be strings:

>>> classes('foo', 'bar')
u'foo bar'

In addition, the names of any supplied keyword arguments are added if they have a truth value:

>>> classes('foo', bar=True)
u'foo bar'
>>> classes('foo', bar=False)
u'foo'

If none of the arguments are added to the list, this function returns None:

>>> classes(bar=False)

group(iterable, num, predicate=None)

Combines the elements produced by the given iterable so that every num items are returned as a tuple.

>>> items = [1, 2, 3, 4]
>>> for item in group(items, 2):
...     print item
(1, 2)
(3, 4)

The last tuple is padded with None values if its' length is smaller than num.

>>> items = [1, 2, 3, 4, 5]
>>> for item in group(items, 2):
...     print item
(1, 2)
(3, 4)
(5, None)

The optional predicate parameter can be used to flag elements that should not be packed together with other items. Only those elements where the predicate function returns True are grouped with other elements, otherwise they are returned as a tuple of length 1:

>>> items = [1, 2, 3, 4]
>>> for item in group(items, 2, lambda x: x != 3):
...     print item
(1, 2)
(3,)
(4, None)
param iterable:the iterable to group
param num:the number of items to pack into each tuple
param predicate:
 an optional function called with the current item on every iteration; if the function returns False that item is emitted as a singleton tuple

separated(items, separator=', ')

Separates a sequence of items by the specified string.

>>> list(separated(['Peter', 'Paul', 'Mary']))
[('Peter', ', '), ('Paul', ', '), ('Mary', None)]

>>> list(separated([]))
[]
param items:the iterable to separate
param separator:
 the string (or other object) to use to separate the items

render(**args, *kwargs)

Render the data given as keyword arguments using the selected template.

The template can be specified either by using the output decorator, or by passing the name of the template file as first argument to this function.

Any keyword arguments are passed on into the template context. They will be available for use in templates, in addition to the various default variables (such as the request and response objects).

prepare_context(**kwargs)

(Not documented)

serialize(stream)

(Not documented)

template_filter(request, response, chain)

Request filter that serializes a Genshi template output stream.

view(request, response, template)

Generic request handler that renders a template with only the default data.

param request:the request object
param response:the response object
param template:the file name of the template