Usage¶
Basic usage¶
The most basic usage of omniconf requires the use of the setting()
, config()
and
omniconf_load()
functions:
-
omniconf.
setting
(key, _type=<type 'str'>, required=False, default=None, help=None, registry=None)[source]¶ Register a new
Setting
with the given key.
-
omniconf.
config
(key, registry=None)[source]¶ Retrieves the configured value for a given key. If no specific registry is specified, the value will be retrieved from the default
ConfigRegistry
.
-
omniconf.
omniconf_load
(config_registry=None, backends=None, autoconfigure_prefix=None)[source]¶ Fill the provided
ConfigRegistry
, by default using all available backends (as determined byautoconfigure_backends()
. If noConfigRegistry
is provided, the defaultConfigRegistry
is used. If unset, autoconfigure_prefix will default to “omniconf”.
Define Settings using setting()
:
from omniconf import setting
setting("app.username")
setting("app.hostname")
After defining the Settings, use omniconf_load()
to load values:
from omniconf import omniconf_load
omniconf_load()
Afterwards, you can use config()
to retrieve values.
>>> from omniconf import config
>>> print config.get("app.username")
"user"
By default, all Settings defined using setting()
will be stored as str
. To use another class, do this:
from omniconf import setting
setting("app.firstname", _type=unicode)
setting("app.load_order", _type=list)
Any class can be used. Special cases are added to support dict
, list
, tuple()
and
bool
, which are processed by ast
. The class or function passed to _type will be called with the value
to process as its only parameter.
Advanced usage¶
By default all Settings and Configs are registered in global Registries. These are defined in their respective modules:
-
omniconf.config.
DEFAULT_REGISTRY
= <omniconf.config.ConfigRegistry object>¶ Global
ConfigRegistry
which will be used when no specificConfigRegistry
is defined.
-
omniconf.setting.
DEFAULT_REGISTRY
= <omniconf.setting.SettingRegistry object>¶ Global
SettingRegistry
which will be used when no specificSettingRegistry
is defined.
This allows you to easily define Settings. Sometimes you might want to have specific Settings and Configs however. You can achieve this by specifying your own Registries:
from omniconf.setting import SettingRegistry
from omniconf.config import ConfigRegistry
from omniconf import omniconf_load
settings = SettingRegistry()
configs = ConfigRegistry(setting_registry=settings)
setting("app.username", registry=settings)
omniconf_load(config_registry=configs)
omniconf actually uses this mechanism to build the context needed for autoconfiguring. You can check this out in
autoconfigure_backends()
-
omniconf.loader.
autoconfigure_backends
(autoconfigure_prefix=None)[source]¶ Determine available backends, based on the current configuration available in the environment and command line. Backends can define a
Setting
that is required for proper autodetection.The result of this function is a list of backends, that are configured and ready to use.
Autoconfigure prefix usage¶
Prefixes are used during autoconfiguring step to load Settings, while trying to avoid name clashes with user defined
Settings. By default, omniconf.prefix will be loaded from the environment and cli arguments, by looking for
OMNICONF_PREFIX
and --omniconf-prefix
respectively. In these settings, omniconf is the prefix.
To change the used during autoconfiguring, do the following:
from omniconf import omniconf_load
omniconf_load(config_registry=configs, autoconfigure_prefix="application")
The above example will set the prefix to application, which will cause autoconfiguring to look for
APPLICATION_PREFIX
and --application-prefix
instead. Good if you don’t want to leak that you’re using omniconf
to your users.
Backend prefix usage¶
Backends may allow a prefix to be defined. By default, this setting is loaded from the omniconf.prefix
key (see
previous section). If defined, this value is passed to all available backends, and will influence how they will load
Config values.
For instance. if omniconf.prefix
is not set, EnvBackend
will load some.setting
from the
SOME_SETTING
environment variable. If omniconf.prefix
is set to app
, the value is loaded from
APP_SOME_SETTING
instead. See the Supported backends section for which Backends allow a prefix to be
configured, and how this changes the loading of values.
Prefix usage examples¶
Working with prefixes can be a little tricky. The thing to keep in mind is that there are two prefix types, one that is used during the autoconfigure step where the backends are initialized (the autoconfiguration prefix), and one that is used when loading the configuration (the backend prefix).
Given this code snippet:
from omniconf import omniconf_load, config, setting
setting("db.url", required=True)
omniconf_load(autoconfigure_prefix="test")
print config("db.url")
A step-by-step analysis:
- The setting db.url is defined and marked as required.
- Autoconfiguration is started and the autoconfigure_prefix is defined as ‘test’.
- During autoconfiguration, by default omniconf.prefix will be looked up. Because we override autoconfigure_prefix, test.prefix is looked up instead.
- The contents of test.prefix is used by certain backends (
EnvBackend
in this example) to determine where they should look for their settings.
- Config values are loaded, and the backend prefix is used to determine how it should be loaded.
Example 1¶
$ python test.py
Traceback (most recent call last):
...
omniconf.exceptions.UnconfiguredSettingError: No value was configured for db.url
An error is raised because we don’t set any config values at all, and db.url is marked as required.
Example 2¶
$ TEST_DB_URL=bla python test.py
Traceback (most recent call last):
...
omniconf.exceptions.UnconfiguredSettingError: No value was configured for db.url
An error is raised because we set TEST_DB_URL, but no backend prefix has been configured. The value of db.url is looked up in DB_URL which is not set.
Example 3¶
$ TEST_PREFIX=OTHER OTHER_DB_URL=foo python test.py
foo
The backend prefix is set to OTHER. This means that the setting for db.url is looked up in OTHER_DB_URL, which is also set.
Example 4¶
$ DB_URL=foo python test.py
foo
No backend prefix is set. This means that the setting for db.url is looked up in DB_URL, which is also set.