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.

Version 7 (modified by cmlenz, 16 years ago) (diff)

Document package data conventions

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.

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
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
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

Error: Macro PythonDoc(trunk, diva.core) failed
Unsupported version control system "svn": No module named svn