Skip to content

molcfg

Zero-dependency Python configuration library for services, CLIs, and internal tooling that need predictable loading, merging, and validation without a heavy runtime.

Get started API reference

What it gives you

  • Layered loading from dicts, TOML/JSON files, environment variables, and CLI arguments
  • Deep merge, override, and append strategies — all return isolated copies
  • Recursive schema validation with defaults, strict unknown-field checks, and built-in constraints
  • Source tracking via Config.meta() so every value can be explained
  • Attribute and dotted-path access, freeze, snapshot, and rollback on the same Config object
  • Thread-safe wrapper and POSIX file lock for concurrent access patterns
  • ${path.to.key} and ${env:VAR} interpolation with circular-reference detection
  • No runtime dependencies

Quick example

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")}

Documentation map

  • Getting Started — installation, first config, layered loading
  • Sources — file, environment, and CLI source details
  • Validation — schemas, defaults, strict mode, constraints
  • Merge — merge strategies, ConfigLoader, ProfileLoader
  • Concurrency — thread-safe wrapper, file locks, interpolation
  • API Reference — complete exported surface