The Viverra core module contains the central machinery -- the Request class, the Response classes, the UrlMap resolver, and the entrypoint function that actually acts as the application resolving and dispatching engine.

The Request Object

The Viverra request object is designed to be a simple, friendly packaging of request information -- created from the environment specific to each request (with the mod_python server backend, directly from the Apache request context). If any Viverra middleware is active, the Viverra-specific environment keys present are extracted and made available directly on the request object.

Important attributes set on the request include request.path (the full path which was requested); request.method (the HTTP method used for the request, such as GET or POST); request.env (a dictionary representing the complete request environment); and request._headers (the HTTP headers received as part of the request). The common Viverra form and cookie middleware, if present, make available the request.form dictionary-like object and the request.cookie dictionary-like object, respectively.

Response Classes

A Viverra response object represents an HTTP response, as well as a plethora of shortcuts to ensure that application code can easily and intuitively generate correctly formed responses. Response objects have a body, which can be manipulated by writing to the Response as if it were a file; they have headers, which can be set and unset from code and map directly onto the underlying protocol; and they have an HTTP status, which is typically set automatically based on the Response type that is chosen. The base Response class also provides convenience methods to set cookies (generating and setting the appropriate HTTP headers) as well as setting redirects.

A rich library of response types is available in the Viverra core, each a subclass of Response, with all the functionality of the base class and some conveniences based on its intended usage. For instance, a Redirect response can be constructed directly with a location for the client to be redirected to, and the appropriate status and headers will be returned.

Perhaps most important, however, is Viverra's concept of HTTP errors -- each also subclasses Response, so that simply raising an appropriate exception (such as UnauthorizedError to signal a locked resource) returns meaningful information to the client (see below for more details).

URL Resolution

See the configuration documentation for details of how mappings are set up; the Viverra core uses the details from viverra.config to connect URL paths to callables appropriately.

The Core 'Application'

The entry point to Viverra is implemented as a WSGI application, and is typically called by the server handler; Viverra application code should not even need to know of its existence. It creates a Request from the passed-in request environment, determines which callable is responsible for the request (using the URL mappings discussed above) and calls it with the request object and any additional arguments as described in the configuration section. In the case of any errors being raised (including an inability to find a callable responsible for the path), it looks for an appropriate handler among the configured error handlers (or falls back to a default implementation), and calls that with the request object. Finally, once it has a response (either a Response object or a string or Unicode object), it examines it for error statuses and jumps through the hoops of the WSGI specification to return response headers and then return the response itself through the middleware chain.