Supported backends

The following backends are supported as of version 1.5.2.dev8:

generic backend interface

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

class omniconf.backends.generic.ConfigBackend

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

abstract classmethod autoconfigure(conf: ConfigRegistry, autoconfigure_prefix: str | None) → ConfigBackend | None

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: str | None) → Sequence[Setting]

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

abstract get_value(setting: Setting) → Any

Retrieves the value for the given Setting.

get_values(settings: Sequence[Setting]) → Sequence[Tuple[Setting, Any]]

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

dict backend interface

For backends that basically work like a dictionary lookup, another generic interface is added that only requires the implementation of passing the loaded config using the conf init parameter and defining the needed autoconfiguration settings.

class omniconf.backends.generic.DictConfigBackend(conf: Mapping[str, Any])

get_value(setting: Setting) → Any

Retrieves the value for the given Setting.

commandline arguments

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

class omniconf.backends.argparse.ArgparseBackend(prefix: str | None = 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: ConfigRegistry, autoconfigure_prefix: str | None) → ConfigBackend | None

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: Setting) → Any

Retrieves the value for the given Setting.

get_values(settings: Sequence[Setting]) → Sequence[Tuple[Setting, Any]]

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(prefix: str | None = 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: ConfigRegistry, autoconfigure_prefix: str | None) → ConfigBackend | None

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: Setting) → Any

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: TextIO)

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: ConfigRegistry, autoconfigure_prefix: str | None) → ConfigBackend | None

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: str | None) → Sequence[Setting]

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: TextIO)

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

classmethod autoconfigure(conf: ConfigRegistry, autoconfigure_prefix: str | None) → ConfigBackend | None

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: str | None) → Sequence[Setting]

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

TOML files

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

class omniconf.backends.toml.TomlBackend(conf: TextIO)

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

classmethod autoconfigure(conf: ConfigRegistry, autoconfigure_prefix: str | None) → ConfigBackend | None

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: str | None) → Sequence[Setting]

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: TextIO)

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

classmethod autoconfigure(conf: ConfigRegistry, autoconfigure_prefix: str | None) → ConfigBackend | None

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: str | None) → Sequence[Setting]

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