Pecan is very easy to configure. As long as you follow certain conventions, using, setting and dealing with configuration should be very intuitive.
Pecan configuration files are pure Python. Each “section” of the configuration is a dictionary assigned to a variable name in the configuration module.
Below is the complete list of default values the framework uses:
server = {
'port' : '8080',
'host' : '0.0.0.0'
}
app = {
'root' : None,
'modules' : [],
'static_root' : 'public',
'template_path' : ''
}
The app configuration values are used by Pecan to wrap your application into a valid WSGI app. The app configuration is specific to your application, and includes values like the root controller class location.
A typical application configuration might look like this:
app = {
'root' : 'project.controllers.root.RootController',
'modules' : ['project'],
'static_root' : '%(confdir)s/public',
'template_path' : '%(confdir)s/project/templates',
'debug' : True
}
Let’s look at each value and what it means:
Warning
app is a reserved variable name for that section of the configuration, so make sure you don’t override it.
Warning
Make sure debug is always set to False in production environments.
See also
Pecan provides some sane defaults. Change these to alter the host and port your WSGI app is served on.
server = {
'port' : '8080',
'host' : '0.0.0.0'
}
Your application may need access to other configuration values at runtime (like third-party API credentials). Put these settings in their own blocks in your configuration file.
twitter = {
'api_key' : 'FOO',
'api_secret' : 'SECRET'
}
You can access any configuration value at runtime via pecan.conf. This includes custom, application, and server-specific values.
For example, if you needed to specify a global administrator, you could do so like this within the configuration file.
administrator = 'foo_bar_user'
And it would be accessible in pecan.conf as:
>>> from pecan import conf
>>> conf.administrator
'foo_bar_user'
In certain situations you might want to deal with keys and values, but in strict dictionary form. The Config object has a helper method for this purpose that will return a dictionary representation of the configuration, including nested values.
Below is a representation of how you can access the to_dict() method and what it returns as a result (shortened for brevity):
>>> from pecan import conf
>>> conf
Config({'app': Config({'errors': {}, 'template_path': '', 'static_root': 'public', [...]
>>> conf.to_dict()
{'app': {'errors': {}, 'template_path': '', 'static_root': 'public', [...]
to_dict() allows you to pass an optional string argument if you need to prefix the keys in the returned dictionary.
>>> from pecan import conf
>>> conf
Config({'app': Config({'errors': {}, 'template_path': '', 'static_root': 'public', [...]
>>> conf.to_dict('prefixed_')
{'prefixed_app': {'prefixed_errors': {}, 'prefixed_template_path': '', 'prefixed_static_root': 'prefixed_public', [...]
Sometimes you want to specify a configuration option that includes dotted keys or is not a valid Python idenfitier, such as (). These situations are especially common when configuring Python logging. By passing a special key, __force_dict__, individual configuration blocks can be treated as native dictionaries.
logging = {
'root': {'level': 'INFO', 'handlers': ['console']},
'loggers': {
'sqlalchemy.engine': {'level': 'INFO', 'handlers': ['console']},
'__force_dict__': True
},
'formatters': {
'custom': {
'()': 'my.package.customFormatter'
}
}
}
from myapp import conf
assert isinstance(conf.logging.loggers, dict)
assert isinstance(conf.logging.loggers['sqlalchemy.engine'], dict)