codechu-config 0.1.0

Schema-driven config with JSON+TOML backends, dotted-key access, atomic save, and migrations.

              .    .  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

Parameter	Purpose
type	Coerced + checked type: str, int, float, bool, list, dict, or None for any.
default	Used when the key is absent on load.
choices	Iterable of allowed values; checked after coercion.
range	(low, high) inclusive numeric bounds.
required	If True, missing keys raise on load/validate.
doc	Human description for tooling.

Schema

Method	Purpose
Schema({name: Field, ...})	Build a schema. Names may be dotted ("watchdog.threshold").
.defaults()	Fresh nested dict of all defaults.
.validate(data)	Return a coerced + validated copy; raise ValidationError on failure.
.field(name)	Look up a single field.

Config

Method	Purpose
Config(schema, path, format="json", migrations=None)	Construct.
.load()	Read file (or use defaults), migrate, validate.
.save()	Atomically write current state.
.get(key, default=None)	Dotted-key read.
.set(key, value)	Validated dotted-key write.
.update({key: value, ...})	All-or-nothing bulk update.
cfg[key] / cfg[key] = value	Dict sugar over get / set.
.as_dict()	Deep-ish copy of current data.

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.