Metadata-Version: 2.4
Name: kaava
Version: 2026.10.3
Summary: Load typed Python configuration from YAML, TOML, or JSON into dataclasses, with validation, source tracing, environment-variable overlays, and a diagnostic CLI.
Author-email: Stefan Hagen <stefan@hagen.link>
Maintainer-email: Stefan Hagen <stefan@hagen.link>
License-Expression: MIT
Project-URL: Documentation, https://codes.dilettant.life/docs/kaava
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ruamel.yaml>=0.18.6
Requires-Dist: python-jsonpath>=2.1.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Provides-Extra: pyyaml
Requires-Dist: PyYAML>=6.0.3; extra == "pyyaml"
Dynamic: license-file

# 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()`.

```python
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`:

```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](https://codes.dilettant.life/docs/kaava/quickstart/README.md).
For a step-by-step tutorial that builds a real command-line tool from scratch, see [tutorial](https://codes.dilettant.life/docs/kaava/tutorial/README.md).

## 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/](https://codes.dilettant.life/docs/kaava/requirements/README.md)

Software Design Description
:   KAA-SDD-001 -- [design/](https://codes.dilettant.life/docs/kaava/design/README.md)

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

## Changes

See [releases/](https://codes.dilettant.life/docs/kaava/releases/README.md) for the release history,
or [releases/changes/](https://codes.dilettant.life/docs/kaava/releases/changes/README.md) for the full detail behind each summary.

## Complexity

The code base complexity is documented at [complexity/](https://codes.dilettant.life/docs/kaava/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.
