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

{{{
#!pycon
>>> 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:

{{{
#!pycon
>>> 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`:

{{{
#!ini
[app]
locale = en_US
timezone = UTC
doctype = html-strict
debug = true
}}}

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

{{{
#!pycon
>>> 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:

{{{
#!pycon
>>> 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 [AuthFramework 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
 `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 ==

[[PythonDoc(trunk, diva.core)]]