Package cherrypy :: Module _cpconfig
[hide private]
[frames] | no frames]

Module _cpconfig

source code

Configuration system for CherryPy.

Configuration in CherryPy is implemented via dictionaries. Keys are strings
which name the mapped value, which may be of any type.


Architecture
------------

CherryPy Requests are part of an Application, which runs in a global context,
and configuration data may apply to any of those three scopes:

    Global: configuration entries which apply everywhere are stored in
    cherrypy.config.
    
    Application: entries which apply to each mounted application are stored
    on the Application object itself, as 'app.config'. This is a two-level
    dict where each key is a path, or "relative URL" (for example, "/" or
    "/path/to/my/page"), and each value is a config dict. Usually, this
    data is provided in the call to tree.mount(root(), config=conf),
    although you may also use app.merge(conf).
    
    Request: each Request object possesses a single 'Request.config' dict.
    Early in the request process, this dict is populated by merging global
    config entries, Application entries (whose path equals or is a parent
    of Request.path_info), and any config acquired while looking up the
    page handler (see next).


Declaration
-----------

Configuration data may be supplied as a Python dictionary, as a filename,
or as an open file object. When you supply a filename or file, CherryPy
uses Python's builtin ConfigParser; you declare Application config by
writing each path as a section header:

    [/path/to/my/page]
    request.stream = True

To declare global configuration entries, place them in a [global] section.

You may also declare config entries directly on the classes and methods
(page handlers) that make up your CherryPy application via the '_cp_config'
attribute. For example:

    class Demo:
        _cp_config = {'tools.gzip.on': True}
        
        def index(self):
            return "Hello world"
        index.exposed = True
        index._cp_config = {'request.show_tracebacks': False}

Note, however, that this behavior is only guaranteed for the default
dispatcher. Other dispatchers may have different restrictions on where
you can attach _cp_config attributes.


Namespaces
----------

Configuration keys are separated into namespaces by the first "." in the key.
Current namespaces:

    engine:     Controls the 'application engine', including autoreload.
                These can only be declared in the global config.
    tree:       Grafts cherrypy.Application objects onto cherrypy.tree.
                These can only be declared in the global config.
    hooks:      Declares additional request-processing functions.
    log:        Configures the logging for each application.
                These can only be declared in the global or / config.
    request:    Adds attributes to each Request.
    response:   Adds attributes to each Response.
    server:     Controls the default HTTP server via cherrypy.server.
                These can only be declared in the global config.
    tools:      Runs and configures additional request-processing packages.
    wsgi:       Adds WSGI middleware to an Application's "pipeline".
                These can only be declared in the app's root config ("/").
    checker:    Controls the 'checker', which looks for common errors in
                app state (including config) when the engine starts.
                Global config only.

The only key that does not exist in a namespace is the "environment" entry.
This special entry 'imports' other config entries from a template stored in
cherrypy._cpconfig.environments[environment]. It only applies to the global
config, and only when you use cherrypy.config.update.

You can define your own namespaces to be called at the Global, Application,
or Request level, by adding a named handler to cherrypy.config.namespaces,
app.namespaces, or app.request_class.namespaces. The name can
be any string, and the handler must be either a callable or a (Python 2.5
style) context manager.

Classes [hide private]
  NamespaceSet
A dict of config namespace names and handlers.
  Config
The 'global' configuration data for the entire CherryPy process.
  _Parser
Sub-class of ConfigParser that keeps the case of options and that raises an exception if the file cannot be read.
Functions [hide private]
 
as_dict(config)
Return a dict from 'config' whether it is a dict, file, or filename.
source code
 
merge(base, other)
Merge one app config (from a dict, file, or filename) into another.
source code
 
_engine_namespace_handler(k, v)
Backward compatibility handler for the "engine" namespace.
source code
 
_tree_namespace_handler(k, v)
Namespace handler for the 'tree' config namespace.
source code
Variables [hide private]
  environments = {'embedded': {'checker.on': False, 'engine.SIGH...
  __package__ = 'cherrypy'
Function Details [hide private]

merge(base, other)

source code 

Merge one app config (from a dict, file, or filename) into another.

If the given config is a filename, it will be appended to the list of files to monitor for "autoreload" changes.


Variables Details [hide private]

environments

Value:
{'embedded': {'checker.on': False,
              'engine.SIGHUP': None,
              'engine.SIGTERM': None,
              'engine.autoreload_on': False,
              'log.screen': False,
              'request.show_tracebacks': False,
              'tools.log_headers.on': False},
 'production': {'checker.on': False, 'engine.autoreload_on': False, 'l\
...