donfig package¶
Submodules¶
donfig.config_obj module¶
-
class
donfig.config_obj.
Config
(name, defaults=None, paths=None, env=None, env_var=None, root_env_var=None, env_prefix=None)[source]¶ Bases:
object
-
collect
(paths=None, env=None)[source]¶ Collect configuration from paths and environment variables
Parameters: Returns: config
Return type: See also
donfig.Config.refresh()
- collect configuration and update into primary config
-
ensure_file
(source, destination=None, comment=True)[source]¶ Copy file to default location if it does not already exist
This tries to move a default configuration file to a default location if if does not already exist. It also comments out that file by default.
This is to be used by downstream modules that may have default configuration files that they wish to include in the default configuration path.
Parameters: - source (string, filename) – Source configuration file, typically within a source directory.
- destination (string, directory) – Destination directory. Configurable by
<CONFIG NAME>_CONFIG
environment variable, falling back to ~/.config/<config name>. - comment (bool, True by default) – Whether or not to comment out the config file when copying.
-
expand_environment_variables
()[source]¶ Expand any environment variables in this configuration in-place.
See
expand_environment_variables()
for more information.
-
get
(key, default='__no_default__')[source]¶ Get elements from global config
Use ‘.’ for nested access
Examples
>>> from donfig import Config >>> config = Config('mypkg') >>> config.get('foo') # doctest: +SKIP {'x': 1, 'y': 2}
>>> config.get('foo.x') # doctest: +SKIP 1
>>> config.get('foo.x.y', default=123) # doctest: +SKIP 123
See also
donfig.Config.set()
-
merge
(*dicts)[source]¶ Merge this configuration with multiple dictionaries.
See
merge()
for more information.
-
refresh
(**kwargs)[source]¶ Update configuration by re-reading yaml files and env variables.
This goes through the following stages:
- Clearing out all old configuration
- Updating from the stored defaults from downstream libraries (see update_defaults)
- Updating from yaml files and environment variables
Note that some functionality only checks configuration once at startup and may not change behavior, even if configuration changes. It is recommended to restart your python process if convenient to ensure that new configuration changes take place.
See also
donfig.Config.collect()
- for parameters
donfig.Config.update_defaults()
-
rename
(aliases)[source]¶ Rename old keys to new keys
This helps migrate older configuration versions over time
-
set
(arg=None, **kwargs)[source]¶ Set configuration values within a context manager.
Parameters: - arg (mapping or None, optional) – A mapping of configuration key-value pairs to set.
- **kwargs – Additional key-value pairs to set. If
arg
is provided, values set inarg
will be applied before those inkwargs
. Double-underscores (__
) in keyword arguments will be replaced with.
, allowing nested values to be easily set.
Examples
>>> from donfig import Config >>> config = Config('mypkg')
Set
'foo.bar'
in a context, by providing a mapping.>>> with config.set({'foo.bar': 123}): ... pass
Set
'foo.bar'
in a context, by providing a keyword argument.>>> with config.set(foo__bar=123): ... pass
Set
'foo.bar'
globally.>>> config.set(foo__bar=123) # doctest: +SKIP
See also
donfig.Config.get()
-
to_dict
()[source]¶ Return dictionary copy of configuration.
Warning
This will copy all keys and values. This includes values that may cause unwanted side effects depending on what values exist in the current configuration.
-
-
class
donfig.config_obj.
ConfigSet
(config, lock, arg=None, **kwargs)[source]¶ Bases:
object
Temporarily set configuration values within a context manager
Note, this class should be used directly from the Config object via the
donfig.Config.set()
method.Examples
>>> from donfig.config_obj import ConfigSet >>> import mypkg >>> with ConfigSet(mypkg.config, {'foo': 123}): ... pass
See also
donfig.Config.set
,donfig.Config.get
-
donfig.config_obj.
canonical_name
(k, config)[source]¶ Return the canonical name for a key.
Handles user choice of ‘-’ or ‘_’ conventions by standardizing on whichever version was set first. If a key already exists in either hyphen or underscore form, the existing version is the canonical name. If neither version exists the original key is used as is.
-
donfig.config_obj.
collect_env
(prefix, env=None)[source]¶ Collect config from environment variables
This grabs environment variables of the form “DASK_FOO__BAR_BAZ=123” and turns these into config variables of the form
{"foo": {"bar-baz": 123}}
It transforms the key and value in the following way:- Lower-cases the key text
- Treats
__
(double-underscore) as nested access - Calls
ast.literal_eval
on the value
-
donfig.config_obj.
collect_yaml
(paths)[source]¶ Collect configuration from yaml files
This searches through a list of paths, expands to find all yaml or json files, and then parses each file.
-
donfig.config_obj.
expand_environment_variables
(config)[source]¶ Expand environment variables in a nested config dictionary
This function will recursively search through any nested dictionaries and/or lists.
Parameters: config (dict, iterable, or str) – Input object to search for environment variables Returns: config Return type: same type as input Examples
>>> expand_environment_variables({'x': [1, 2, '$USER']}) # doctest: +SKIP {'x': [1, 2, 'my-username']}
-
donfig.config_obj.
merge
(*dicts)[source]¶ Update a sequence of nested dictionaries
This prefers the values in the latter dictionaries to those in the former
Examples
>>> a = {'x': 1, 'y': {'a': 2}} >>> b = {'y': {'b': 3}} >>> merge(a, b) # doctest: +SKIP {'x': 1, 'y': {'a': 2, 'b': 3}}
See also
-
donfig.config_obj.
update
(old, new, priority='new')[source]¶ Update a nested dictionary with values from another
This is like dict.update except that it smoothly merges nested values
This operates in-place and modifies old
Parameters: priority (string {'old', 'new'}) – If new (default) then the new dictionary has preference. Otherwise the old dictionary does. Examples
>>> a = {'x': 1, 'y': {'a': 2}} >>> b = {'x': 2, 'y': {'b': 3}} >>> update(a, b) # doctest: +SKIP {'x': 2, 'y': {'a': 2, 'b': 3}}
>>> a = {'x': 1, 'y': {'a': 2}} >>> b = {'x': 2, 'y': {'b': 3}} >>> update(a, b, priority='old') # doctest: +SKIP {'x': 1, 'y': {'a': 2, 'b': 3}}
See also