Supported backends

The following backends are supported as of version 1.2.1:

backend interface

All backends implement the same interface, which allows for easy addition of new (or external backends).

class omniconf.backends.generic.ConfigBackend(conf=None)

Defines a configuration backend, which provides configuration values based on keys.

classmethod autoconfigure(conf, autoconfigure_prefix)

Called with a ConfigRegistry, the result of this method must be either a new instance of this class, or None. This method is automatically called during the autoconfigure phase.

classmethod autodetect_settings(autoconfigure_prefix)

Returns a tuple of Setting objects, that are required for autoconfigure() to complete successfully.

get_value(setting)

Retrieves the value for the given Setting.

get_values(settings)

Retrieves a list of Setting`s all at once. Values are returned as a list of tuples containing the :class:.Setting` and value.

commandline arguments

Command line arguments are implemented using argparse. This backend is enabled by default.

class omniconf.backends.argparse.ArgparseBackend(conf=None, prefix=None)

Uses the current process arguments, and allows values in it to be retrieved using dotted keys with a specific prefix. By default no prefix is assumed.

classmethod autoconfigure(conf, autoconfigure_prefix)

Called with a ConfigRegistry, the result of this method must be either a new instance of this class, or None. This method is automatically called during the autoconfigure phase.

get_value(setting)

Retrieves the value for the given Setting.

get_values(settings)

Process the given list Setting objects, and retrieve the values. Keys are converted as follows:

• Dots are replaced by dashes (-).
• The key is lowercased.
• A prefix is attached to the key, if specified

This means that a key like section.value will be queried like --prefix-section-value. When no prefix is specified, --section-value is queried instead.

Special handling is added for boolean Settings with a default specified, which works as follows:

• Settings with _type=bool and no default will be processed as normal.
• Settings with _type=bool, and where the default value is True will be specified as an argparse argument with action=store_false.
• Settings with _type=bool, and where the default value is False will be specified as an argparse argument with action=store_true.

environment variables

Environments are read from os.environ. This backend is enabled by default.

class omniconf.backends.env.EnvBackend(conf=None, prefix=None)

Uses the current process Environment, and allows values in it to be retrieved using dotted keys with a specific prefix. By default no prefix is assumed.

classmethod autoconfigure(conf, autoconfigure_prefix)

Called with a ConfigRegistry, the result of this method must be either a new instance of this class, or None. This method is automatically called during the autoconfigure phase.

get_value(setting)

Retrieves the value for the given Setting. Keys are converted as follows:

• Dots are replaced by underscores
• The key is uppercased.
• A prefix is attached to the key

This means that a key like section.value will be queried like PREFIX_SECTION_VALUE. When no prefix is specified, SECTION_VALUE is queried instead.

ConfigObj files

Files in ConfigObj format are supported. This backend is only enabled if omniconf.configobj.filename is specified during setup.

class omniconf.backends.configobj.ConfigObjBackend(conf)

Uses a ConfigObj file (or StringIO instance) as a backend, and allows values in it to be retrieved using dotted keys.

Dots in the keys denote a section in the ConfigObj document. For instance, the key section.subsection.key will correspond to this document:

[section]
[[subsection]]
key=value

classmethod autoconfigure(conf, autoconfigure_prefix)

Called with a ConfigRegistry, the result of this method must be either a new instance of this class, or None. This method is automatically called during the autoconfigure phase.

classmethod autodetect_settings(autoconfigure_prefix)

Returns a tuple of Setting objects, that are required for autoconfigure() to complete successfully.

JSON files

Files in JSON format are supported. This backend is only enabled if omniconf.json.filename is specified during setup.

class omniconf.backends.json.JsonBackend(conf)

Uses a JSON string as a backend, and allows values in it to be retrieved using dotted keys.

classmethod autoconfigure(conf, autoconfigure_prefix)

Called with a ConfigRegistry, the result of this method must be either a new instance of this class, or None. This method is automatically called during the autoconfigure phase.

classmethod autodetect_settings(autoconfigure_prefix)

Returns a tuple of Setting objects, that are required for autoconfigure() to complete successfully.

YAML files

Files in YAML format are supported. This backend is only enabled if omniconf.yaml.filename is specified during setup. All YAML documents in the file are consumed.

class omniconf.backends.yaml.YamlBackend(conf)

Uses a YAML string as a backend, and allows values in it to be retrieved using dotted keys.

classmethod autoconfigure(conf, autoconfigure_prefix)

Called with a ConfigRegistry, the result of this method must be either a new instance of this class, or None. This method is automatically called during the autoconfigure phase.

classmethod autodetect_settings(autoconfigure_prefix)

Returns a tuple of Setting objects, that are required for autoconfigure() to complete successfully.

Hashicorp Vault

Hashicorp’s Vault is supported by using its API. This backend requires several configuration keys to be defined during setup, see the documentation below for details.

class omniconf.backends.vault.VaultBackend(conf=None, prefix=None, url=None, auth=None, credentials=None, base_path=None)

Uses Hashicorp’s Vault as a backend, and allows values in it to be retrieved using dotted keys.

Key translation

Dotted keys are translated into an URL path, which is then optionally prepended by the configured backend prefix. The last part of the path is used as a property to retrieve. If a base_path is also configured, it overrides the backend prefix.

For instance, a setting with key setting.foo.bar will be translated into path setting/foo, from which the property with key bar will be retrieved. Because Vault nodes are grouped by backend, it usually makes sense to define base_path as secret, which corresponds to the Generic backend of Vault. In this example, the example key will be translated into path secret/setting/foo, from which the property with key bar will be retrieved.

API Connection

The URL endpoint which omniconf will default to http://localhost:8200, and can be configured using the configuration key omniconf.vault.url, assuming the autoconfigure_prefix is set to omniconf.

Authentication

Vault’s API requires some form of authentication, of which the following are supported:

• Tokens
• TLS certificates
• Username & Password
• LDAP
• App ID
• AppRole

Retrieval of Vault data requires an ACL to be defined, which goes beyond the scope of this documentation. omniconf only needs read rights on the keys it tries to access.

Selection of what authentication method is used depends on which configuration is present during setup. For all the following examples, the autoconfigure_prefix is assumed to be omniconf:

• Token authentication is used if omniconf.vault.auth.token is defined.
• TLS certificates authentication is used if both omniconf.vault.auth.tls.cert.filename and omniconf.vault.auth.tls.key.filename are defined.
• Username and Password authentication is used if both omniconf.vault.auth.userpass.username and omniconf.vault.auth.userpass.password are defined.
• LDAP authentication is used if both omniconf.vault.auth.ldap.username and omniconf.vault.auth.ldap.password are defined.
• App ID authentication is used if both omniconf.vault.auth.appid.app_id and omniconf.vault.auth.appid.user_id are defined.
• AppRole authentication is used if both omniconf.vault.auth.approle.role_id and omniconf.vault.auth.approle.secret_id are defined.

The above order is also the order in which the configuration values are looked up. The first one to satisfy the conditions is used, and no further attepts are made if configuration fails.

classmethod autoconfigure(conf, autoconfigure_prefix)

Called with a ConfigRegistry, the result of this method must be either a new instance of this class, or None. This method is automatically called during the autoconfigure phase.

classmethod autodetect_settings(autoconfigure_prefix)

Returns a tuple of Setting objects, that are required for autoconfigure() to complete successfully.

get_value(setting)

Retrieves the value for the given Setting.