.    .  c o d e c h u  .    .
           .   \  |  /  c o n f i g  \  |   .
        ((((( ── (( ⚙ )) ──────────── (( ⚙ )) ── )))))
           '   /  |  \                /  |   '
              '    '  schema · dotted · atomic

Schema-first config. Validates on set. Saves atomically. Migrates on load.

codechu-config

Schema-driven configuration for Python. JSON + TOML backends, dotted-key access, atomic save, and forward migrations. Pure stdlib (tomli_w is the only optional dependency, needed only when writing TOML).

pip install codechu-config           # JSON-only
pip install "codechu-config[toml]"   # adds TOML write support

What it gives you

• Schema validation — types, choices, ranges, required fields, all enforced on every set.
• Dotted keys — cfg.set("watchdog.threshold", 90) writes nested structure; cfg.get("watchdog.threshold") reads it back.
• Atomic save — tempfile-in-same-dir + fsync + os.replace. A crash mid-write leaves the previous content intact, never garbage. If codechu-fs is installed it is used transparently; otherwise the stdlib fallback ships in-package.
• Migrations — point the Config at a list of callables; they run in order whenever the on-disk _version differs from the schema's default.
• JSON + TOML — JSON by default (zero deps). TOML reads via stdlib tomllib (Python 3.11+); TOML writes need the optional tomli_w.
• Dict sugar — cfg["language"] = "tr", "language" in cfg.

Quick start

from codechu_config import Config, Field, Schema

schema = Schema({
    "_version": Field(int, default=1),
    "language": Field(str, default="en", choices=["en", "tr"]),
    "watchdog.threshold": Field(int, default=90, range=(0, 100)),
    "watchdog.enabled": Field(bool, default=True),
})

cfg = Config(schema, "~/.config/myapp/config.json").load()
cfg.set("language", "tr")
cfg.set("watchdog.threshold", 75)
cfg.save()                       # atomic

Bulk update with all-or-nothing semantics

try:
    cfg.update({"language": "tr", "watchdog.threshold": 200})
except ValidationError:
    pass                         # nothing changed; original values intact

Migrations

def v1_to_v2(data):
    data["language"] = data.pop("lang", "en")
    data["_version"] = 2
    return data

cfg = Config(schema, path, migrations=[v1_to_v2]).load()

Migrations run only when the on-disk _version does not match the schema default. Each migration is responsible for bumping _version.

TOML backend

cfg = Config(schema, "~/.config/myapp/config.toml", format="toml").load()

Reading TOML uses the stdlib tomllib (Python 3.11+). Writing TOML requires pip install codechu-config[toml].

API reference

Field

Schema

Config

Exceptions

• ConfigError — base.
• ValidationError — raised by Field, Schema, and Config.set.
• MigrationError — raised when a migration callable fails or returns a non-dict.

License

MIT — see LICENSE.

Part of Codechu.