molcfg loads configuration from dicts, files, environment variables, and CLI arguments into a single layered Config, remembering where every value came from. It adds schema validation, string-tag construction, interpolation, and thread-safe access on top.

Capabilities

Module	Capability
config	Config container — attribute and dotted-path access, freeze, snapshot/rollback, change notification, JSON/TOML/YAML round-trip
source	Config sources — DictSource, JsonFileSource, TomlFileSource, YamlFileSource, EnvSource, CliSource behind a common Source interface
merge	OVERRIDE / APPEND / DEEP_MERGE strategies, ConfigLoader for layered loading, and ProfileLoader for profile-based config
validation	Type-and-constraint validation — Range, OneOf, Pattern, Length descriptors, Build, and the validate entry point
registry	Registry — maps string keys (e.g. "silu") to factories, resolving short and long forms into classes or instances
concurrency	ThreadSafeConfig wrapper, POSIX FileLock, and the ${path} / ${env:VAR} interpolate engine
paths	project_config_dir — resolves and creates the shared ~/.molcrafts/<name>/config/ directory
errors	Exception hierarchy — ConfigError, FrozenConfigError, CircularReferenceError, ValidationError

Install

pip install molcrafts-molcfg

Requires Python 3.12+. The only runtime dependency is pyyaml.

Quick start

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

Full documentation lives in docs/:

• Getting started
• Sources
• Validation
• Merge strategies
• Registry
• Concurrency
• API reference

MolCrafts ecosystem

Project	Role
molpy	Python toolkit — the shared molecular data model & workflow layer
molrs	Rust core — molecular data structures & compute kernels (native + WASM)
molpack	Packmol-grade molecular packing (Rust + Python)
molvis	WebGL molecular visualization & editing
molexp	Workflow & experiment-management platform
molnex	Molecular machine-learning framework
molq	Unified job queue — local / SLURM / PBS / LSF
molcfg	Layered configuration library — this repo
mollog	Structured logging, stdlib-compatible
molhub	Molecular dataset hub
molmcp	MCP server for the ecosystem
molrec	Atomistic record specification

Contributing

See CONTRIBUTING.md.

License

BSD-3-Clause — see LICENSE.

---