Usage

Basic usage

The most basic usage of omniconf requires the use of the setting(), config() and omniconf_load() functions:

omniconf.setting(key: str, _type: ~typing.Callable[[...], ~typing.Any] = <class 'str'>, required: bool = False, default: ~typing.Any | None = None, help: str | None = None, registry: ~omniconf.setting.SettingRegistry | None = None, type_hint: ~typing.Type[~typing.Any] | None = None) Setting[source]

Register a new Setting with the given key.

omniconf.config(key: str, registry: ConfigRegistry | None = None) Any | 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: ConfigRegistry | None = None, backends: Sequence[ConfigBackend] | None = None, autoconfigure_prefix: str | None = None) None[source]

Fill the provided ConfigRegistry, by default using all available backends (as determined by autoconfigure_backends(). If no ConfigRegistry is provided, the default ConfigRegistry 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("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. See Setting types for more information.

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 specific ConfigRegistry is defined.

omniconf.setting.DEFAULT_REGISTRY = <omniconf.setting.SettingRegistry object>

Global SettingRegistry which will be used when no specific SettingRegistry 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: str | None = None) List[ConfigBackend][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:

  1. The setting db.url is defined and marked as required.

  2. Autoconfiguration is started and the autoconfigure_prefix is defined as ‘test’.

    1. During autoconfiguration, by default omniconf.prefix will be looked up. Because we override autoconfigure_prefix, test.prefix is looked up instead.

    2. The contents of test.prefix is used by certain backends (EnvBackend in this example) to determine where they should look for their settings.

  3. 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.

Outputting usage information

To output argparse-like usage information based on Setting objects contained in a SettingRegistry, use the show_usage() function.

omniconf.show_usage(setting_registry: SettingRegistry | None = None, name: str | None = None, top_message: str | None = None, bottom_message: str | None = None, out: TextIO | None = None, exit: int = 0) None[source]

Prints usage information based on Setting objects in the given SettingRegistry. If no setting_registry is specified, the default SettingRegistry is used.

If no name is specified, sys.argv[0] is used. Additionally, a header and footer message may be supplied using top_message and bottom_message message respectively.

By default the usage information is output to sys.stderr. This can be overidden by specifying a different File-like object to out.

By default, this function will call sys.exit and stop the program with exit code 0. This can be overridden by a specifying different value to exit. Set to False to not exit.

For instance, the output for this piece of code:

from omniconf import setting, show_usage

setting("verbose", _type=bool, default=False, help="Enable verbose mode.")
setting("section1.setting", help="An optional setting")
setting("section1.other_setting", help="A different optional setting.")
setting("section2.setting", required=True, help="A required setting.")

show_usage(name="usage_example")

Looks like this:

usage: usage_example [--verbose] [--section1-other_setting SOS]
                  [--section1-setting SS] --section2-setting SS

optional arguments:
--verbose             Enable verbose mode.

section1:
--section1-other_setting SOS
                     A different optional setting.
--section1-setting SS
                     An optional setting

section2:
--section2-setting SS
                     A required setting.

An user who wants to show usage information, usually specifies a command line flag like --help. To detect this, omniconf provides a convenience method:

omniconf.help_requested() bool[source]

Returns True if -h or –help was specified on the command line.

Two other methods are also provided, one to detect a version flag, and one to detect any flag:

omniconf.version_requested() bool[source]

Returns True if -v or –version was specified on the command line.

omniconf.flag_requested(flags: Sequence[str]) bool[source]

Returns True if the specified list of flags were specified on the command line.