API Reference¶

Config¶

class Config(data: dict | None = None, *, metadata=None, prefix="")

Nested configuration container. Nested dicts are automatically wrapped into child Config instances.

Access¶

Methods¶

• get(path, default=None) — safe dotted-path read
• keys(), values(), items() — top-level iteration
• to_dict() — recursive plain-dict export
• to_json(**kwargs) — JSON string; passes kwargs to json.dumps
• freeze() — recursively freeze; raises FrozenConfigError on write
• unfreeze() — recursively unfreeze
• snapshot() — push current state onto the snapshot stack
• rollback() — pop and restore the last snapshot
• on_change(callback) — register callback(path, new_value, old_value)
• meta(path) — return {"source": str, "history": tuple} for a dotted path
• metadata() — return the full metadata dict

Properties¶

• frozen — True if the config is currently frozen

Sources¶

All sources inherit from Source and expose a single method:

• load() -> dict[str, Any]

DictSource¶

DictSource(data: dict, *, name: str = "")

Wraps an in-memory dict.

JsonFileSource¶

JsonFileSource(path: str | Path, *, name: str = "")

TomlFileSource¶

TomlFileSource(path: str | Path, *, name: str = "")

EnvSource¶

EnvSource(prefix: str = "", *, coerce: bool = True, environ: dict | None = None, name: str = "")

Reads environment variables and maps them to nested keys by splitting on _. prefix is stripped and not included in the output key.

CliSource¶

CliSource(args: list[str], *, coerce: bool = True, name: str = "")

Parses --key=value and --key value arguments. Dotted keys map to nested dicts.

Merge¶

merge()¶

merge(base: dict, override: dict, strategy: MergeStrategy = DEEP_MERGE) -> dict

Returns a new dict. Neither input is mutated.

MergeStrategy¶

class MergeStrategy(enum.Enum):
    DEEP_MERGE = "deep_merge"
    OVERRIDE   = "override"
    APPEND     = "append"

ConfigLoader¶

ConfigLoader(sources: list[Source], strategy: MergeStrategy = DEEP_MERGE)

• load() -> Config — merge all sources in order, attach metadata

ProfileLoader¶

ProfileLoader(base_sources: list[Source], profiles: dict[str, Source], strategy: MergeStrategy = DEEP_MERGE)

• load(profile: str | None = None) -> Config — load base sources and optionally apply a named profile overlay

Validation¶

validate()¶

validate(
    data: dict,
    schema: type,
    *,
    apply_defaults: bool = False,
    allow_extra: bool = True,
) -> dict

Raises ValidationError on type mismatch, missing required fields, or constraint failure.

Constraints¶

Range(min: float | None = None, max: float | None = None)
Length(min: int | None = None, max: int | None = None)
Pattern(pattern: str)
OneOf(*choices)

Attach via __constraints__ = {"field": [constraint, ...]} on the schema class.

Build¶

Build(registry: Registry)

typing.Annotated metadata marker. When validate() encounters field: Annotated[T, Build(reg)], the raw value is passed through reg.build(...) before the field's type is checked. Works on default values too.

Registry¶

Registry(name: str, *, discriminator: str = "type")

String-tag → factory container. Generic: Registry[T]("name").

Registration¶

reg.register("silu", nn.SiLU)     # direct
@reg("leaky_relu")                # decorator
class MyLeakyReLU(nn.Module): ...

Keys are lowercased. Duplicate registration raises ValueError.

Access¶

• reg.build(spec) -> T | None — resolve into an instance. Accepts str (short form), dict with a type key + kwargs (long form), None (pass-through), or an existing instance (idempotent).
• reg.get(name) -> type[T] | callable | None — return the registered factory/class without instantiating. None pass-through. For APIs that take type[T] and construct later.
• reg.keys() -> list[str] — sorted list of registered keys.
• "key" in reg — containment check (case-insensitive).

See the Registry guide for the full tutorial.

Concurrency¶

ThreadSafeConfig¶

ThreadSafeConfig(config: Config, lock: threading.RLock | None = None)

Wraps all reads and writes in the provided lock (or a new RLock). Exposes the same interface as Config.

FileLock¶

FileLock(path: str | Path)

Context manager. Acquires fcntl.LOCK_EX on entry, releases on exit.

• acquire() / release() for manual management

interpolate()¶

interpolate(data: dict, environ: dict | None = None) -> dict

Resolves ${path.to.key} and ${env:VAR} placeholders. Raises CircularReferenceError on circular references.

Errors¶

All errors inherit from ConfigError.