Skip to content

API reference

cfgx

CLASS DESCRIPTION
Expression

A deferred selection or calculation, resolved within a config location.
ConfigError

Invalid config structure or dependency cycle.
MissingValueError

A selected config value does not exist.
FUNCTION DESCRIPTION
load

Compose sources and overrides into an independent, resolved dictionary.
compose

Contribute ordered, dictionary-valued sources at this location.
include

Include a file's unresolved config definitions at this location.
computed

Declare a calculation whose callable receives get(expression).
replace

Replace inherited contents at this location instead of merging dictionaries.
dump

Persist a config dictionary to a Python snapshot (config = ...).
dumps

Return a Python snapshot string (config = ...) for a config dictionary.
format

Return a string representation based on repr(config).
ATTRIBUTE DESCRIPTION
final

Read the complete configuration, including later layers and overrides.
previous

Read definitions contributed before the expression's originating layer.
value

Read the inherited value at the current output location.
delete

Remove a dictionary entry from the composed configuration.

final module-attribute 

final = Expression('root', 'final', None)

Read the complete configuration, including later layers and overrides.

previous module-attribute 

previous = Expression('root', 'previous', None)

Read definitions contributed before the expression's originating layer.

value module-attribute 

value = previous(0)

Read the inherited value at the current output location.

delete module-attribute 

delete = _Delete()

Remove a dictionary entry from the composed configuration.

Expression

A deferred selection or calculation, resolved within a config location.

Attributes and subscripts select keys. Calling map(fn), default(x), keys(), len(), or exists() on a selection constructs an operation. These names can also be selected as ordinary dictionary keys.

ConfigError

Bases: ValueError

Invalid config structure or dependency cycle.

MissingValueError

Bases: KeyError

A selected config value does not exist.

load 

load(*sources, overrides=())

Compose sources and overrides into an independent, resolved dictionary.

Sources are paths, plain dictionaries, expressions producing dictionaries, include/compose declarations, replacements, or tuples of sources. Every file defines config using the same syntax. Nested includes and compositions bind definitions at their insertion location. Includes expand in order relative to the declaring file; repeated includes apply repeatedly. Each contribution is a layer; explicit compositions can introduce local layers inside a value.

Exact built-in dictionaries, lists, and tuples are structurally copied. Other objects are opaque and retain identity. No source container is mutated. Overrides contribute ordinary layers using path=value, path!=, or expr:layer. Paths select string dictionary keys. Assignment replaces its leaf; dictionary ancestors merge normally. Values can use Python expr:.

compose 

compose(*sources)

Contribute ordered, dictionary-valued sources at this location.

Source strings and paths include files; source tuples group contributions. Strings and tuples inside config values remain ordinary data.

include 

include(path)

Include a file's unresolved config definitions at this location.

Paths are relative to the declaring config file, or the working directory for sources and overrides supplied directly to load.

computed 

computed(fn)

Declare a calculation whose callable receives get(expression).

Only reads actually executed by the callable become dependencies. Each binding runs at most once per load. The result may contain more declarations.

replace 

replace(x)

Replace inherited contents at this location instead of merging dictionaries.

dump 

dump(config: dict, fd: TextIO, *, format: str = 'pretty', sort_keys: bool = False)

Persist a config dictionary to a Python snapshot (config = ...).

Formatting uses repr(config); default formatting is "pretty". The caller is responsible for ensuring it is valid Python that can be reloaded with any required imports available. Otherwise formatting can raise or the snapshot may fail to load. Use format="raw" for raw repr output.

sort_keys orders dict keys throughout nested dict/list/tuple structures.

dumps 

dumps(config: dict, *, format: str = 'pretty', sort_keys: bool = False) -> str

Return a Python snapshot string (config = ...) for a config dictionary.

Formatting uses repr(config); default formatting is "pretty". The caller is responsible for ensuring it is valid Python that can be reloaded with any required imports available. Otherwise formatting can raise or the snapshot may fail to load. Use format="raw" for raw repr output.

sort_keys orders dict keys throughout nested dict/list/tuple structures.

format 

format(config: dict, *, format: str = 'pretty', sort_keys: bool = False) -> str

Return a string representation based on repr(config).

Formatting is best-effort; invalid repr output can raise or fail to reload. Formatting defaults to "pretty"; use format="raw" for raw repr output.

sort_keys orders dict keys throughout nested dict/list/tuple structures.