Configuration Providers¶
A Configuration Provider implements
ConfigProviderBase
, allowing it to be
registered by a ProviderManager
and thereby
included in a ConfigurationRegistry
.
Two such Providers are included in this package:
The
EnvironmentProvider
parses environment variables for configuration data.The
FilesystemProvider
parses json or yaml files for configuration data.
Any provider implementing ConfigProviderBase
can be added to the registry by calling the
register()
method on the registry’s
manager
.
Environment Provider¶
The EnvironmentProvider
attempts to
automatically parse configuration data for your application from environment
variables.
Environment variables matching the pattern APP__.*
are
automatically read into the configuration, where APP
refers to
the uppercased name
given to your registry at creation.
You can customize this behavior by creating your own instance of an
EnvironmentProvider
.
By default __
(double-underscore) is parsed as a hierarchical separator.
After stripping the application prefix from the variable name, the __
is effectively equivalent to a .
in dotted-path notation e.g.
APP__GLOBAL__THINGS
is equivalent to global.things
, which is the same
as {"global": {"things": {}}}
.
You can customize the string used as hierarchical separator, replacing
__
with a string of your choosing, by passing alevel_separator
keyword argument to yourEnvironmentProvider
, e.g.provider = EnvironmentProvider(level_separator='____')
(four underscores). Bear in mind that environment variable keys are limited to alphanumeric ASCII characters and underscores (no hyphens, dots, or other punctuation), and must start with a letter.NOTE: Avoid using the value of
level_separator
in your configuration keys (names), as this will confuse the provider’s parsing.
String values of “true” or “false” (in any combination of upper/lower case) are cast to python booleans by default.
To disable this behavior, pass
cast_bool=False
to theEnvironmentProvider
constructor.
Values that are enclosed in square brackets are parsed as comma-separated
lists by default. For example, if you export APP__FOO="[a, b, c]"
the
parsed value of foo will be a python list, ['a', 'b', 'c']
.
You can disable list parsing by passing
value_split=False
to to theEnvironmentProvider
constructor, in which case the above would return a python string:"[a, b, c]"
.You can customize the value separator by passing a
value_separator
keyword to theEnvironmentProvider
constructor. The separator is treated as a regex, so you can use e.g.value_separator=r'\s+'
to split on whitespace instead of the default comma.
Filesystem Provider¶
The FilesystemProvider
searches a list
of filesystem paths for JSON or YAML configuration files, parses the first one
that it finds, and stores the configuration in memory until its update()
method
is called again.
If a list of paths is not specified, the provider will search for files as follows:
$HOME/.local/etc/{prefix}/{prefix}.(json|yaml|yml)
/etc/{prefix}/{prefix}.(json|yaml|yml)
The list of paths is stored as a list on the provider’s
path
attribute, and
can be manipulated just like any other list to add or remove paths to search.