Application Object

There can only be one instance of a diva.core.Application per Python interpreter. That is because the application is in many places accessed via the app singleton, which provides thread-local access to the application context.

Usually a specific application will define a subclass of diva.core.Application that is explicitly instantiated at startup: 

>>> from diva.core import Application
>>> 
>>> class MyApp(Application):
...    pass
... 
>>> myapp = MyApp()

After this point, you'll be able to access the singleton instance of the application using a simple import: 

>>> from diva import app
>>> app
<diva.ApplicationProxy object at …>

This application proxy forwards all operations to the actual application class. The application class has a ctxt property that provides access to various thread-local objects, such as the current HTTP request.

Note though that it's not necessary to actually subclass Application, you can just as well use the base class as-is if you don't need any special behavior.

Initialization with a Configuration File

The Application provides a convenience factory function that lets you instantiate an application using an INI-style configuration file.

For example, assume the following configuration is stored in conf/myapp.ini: 

[app]
locale = en_US
timezone = UTC
doctype = html-strict
debug = true

Now you can easily instantiate your application using the configure() class method: 

>>> from mypkg import MyApp
>>> myapp = MyApp.configure('conf/myapp.ini')

See ConfigOptions for information on the configuration options that are available by default, although you can of course always add your own.

Package Data Conventions

An application can easily avoid explicit configuration of things like the template and locale directories or URL routing by sticking to a directory layout convention that puts these resources in standard paths inside the application package.

The prerequisite for this to work is to specify a class variable called package on the Application subclass, which must be the package name as string. For example: 

>>> from diva.core import Application
>>> 
>>> class MyApp(Application):
...    package = 'mypkg'

With that class variable set, templates, PO/MO translation catalogs, and the routing configuration file are expected in the following directories:

  • mypkg/conf/routing.cfg
  • mypkg/locale (with subdirectories of the form [locale]/LC_MESSAGES)
  • mypkg/templates

Of course these defaults can be overridden by setting the equivalent attributes on the Application class, or by specifying them via the constructor.

Application Context Variables

It should very rarely be necessary to access any of these variables from application-level code, but here's a list of them anyway.

context
The Genshi Context object that contains the data to pass to the template
forms
A list of Form objects created while processing a request (used for form filling)
locale
The Babel Locale object
principal
A Principal object representing the remote user (only when the AuthMixIn is in use)
request
The Request object representing the current HTTP request
response
The Response object representing the current HTTP response
serializer
The Genshi Serializer instance to use for rendering
session
The session dictionary (see SessionState)
template
The Genshi Template object that should be used to render the response
timezone
A tzinfo or pytz.timezone instance
translations
A Babel Translations instance (which is a subclass of GNUTranslations from the standard library)

API Documentation

diva.core

Implementation of the main application object that sets up the application environment and dispatches requests to individual handlers.

Application

WSGI application object that handles a specific project.

__init__(self, routing=None, template_dirs=None, locale_dir=None, **kwargs)

Initialize the application.

param routing:the path to an extra routing configuration file
param template_dirs:
 the template search path for the application
param locale_dir:
 the path to the application localizations

Additional keyword arguments are merged into the configuration dictionary.

init(self)

Subclasses should override this method instead of __init__ to perform any initialization that may be needed after instantiation. This method is called directly before the first request is handled.

The default implementation is empty.

configure(cls, filename, section='app', **kwargs)

Initialize the application based on a configuration file.

The configuration file is expected to be in INI-style format, it is parsed using the Python ConfigParser module.

The section name defaults to "app", but any other name can be used by providing the section parameter.

Additional keyword arguments get merged into the configuration, potentially overwriting options read from the configuration file.

param filename:path to the configuration file
param section:name of the config section
param kwargs:additional configuration options
return:the Application instance

create(cls, global_config, **local_config)

Factory function that is compatible with the PasteDeploy specification for WSGI applications.

mime_types(self)

The MIME types database.

type:MimeTypes

routing(self)

The URL routing.

type:Routing

templates(self)

The template loader.

type:TemplateLoader

__call__(self, environ, start_response)

Called by the WSGI server (or middleware) to make the application process a specific HTTP request.

param environ:the WSGI environment dictionary
param start_response:
 function to call to start the response

cleanup(self, environ)

Called after a request has been processed (successfully or not).

param environ:the WSGI environment dictionary

prepare(self, environ)

Called before processing a request.

param environ:the WSGI environment dictionary

get_filters(self, environ)

Return the list of request filters for the given request.

param environ:the WSGI environment dictionary
return:list of filters to apply
rtype:list

ApplicationMixIn

Abstract base for classes that add functionality at the application level.

contribute_filters(self)

Return a set of request filters that should be applied in addition to the default filters.

return:the set of filter functions
rtype:iterable

register_filter(provides, requires=)

Decorator for registering a request filter.

Request filter registration is used to determine the appropriate order for request filters based on their dependencies.

param provides:a string identifying the service provided by the filter
param requires:a string, or a sequence of strings, identifying services this filter depends on for proper operation