Application Object

CherryPy collects controllers and handlers into Application objects. You can construct your own cherrypy.Application(root, script_name) objects, or let CherryPy do it behind the scenes for you.

If you're simply using cherrypy.quickstart, you may not be aware that Application objects even exist. But the quickstart function calls tree.mount, which constructs an Application object behind the scenes. If you call tree.mount directly, it will return the Application object to you. Application objects are also available in the tree.apps dict (see below). These are all available as soon as you mount an application.

You can also access the current Application object at runtime via cherrypy.request.app.

Attributes

root

By default, CherryPy uses a nested set of objects to define the URL space of your application. The Application.root should be the top-most object in the set.

script_name

The URL "mount point" for the application. For example, if script_name is "/my/cool/app", then the URL "http://my.domain.tld/my/cool/app/page1" might be handled by a "page1" method on the root object. If script_name is explicitly set to None, then the script_name will be provided for each call from request.wsgi_environ['SCRIPT_NAME'].

config

A dict of {path: pathconf} pairs, where 'pathconf' is itself a dict of {key: value} pairs. Any keys (config file section names) which are not paths (that is, do not start with a slash "/") are considered off-limits to the CherryPy framework. Feel free to define your own keys here for app-specific config.

namespaces

A _cpconfig.NamespaceSet?.

log

A LogManager? instance. See _cplogging.

Using the Application class

One important use case for explicit Application instances is when you want to have various parts of your website do almost the same thing, but not quite. For example, you might have mostly the same application, but want to serve it in both a 'US English' and a 'UK English' format. You could use the Accept-Language header to switch between them, but perhaps you want to be able to link to either version regardless of the browser's language settings, or you want to improve your search engine rankings for each format.

We can accomplish the above by mounting two separate Applications, each with their own root, instead of one:

import gettext

def _(text):
    return gettext.dgettext(cherrypy.request.app.domain, text)


class Root(object):
    
    def index(self):
        return _('Hello world')


class MyApp(cherrypy.Application):
    
    def __init__(self, domain, domaindir, script_name="", config=None):
        self.domain = domain
        self.domaindir = domaindir
        gettext.bindtextdomain(domain, domaindir)
        cherrypy.Application.__init__(self, Root(), script_name, config)

cherrypy.tree.apps['/en_US'] = MyApp('en-us', '/path/to/en-us', '/en_US', appconf)
cherrypy.tree.apps['/en_UK'] = MyApp('en-uk', '/path/to/en-uk', '/en_UK', appconf)

Here we have mounted the same Application class twice, once for each language. The "_" function calls dgettext for thread safety, passing it the language domain for the current request, which is stored on each Application object as "Application.domain".

Tree Object

The Tree class is used to keep track of where multiple applications are mounted. To "mount" an application means to have its root respond to a URL other than "/". By using cherrypy.tree, you can easily mount applications and remember where you mounted them!

mount(root, script_name="", config=None)

Function to mount a set of handlers at the given script_name, using the given configuration dict (or filename). If config is not None, then each of its sections (which should be a relative URL, like "/skins/deepblue/main") will be prefixed with the script_name, so that config lookups are also "mounted" at the base URL.

apps

A dict of the form {script name: application}, where "script name" is a string declaring the URI mount point (no trailing slash), and "application" is an instance of cherrypy.Application (or an arbitrary WSGI callable if you happen to be using a WSGI server).

script_name(path=None)

A method which finds the appropriate script_name for a given path. If path is None or missing, cherrypy.request.script_name is used. If multiple applications "contain" the given path, the longer script_name is returned. That is, if App1 is mounted at "/" and App2 is mounted at "/path/to/app", then cherrypy.tree.script_name("/path/to/app/main") will return "/path/to/app".

Once you have obtained the script_name, you can obtain a reference to the application root object by looking up cherrypy.tree.apps[script_name].root.