donfig package

Submodules

donfig.config_obj module

class donfig.config_obj.Config(name: str, defaults: list[Mapping[str, Any]] | None = None, paths: list[str] | None = None, env: Mapping[str, str] | None = None, env_var: str | None = None, root_env_var: str | None = None, env_prefix: str | None = None, deprecations: Mapping[str, str | None] | None = None)

Bases: object

clear()

Clear all existing configuration.

collect(paths: list[str] | None = None, env: Mapping[str, str] | None = None) → dict

Collect configuration from paths and environment variables

Parameters:

• paths (list[str]) – A list of paths to search for yaml config files. Defaults to the paths passed when creating this object.

• env (Mapping[str, str]) – The system environment variables to search through. Defaults to the environment dictionary passed when creating this object.

Returns:

config

Return type:

dict

See also

donfig.Config.refresh

collect configuration and update into primary config

ensure_file(source: str, destination: str | None = None, comment: bool = True) → None

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() → None

Expand any environment variables in this configuration in-place.

See expand_environment_variables() for more information.

get(key: str, default: Any = '__no_default__') → Any

Get elements from global config

Use ‘.’ for nested access

Examples

>>> from donfig import Config
>>> config = Config('mypkg')
>>> config.get('foo')  
{'x': 1, 'y': 2}

>>> config.get('foo.x')  
1

>>> config.get('foo.x.y', default=123)  
123

See also

donfig.Config.set

merge(*dicts)

Merge this configuration with multiple dictionaries.

See merge() for more information.

pprint(**kwargs)

refresh(**kwargs) → None

Update configuration by re-reading yaml files and env variables.

This goes through the following stages:

1. Clearing out all old configuration

2. Updating from the stored defaults from downstream libraries (see update_defaults)

3. 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: Mapping) → None

Rename old keys to new keys

This helps migrate older configuration versions over time

serialize() → str

Serialize conifg data into a string.

See serialize() for more information.

set(arg=None, **kwargs)

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 in arg will be applied before those in kwargs. 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)  

See also

donfig.Config.get

to_dict()

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.

update(new, priority='new')

Update the internal configuration dictionary with new.

See update() for more information.

update_defaults(new: Mapping) → None

Add a new set of defaults to the configuration

It does two things:

1. Add the defaults to a collection to be used by refresh() later

2. Updates the global config with the new configuration. Old values are prioritized over new ones, unless the current value is the old default, in which case it’s updated to the new default.

class donfig.config_obj.ConfigSet(config: MutableMapping, lock: SerializableLock | AbstractContextManager, deprecations: MutableMapping[str, str | None], arg: Mapping | None = None, **kwargs)

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: str, config: Mapping[str, Any]) → str

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: str, env: Mapping[str, str] | None = None, deprecations: MutableMapping[str, str | None] | None = None) → dict

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: Sequence[str]) → list[dict]

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.deserialize(data: str) → Any

De-serialize config data into the original object.

Typically used when receiving config via the MYPKG_INTERNAL_INHERIT_CONFIG environment variable. This is automatically called when a Config is created and environment variables are loaded.

Parameters:

data (str) – String serialized by donfig.serialize()

Returns:

deserialized_data – The de-serialized data

Return type:

obj

donfig.config_obj.expand_environment_variables(config)

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']})  
{'x': [1, 2, 'my-username']}

donfig.config_obj.merge(*dicts: Mapping) → dict

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)  
{'x': 1, 'y': {'a': 2, 'b': 3}}

See also

donfig.config_obj.update

donfig.config_obj.serialize(data: Any) → str

Serialize config data into a string.

Typically used to pass config via the MYPKG_INTERNAL_INHERIT_CONFIG environment variable.

Parameters:

data (json-serializable object) – The data to serialize

Returns:

serialized_data – The serialized data as a string

Return type:

str

donfig.config_obj.update(old: MutableMapping[str, Any], new: Mapping[str, Any], priority: Literal['old', 'new', 'new-defaults'] = 'new', defaults: Mapping | None = None) → Mapping[str, Any]

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', 'new-defaults'}) – If new (default) then the new dictionary has preference. Otherwise the old dictionary does. If ‘new-defaults’, a mapping should be given of the current defaults. Only if a value in old matches the current default, it will be updated with new.

Examples

>>> a = {'x': 1, 'y': {'a': 2}}
>>> b = {'x': 2, 'y': {'b': 3}}
>>> update(a, b)  
{'x': 2, 'y': {'a': 2, 'b': 3}}

>>> a = {'x': 1, 'y': {'a': 2}}
>>> b = {'x': 2, 'y': {'b': 3}}
>>> update(a, b, priority='old')  
{'x': 1, 'y': {'a': 2, 'b': 3}}

>>> d = {'x': 0, 'y': {'a': 2}}
>>> a = {'x': 1, 'y': {'a': 2}}
>>> b = {'x': 2, 'y': {'a': 3, 'b': 3}}
>>> update(a, b, priority='new-defaults', defaults=d)  
{'x': 1, 'y': {'a': 3, 'b': 3}}

See also

donfig.config_obj.merge

donfig.utils module

donfig.utils.tmpfile(extension='', dir=None)

Module contents