API reference¶

cfgx ¶

CLASS	DESCRIPTION
`Delete`	Sentinel that removes a key from a merged config.
`Replace`	Sentinel that forces a value to replace a mapping during merge.
`Lazy`	Callable wrapper that defers computation until config resolution.

FUNCTION	DESCRIPTION
`load`	Load config modules from one or more paths, apply overrides, and merge the results.
`apply_overrides`	Apply CLI-style override strings to a config dictionary.
`merge`	Recursively merge two dictionaries, honoring Delete/Replace sentinels.
`resolve_lazy`	Resolve Lazy values in a config dictionary.
`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).

Delete ¶

Sentinel that removes a key from a merged config.

Replace ¶

Sentinel that forces a value to replace a mapping during merge.

Lazy ¶

Callable wrapper that defers computation until config resolution.

load ¶

load(path: PathLike | Sequence[PathLike], overrides: Sequence[str] | None = None, resolve_lazy: bool = True)

Load config modules from one or more paths, apply overrides, and merge the results.

Parent configs (via parents) are resolved first, then later paths override earlier ones. config must be a dictionary.

apply_overrides ¶

apply_overrides(cfg: dict, overrides: Sequence[str])

Apply CLI-style override strings to a config dictionary.

Supports assignment (=), append (+=), delete (!=), and removal from list (-=) using dotted/indexed key paths like model.layers[0].units. Mutates the dictionary in place and returns it.

merge ¶

merge(base: dict, override: dict)

Recursively merge two dictionaries, honoring Delete/Replace sentinels.

If both sides contain dicts, merge continues down the tree. Delete removes a key from the base config, Replace overwrites without further deep merging, and other values simply override. Returns a new dictionary without mutating the inputs.

resolve_lazy ¶

resolve_lazy(cfg: dict)

Resolve Lazy values in a config dictionary.

Lazies are evaluated against the fully merged config, and results replace the Lazy nodes in place. Cycles raise an error.

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 structures, including dict subclasses.

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 structures, including dict subclasses.

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 structures, including dict subclasses.