Skip to content

molcfg Manual

molcfg

Load configuration from dicts, files, environment variables, and CLI arguments; merge the layers into one immutable object; validate it against a schema; and ask any value where it came from. A single runtime dependency, and every operation returns an isolated copy.

molcfg

At a glance

Layers in, one explained config out

Stack sources lowest-priority first. ConfigLoader merges them into an immutable Config, and meta() reports the winning source and the full override history for any value.

from molcfg import CliSource, ConfigLoader, DictSource, EnvSource

cfg = ConfigLoader([
    DictSource({"db": {"host": "localhost", "port": 5432}}, name="defaults"),
    EnvSource(prefix="APP", name="env"),
    CliSource(["--db.port=6432"], name="cli"),
]).load()

assert cfg["db.port"] == 6432
assert cfg.meta("db.port") == {"source": "cli", "history": ("defaults", "cli")}

What molcfg gives you

Everything a config layer needs, nothing it doesn't

Layered sources

Load from dicts, JSON / TOML / YAML files, environment variables, and CLI arguments — each a named Source you can stack in priority order.

 Immutable merge

Deep-merge, override, and append strategies via ConfigLoader and ProfileLoader. Every result is an isolated copy — inputs are never mutated.

 Schema validation

Recursive schemas with defaults, strict unknown-field checks, and built-in constraints (Range, OneOf, …). Fail fast with a clear message.

 Source tracking

Config.meta() answers "where did this value come from?" — the winning source plus the full override history for every key.

 Registry & Build

Resolve config strings like "silu" into Python classes or instances, so config files can drive object construction.

 Concurrency & interpolation

A thread-safe wrapper and cross-platform file lock for shared access, plus ${path.to.key} / ${env:VAR} interpolation with circular-reference detection.

Find your page

The manual in seven chapters