kaava

Load typed Python configuration from YAML, TOML, or JSON into dataclasses, with validation, source tracing, environment-variable overlays, and a diagnostic CLI.

Requires Python 3.11 or later. YAML support uses ruamel.yaml (default) or PyYAML; TOML and JSON use the standard library.

Install

pip install kaava

Quickstart

Define your configuration shape as a plain dataclass and call load().

import dataclasses
from kaava import conf_field, load


@dataclasses.dataclass
class DBConfig:
    host: str = conf_field(description='database host')
    port: int = conf_field(default=5432)


@dataclasses.dataclass
class AppConfig:
    name: str = conf_field(description='application name')
    db: DBConfig = conf_field(description='database connection')
    debug: bool = conf_field(default=False)


cfg = load(AppConfig, 'config.yaml')
print(cfg.name, cfg.db.host, cfg.db.port)

config.yaml:

name: myapp
db:
  host: localhost

Fields with no default or default_factory are required. Nested dataclasses map to YAML mappings and are built recursively. load() raises on the first error encountered; use validate() or load_valid() to collect all errors.

For a quick feature-by-feature tour, see quickstart. For a step-by-step tutorial that builds a real command-line tool from scratch, see tutorial.

Learn more

kaava's man pages are installable locally with kaava eject man (see man kaava) or browsable under docs/man/:

• man kaava -- the CLI: doctor, explain, validate, eject config, eject man, complete, version; options, exit codes, examples.
• man 3 kaava -- the full library API: every exported function and type (load, doctor, explain, conf_field, the overlay builders, the error hierarchy), exact signatures and behavior.
• man 5 kaava -- file formats: the CLI's own settings (~/.config/kaava/cli.yaml), the auto-discovery locations load() falls back to, and the dotenv format.
• man 7 kaava -- the sources-then-overlays loading model end to end, a worked "adopting kaava in a new project" walkthrough, and how the CLI configures itself using the same load() any caller uses.

Companion CLI

The kaava command exposes the library's diagnostic functions as subcommands, against a dotted import path (module.path:ClassName):

kaava doctor          myapp.config:AppConfig config.yaml
kaava explain         myapp.config:AppConfig config.yaml
kaava validate        myapp.config:AppConfig config.yaml
kaava eject config    myapp.config:AppConfig

A remembered default target (see man 5 kaava) lets every command above drop the dataclass path and sources entirely: kaava doctor alone. Every command, subcommand, and long option accepts an unambiguous prefix (kaava ver for kaava version); calling kaava or kaava eject alone prints that command's own help and exits 0.

Design and requirements

Software Requirements Specification : KAA-SRS-001 -- requirements/

Software Design Description : KAA-SDD-001 -- design/

Both documents follow the MIL-STD-498 DID structure and are rendered into the documentation site alongside the tutorial and quickstart.

Changes

See releases/ for the release history, or releases/changes/ for the full detail behind each summary.

Complexity

The code base complexity is documented at complexity/.

Coverage

The test suite maintains 100% branch coverage. The HTML report (if generated) is in site/coverage/.

SBOM

Runtime dependency information is published in docs/sbom/ in SPDX 3.0 (JSON-LD) and CycloneDX 1.6 (JSON) formats. See docs/sbom/README.md for the component inventory and validation guide.