molcfg

Layered configuration for Python — predictable loading, merging, validation, and source tracking.

CI PyPI Python License Ruff

Documentation  ·  Quick start  ·  Ecosystem

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: docs.molcrafts.org/molcfg (sources in docs/):

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.

Crafted with 💚 by MolCrafts

Project links

Data verified by PyPI on Aug 9, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

Owner

PyPI data
Data sourced directly from PyPI's database.

Credits

Author: Roy Kid

GitHub Statistics

Data verified by PyPI on Aug 9, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

BSD-3-Clause
View SPDX License List

Requires

Python >=3.12

Provides Extra

dev docs

Tags

config configuration environment validation merge

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

molcrafts_molcfg-1.5.0.tar.gz (43.9 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

molcrafts_molcfg-1.5.0-py3-none-any.whl (23.6 kB view details)

Uploaded Python 3

File details

Details for the file molcrafts_molcfg-1.5.0.tar.gz.

File metadata

  • Download URL: molcrafts_molcfg-1.5.0.tar.gz
  • Upload date:
  • Size: 43.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for molcrafts_molcfg-1.5.0.tar.gz
Algorithm Hash digest
SHA256 3d6fb7cba5ddd87b1370f94486740b40359e3af9639d7cb8b926657424cb9116
MD5 01b7d1afa63f78c5792d6853351d4cd1
BLAKE2b-256 d2eda365b3d798bf42860a933d675f0ebeeff64cfdb8444e34891bacab885c9e

See more details on using hashes here.

Provenance

The following attestation bundles were made for molcrafts_molcfg-1.5.0.tar.gz:

Publisher: release.yml on MolCrafts/molcfg

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file molcrafts_molcfg-1.5.0-py3-none-any.whl.

File metadata

File hashes

Hashes for molcrafts_molcfg-1.5.0-py3-none-any.whl
Algorithm Hash digest
SHA256 61c5db3cfff5f8ec5a407bc0bbbec73585c29520e1860dc4bf7d8f454564ce31
MD5 702facf0ccb4310927c9b40d495938ab
BLAKE2b-256 8d83de3456513176b0e0a0876bd7fbf3db4925be8db29f889bdee7b00eb331ac

See more details on using hashes here.

Provenance

The following attestation bundles were made for molcrafts_molcfg-1.5.0-py3-none-any.whl:

Publisher: release.yml on MolCrafts/molcfg

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

1.5.0 This release

2 files

1.4.2

2 files

1.4.1

2 files

1.4.0

2 files

1.1.0

2 files

1.0.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page