Configuration ¶

Tipfy has a configuration system that is used internally to configure its modules, but that can also be used to configure any modules in your application. The configuration is defined in a dictionary, normally stored in config.py. This dictionary is passed to the WSGI application constructor. It looks like this:

config.py

config = {}

config['tipfy.ext.i18n'] = {
    # Change default values from the internalization module.
    'locale':   'pt_BR',
    'timezone': 'America/Sao_Paulo',
}

config['tipfy.ext.session'] = {
    'secret_key': 'my_secret_key',
}

As you see, the configuration is divided per module name, and each module configuration is another dictionary. It is easy to find out which configuration keys are available in the module documentation: all tipfy modules that are configurable have the config keys described in their page in the API Docs as default_config.

This per-module configuration avoids collisions if two modules have the same configuration key, and allows you to easily add configuration values for your own modules without worrying about name clashes. But the best is that modules can provide default values for their configurable options, in most cases making configuration entirely optional.

Accessing configuration values¶

To read the configured values for your app, you use the function get_config(). It will return the value defined in config.py, or if not set load the default value for the module. You need to specify the module name and configuration key:

from tipfy import get_config

default_locale = get_config('tipfy.ext.i18n', 'locale')

And optionally you can pass a default value to be used in case the configuration is not set:

default_locale = get_config('tipfy.ext.i18n', 'locale', 'pt_BR')

Additionally, you can get all the configuration for a module (it is a simple dictionary), then use the keys one by one:

config = get_config('tipfy.ext.i18n')
locale = config.get('locale', 'pt_BR')
timezone = config.get('timezone')

Making your own modules configurable¶

The configuration system can also be used to configure any modules in your application. This is useful if you will distribute your app or if you will deploy it multiple times and want to set some flexibility points.

To configure a module, you simply set values for it in config:

config.py

config = {}

config['my_app.my_module'] = {
    'some_key':       'some_value',
    'some_other_key': 'some_other_value',
}

Then in your code you can access those values:

some_key = get_config('my_app.my_module', 'some_key')
some_other_key = get_config('my_app.my_module', 'some_other_key')

And what happens when you access those values and they are set in config? Well, an error will occur, as values that don't have a default to be used raise an exception. You can avoid this passing a default value when requesting the configuration:

some_key = get_config('my_app.my_module', 'some_key', 'some_default_value')
some_other_key = get_config('my_app.my_module', 'some_other_key', 'some_other_default_value')

Or even better: set the default configuration values in your module. You can do this defining a default_config global variable in the module:

my_app/my_module.py

#: Default configuration values for this module. Keys are:
#: - ``some_key``: Some configuration description. Default is 
#:   'some_default_value'.
#: - ``some_other_key``: Some other configuration description. Default is 
#:   'some_other_default_value'.
default_config = {
    'some_key':       'some_default_value',
    'some_other_key': 'some_other_default_value',
}

The configuration system will load these default values automatically when you request a configuration from this module, even if you don't pass a default. This makes easier to document configurable values, and you'll always know what configuration a module accepts by looking at its default_config variable.

• Version: latest
• Edited by moraes on 7/2/10 6:54 AM
• Save on Delicious | Submit to Reddit
• History
• Edit