confingo

A dataclass-driven configuration toolkit. Define your program's settings once as typed dataclasses, then load them from a config file, with everything validated and coerced against the schema on the way in.

The dataclass declaration is the single source of truth: it serves at once as the schema, the type validator, and the default values. Defaults are validated against the same annotations supplied values are coerced toward, so every authored default that reaches the object has a plain serializable form. Config objects compare by value and are unhashable; config_hash is the stable value-identity operation.

Installation

pip install confingo

Runs on Python 3.12 and newer.

Quick example

Define the schema as dataclasses. Any of them subclasses ConfigNode to get load, save, and hash methods over its own subtree; the optimizer section carries a bare annotation and builds itself, so optimizer.name is the one value the file must supply.

from __future__ import annotations

from dataclasses import dataclass
from pathlib import Path
from typing import Literal

from confingo import ConfigNode


@dataclass
class OptimizerConfig(ConfigNode):
    name: Literal["adamw", "sgd"]
    lr: float = 3e-4


@dataclass
class TrainingConfig(ConfigNode):
    optimizer: OptimizerConfig
    seed: int = 0
    output_dir: Path = Path("runs")

Write a config file that supplies the required value and any leaves that differ from the defaults:

{
  "optimizer": {"name": "adamw", "lr": 0.001}
}

Load it into a typed, validated object and derive a stable run identity:

config = TrainingConfig.cfg.load_json("train.json")

config.optimizer.lr             # 0.001, coerced to float
config.seed                     # 0, from the default
run_id = config.cfg.hash()   # "344e28a35dd4"
saved = config.cfg.save_json(config.output_dir / run_id / "resolved.json")
saved.as_posix()                # "runs/344e28a35dd4/resolved.json"

The runnable version lives in examples/quickstart/ and is walked through in Getting started.

Validation walks the whole tree in one pass and reports every problem at once, each tagged with a dotted path:

confingo.ConfigError: config file train.json has 3 issues:
  - sed: unknown key (known keys: optimizer, output_dir, seed)
  - optimizer.name: expected one of 'adamw' | 'sgd', got 'adam'
  - optimizer.lr: expected float, got str

Variant groups

When a field should hold any of several sections, declare a variant group: a base naming the key its sections select under, and one class per member naming the string a config file writes there.

from dataclasses import dataclass

from confingo import ConfigChoice


@dataclass
class Optimizer(ConfigChoice, tag_key="algorithm"):
    lr: float = 3e-4                      # shared by every variant


@dataclass
class AdamW(Optimizer, tag="adamw"):
    betas: tuple[float, float] = (0.9, 0.999)


@dataclass
class SGD(Optimizer, tag="sgd"):
    momentum: float = 0.9

A field annotated optimizer: Optimizer takes any variant, and the file names which one to build:

optimizer:
  algorithm: sgd
  lr: 0.1
  momentum: 0.8

One class is constructed, so its __post_init__ and __validate__ run once. The selection is required, and a file that leaves it out is told so at the key's own dotted path. It leads the exported section, so a saved snapshot loads back into the variant it came from. The rules live in variant groups.

Arrays and tensors

NumPy arrays and PyTorch tensors work as field types whenever your application already imports the backend; the array/tensor integration activates from that already-imported backend and detects it at runtime. Values serialize as plain JSON data (a scalar for a 0-d value, nested lists otherwise) and rebuild against the annotated dtype, with bare torch.Tensor pinned to value-stable dtypes and Annotated[torch.Tensor, torch.float32] pinning a specific one. The rules live in arrays and tensors.

Documentation

Full documentation lives in docs/, which offers two routes through one set of pages.

Essentials covers everything needed to write, load, save, and debug a config:

• Getting started: the linear introduction, from a runnable example to a realistic training config with defaults, sections, variant groups, and a run hash.
• Arrays and tensors: NumPy and PyTorch fields, dtype and shape choices.
• Files, formats, and run identity: JSON, YAML, extension dispatch, atomic saves.
• Recipes: copyable answers to common tasks.

Exact reference holds the precise rules, for lookup:

• Schema design: implicit sections, leaf-level requirements, defaults, ConfigNode, variant groups.
• Types and coercion: accepted annotations and exact conversion rules.
• Validation and errors: the collect-all error model and every issue source.
• Equality and hashing: canonical equality, unhashable config objects, stable run identity.
• API reference: signatures for every public name.

In one line

confingo packages the "config file plus dataclass schema" pattern into a reusable toolkit: a typed marshal / unmarshal pair over plain stdlib dataclasses, with exhaustive error reporting and a reproducible fingerprint.