Configuration Registry

The ConfigurationRegistry is the main entry point into the library and the class developers will interact with most frequently.

Default Behavior

Its constructor requires a single argument: a name that will be used to identify and namespace the configuration (the name of your application is usually a good choice).

With no additional arguments, the constructor will return a registry with a FilesystemProvider and an EnvironmentProvider configured to sane defaults, which will consider the following configuration sources in order:

• default values provided by the developer:

  • defaults passed in to the ConfigurationRegistry constructor

  • programmatic calls to the registry’s set_default() method

• the first JSON or YAML configuration file found from:

  • $HOME/.local/etc/{name}/{name}.(json|yaml|yml)

  • /etc/{name}/{name}.(json|yaml|yml)

• environment variables in the {NAME}__ namespace

• developer overrides via the registry’s set() method

Providers

The registry merges configurations from a set of providers. These providers are managed by a ProviderManager, which is attached to the registry as its providers attribute.

To disable or customize the default providers, you can pass the registry constructor your own list of providers (which can be empty). For example, cf = ConfigurationRegistry("app", providers=[]) will create a configuration registry that only manages default values and developer overrides.

Alternatively, you can call the register() or deregister() methods on the registry’s provider manager to add or remove a provider (e.g. cf.providers.deregister("environment")).

Provider Values

Each provider is required to implement an update() method that will trigger it to read its configuration from the source and update itself accordingly.

In the case of the FilesystemProvider, for example, the update() method causes the provider to read the first configuration file it finds from the filesystem.

Always call update() on your registry after constructing it. This will call each provider’s update() method, which some providers require.

Getting Values

A dictionary of merged configuration values is available as the registry’s dict property.

An individual value can be retrieved using the get() method, which takes a configuration key as its argument and returns the value in its stored type.

Additional helper functions to cast the value to various types are included (e.g. get_bool()).