cfg-mgr documentation¶

Installation¶

Install cfg-mgr with pip:

pip install cfg-mgr

The base install includes the JSON and TOML (requires python>=3.11) file loaders. Loaders for other file formats require optional dependencies, installed as extras:

YAML file loader (with PyYaml):

pip install cfg-mgr[yaml]

.env file loader (with python-dotenv):

pip install cfg-mgr[dotenv]

All optional file loaders:

pip install cfg-mgr[all]

Or clone/fork the source: https://github.com/raghavj98/cfgmgr

API Reference¶

Simple interface for loading and using configurations.

Usage:

import cfgmgr

cfgmgr.make_config(env_prefix="CFG_", file_path="config.json")
val = cfgmgr.getkey("KEY")  # Reads os.environ["CFG_KEY"]
cfgmgr.setkey("KEY", 'a')
cfgmgr.get()["KEY"]  # 'a'

cfgmgr.make_config(env_prefix=None, file_path=None, find_file=False, include_key=None, **kwargs)¶

Initialize a global default Config instance.

Parameters:

env_prefix (str) – If provided, used to construct an EnvLoader instance for the default config.
file_path (str) – If provided, used to construct a FileLoader instance for the default config. make_config will try to auto detect the appropriate FileLoader subclass via the file extension.
find_file (bool) – If True, crawl upwards from current working directory until file_path is found.
include_key (str) – Can only be given alongside a file_path. If given, the value corresponding to it will be treated as another file to load, recursively.
**kwargs – Passed to Config.__init__, overrides values from all loaders.

Raises:

ValueError – include_key given without file_path.
FileNotFoundError – file_path or any files inferred from include_key cannot be found.
IncludeCycleError – Cyclical includes detected

Returns:

None

cfgmgr.getkey(key, default=None)¶

Get a value from the current global default config.

Parameters:

key (str) – Passed to Config.get.
default (Optional) – If key is not found, return this instead.

Returns:

The value corresponding to key in the current global default config.

Raises:

AttributeError – If no global default config is initialized (via make_config)

cfgmgr.setkey(key, value)¶

Set a value in the current global default config.

Parameters:

key (str) – key to set the value for
value (Any) – The value to store

Returns:

None

Raises:

AttributeError – If no global default config is initialized (via make_config)

cfgmgr.get()¶

Get the current global default config.

Returns:: The current global default Config instance. Future make_config calls will create a new global config. Can be used to “store” configs created by make_config.

class cfgmgr.Config(loaders, **kwargs)¶

Bases: MutableMapping

Primary interface for configuration access.

Composed of an ordered set of loaders. Implements MutableMapping. Contained loaders shadow each others’ keys. Setting a key using MutableMapping methods shadows all loaders.

Performance warning: len on a Config instance iterates over it (albeit non exhausting)

get(k[, d]) → D[k] if k in D, else d. d defaults to None.¶

exception cfgmgr.IncludeCycleError¶

Bases: ValueError

Raised when a file’s include directives form a cycle.

class cfgmgr.Loader¶

Bases: Mapping

Abstract interface for configuration data sources.

A Loader is a Mapping over a data source for a configuration.

static = False¶

True if the underlying data source is immutable.

A loader itself is always immutable, but the underlying data source may still be mutable through other means (like EnvLoader via os.environ), in which case static is False.

Type:: bool

class cfgmgr.FileLoader(file_path, strip_keys=())¶

Bases: Loader

Abstract base class for loaders reading from a file.

FileLoader has static = True since the stored internal state is immutable.

static = True¶

True if the underlying data source is immutable.

A loader itself is always immutable, but the underlying data source may still be mutable through other means (like EnvLoader via os.environ), in which case static is False.

Type:: bool

class cfgmgr.EnvLoader(prefix='')¶

Bases: Loader

Loader for environment variables.

class cfgmgr.JSONLoader(file_path, strip_keys=())¶

Bases: FileLoader

Load JSON files.

Uses stdlib json module.

class cfgmgr.TOMLLoader(file_path, strip_keys=())¶

Bases: FileLoader

Load TOML files.

Requires python>=3.11 since it uses stdlib tomllib.

class cfgmgr.YAMLLoader(file_path, strip_keys=())¶

Bases: FileLoader

Load YAML files.

Uses PyYAML. (yaml.safe_load)

class cfgmgr.DotEnvLoader(file_path, strip_keys=())¶

Bases: FileLoader

Load .env files.

Uses python-dotenv. (dotenv.dotenv_values, so os.environ is not modified)

class cfgmgr.IncludeLoader(including, included)¶

Bases: Loader

Composite Loader subclass for files that includes another file.

static = True¶

True if the underlying data source is immutable.

A loader itself is always immutable, but the underlying data source may still be mutable through other means (like EnvLoader via os.environ), in which case static is False.

Type:: bool

cfgmgr.deep_merge(prim, sec)¶

Recursively merge two mappings, with prim taking priority.

Where both mappings contain the same key and both values are themselves mappings, the values are merged recursively. Otherwise the value from prim wins. If either argument is not a mapping, prim is returned as-is.

Parameters:

prim (Any) – The higher-priority value.
sec (Any) – The lower-priority value.

Returns:

The merged result. A read-only MappingProxyType when a merge occurred, otherwise prim unchanged.

cfgmgr.deep_freeze(val)¶

Recursively convert a value into an immutable structure.

Mappings become read-only MappingProxyTypes and sequences (other than str, bytes, and bytearray) become tuples, applied recursively. Any other value is returned unchanged.

Parameters:: val (Any) – The value to freeze.
Returns:: An immutable copy of val.

cfgmgr.resolve_includes(entry_file, include_key='include-cfg')¶

Recursively construct loaders for a file with an include directive

Parameters:

entry_file (str) – Path of the entry point file
include_key (str) – Include key that specifies the files to include. Defaults to ‘include-cfg’.

Returns:

A Loader instance representing the merged data from all found files

Raises:

IncludeCycleError – If the include directives form a cycle.
FileNotFoundError – If entry_file or any included file cannot be found.

cfgmgr.find_relative_file(base, target)¶

Find a file path relative to another.

Parameters:

base (str) – File path of the base file.
target (str) – Path of the target relative to base.

Returns:

Canonical path of the target.

Raises:

FileNotFoundError – If no file can be found.

cfgmgr.find_file_up(basename)¶

Find a file crawling up from the current working directory

Parameters:: basename (str) – Name of the file to find
Returns:: Path of the found file, or None if no such file can be found.
Raises:: ValueError – If the file extension is not registered to a corresponding Loader.

cfgmgr.get_file_loader(file_path, /, **kwargs)¶

Get a constructed loader for a file

Attempts to find a registered loader for the extension of the given file

Parameters:: file_path (str) – File path to construct a loader from
Returns:: Constructed Loader instance for the file
Raises:: ValueError – If the extension is not supported.