kaava 2026.6.8__tar.gz

kaava-2026.6.8/COUNTRY-OF-ORIGIN

@@ -0,0 +1 @@
+Switzerland

kaava-2026.6.8/EXPORT-CONTROL-CLASSIFICATION-NUMBER

@@ -0,0 +1 @@
+EAR99

kaava-2026.6.8/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stefan Hagen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kaava-2026.6.8/MANIFEST.in

@@ -0,0 +1,5 @@
+include COUNTRY-OF-ORIGIN
+include EXPORT-CONTROL-CLASSIFICATION-NUMBER
+include LICENSE
+include README.md
+include docs/kaava.1

kaava-2026.6.8/PKG-INFO

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: kaava
+Version: 2026.6.8
+Summary: Formula / schema / pattern (Finnish: kaava) - 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
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+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 PyYAML; TOML and JSON use the standard library.
+
+## Install
+
+```
+pip install kaava
+```
+
+## Quick start
+
+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/README.md`.
+For a step-by-step tutorial that builds a real command-line tool from scratch, see `tutorial/README.md`.
+
+## Field metadata
+
+`conf_field()` extends `dataclasses.field()` with configuration-specific metadata.
+
+- `default` / `default_factory` — the field's default value or factory
+- `description` — shown in `explain()` output and in YAML templates produced by `eject()`
+- `env` — explicit environment-variable name used by `env_overlay()`
+- `secret` — when `True`, `explain()` masks the value; useful for passwords and API keys
+- `validator` — a callable `(value) -> bool | str`; a falsy return or raised `ValueError` becomes a `ValidationError`
+
+## Sources
+
+`load()` accepts one or more file paths (`str` or `pathlib.Path`) or `https://` URLs.
+The format is inferred from the file extension (`.yaml` / `.yml`, `.toml`, `.json`); YAML is the default for unrecognised extensions.
+
+```python
+cfg = load(AppConfig, 'base.yaml', 'prod.yaml')
+```
+
+Sources are applied in order — later sources deep-merge over earlier ones.
+A nested key in a later source only replaces its own subtree,
+leaving sibling keys from earlier sources intact.
+
+### Auto-discovery
+
+When called with no sources, `load()` searches for configuration in standard locations, in this order:
+
+- `~/.config/kaava.toml` — user-level defaults
+- `pyproject.toml`, `[tool.kaava]` section — project-level, if the section exists
+- `kaava.toml`, `kaava.yaml`, or `kaava.json` in the working directory
+
+Later entries override earlier ones via the same deep-merge.
+Passing at least one explicit source skips discovery entirely.
+
+## Environment-variable overlays
+
+Overlays are applied on top of all sources, last-wins.
+
+```python
+from kaava import env_overlay, load
+
+overlay = env_overlay(AppConfig, prefix='APP_')
+cfg = load(AppConfig, 'config.yaml', overlays=[overlay])
+```
+
+With `prefix='APP_'`, the field `db.host` maps to `APP_DB_HOST`.
+An explicit `env=` annotation on a field always takes precedence over the derived name.
+`env_overlay()` reads from `os.environ` by default; pass `environ=` to supply a custom mapping.
+
+### Dotenv files
+
+```python
+from kaava import dotenv_environ, env_overlay, load
+
+environ = dotenv_environ('.env')
+overlay = env_overlay(AppConfig, environ=environ, prefix='APP_')
+cfg = load(AppConfig, 'config.yaml', overlays=[overlay])
+```
+
+`dotenv_environ()` parses `KEY=VALUE` pairs.
+Blank lines and `#` comments are skipped.
+An `export KEY=VALUE` prefix and surrounding quotes are stripped.
+
+### CLI arguments
+
+```python
+from kaava import cli_from_namespace, load
+
+overlay = cli_from_namespace(vars(args))
+cfg = load(AppConfig, 'config.yaml', overlays=[overlay])
+```
+
+`cli_from_namespace()` accepts an `argparse.Namespace` or a plain `dict`.
+Dotted keys (`db.host`) are unflattened into the nested config structure automatically.
+
+## Collecting all errors
+
+`validate()` returns every error as a list without raising, which is useful for CLI tools that want to report all problems at once.
+
+```python
+from kaava import validate
+
+errors = validate(AppConfig, 'config.yaml')
+for e in errors:
+    print(e)
+```
+
+`load_valid()` does the same collection but raises `ConfigErrors` at the end if any errors were found.
+
+## Source tracing and explain
+
+`load_traced()` returns the config kaava together with a `SourceMap` recording where each field value came from.
+
+```python
+from kaava import explain, load_traced
+
+cfg, source_map = load_traced(AppConfig, 'base.yaml', 'prod.yaml')
+print(explain(cfg, source_map))
+```
+
+`explain()` renders a table of field paths, current values, sources, and descriptions.
+Pass `show='non-default'` to show only fields whose value came from a source, not a dataclass default.
+
+## Diagnostics
+
+`doctor()` probes every source, captures all load and validation errors without raising,
+and reports which environment variables declared in the dataclass are set or unset.
+
+```python
+from kaava import doctor
+
+report = doctor(AppConfig, 'config.yaml', prefix='APP_')
+print(report)
+print('ok:', report.ok)
+```
+
+The returned `DoctorReport` has fields `sources_ok`, `sources_failed`, `errors`,
+`set_env`, `unset_env`, `kaava`, and `source_map`.
+`report.ok` is `True` only when no sources failed and no errors were found.
+
+## Ejecting a template
+
+`eject()` prints a YAML scaffold derived from the dataclass schema.
+Required fields are annotated with `# required`; defaults, descriptions, and env-var names appear as inline comments.
+
+```python
+from kaava import eject
+
+print(eject(AppConfig))
+```
+
+## Companion CLI
+
+The `kaava` command exposes the four diagnostic functions as subcommands.
+The target dataclass is identified by a dotted import path of the form `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    myapp.config:AppConfig
+```
+
+See `man kaava` for the full reference, including `--env-prefix`, `--dotenv`, and exit codes.
+
+## 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.

kaava-2026.6.8/README.md

@@ -0,0 +1,204 @@
+# 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 PyYAML; TOML and JSON use the standard library.
+
+## Install
+
+```
+pip install kaava
+```
+
+## Quick start
+
+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/README.md`.
+For a step-by-step tutorial that builds a real command-line tool from scratch, see `tutorial/README.md`.
+
+## Field metadata
+
+`conf_field()` extends `dataclasses.field()` with configuration-specific metadata.
+
+- `default` / `default_factory` — the field's default value or factory
+- `description` — shown in `explain()` output and in YAML templates produced by `eject()`
+- `env` — explicit environment-variable name used by `env_overlay()`
+- `secret` — when `True`, `explain()` masks the value; useful for passwords and API keys
+- `validator` — a callable `(value) -> bool | str`; a falsy return or raised `ValueError` becomes a `ValidationError`
+
+## Sources
+
+`load()` accepts one or more file paths (`str` or `pathlib.Path`) or `https://` URLs.
+The format is inferred from the file extension (`.yaml` / `.yml`, `.toml`, `.json`); YAML is the default for unrecognised extensions.
+
+```python
+cfg = load(AppConfig, 'base.yaml', 'prod.yaml')
+```
+
+Sources are applied in order — later sources deep-merge over earlier ones.
+A nested key in a later source only replaces its own subtree,
+leaving sibling keys from earlier sources intact.
+
+### Auto-discovery
+
+When called with no sources, `load()` searches for configuration in standard locations, in this order:
+
+- `~/.config/kaava.toml` — user-level defaults
+- `pyproject.toml`, `[tool.kaava]` section — project-level, if the section exists
+- `kaava.toml`, `kaava.yaml`, or `kaava.json` in the working directory
+
+Later entries override earlier ones via the same deep-merge.
+Passing at least one explicit source skips discovery entirely.
+
+## Environment-variable overlays
+
+Overlays are applied on top of all sources, last-wins.
+
+```python
+from kaava import env_overlay, load
+
+overlay = env_overlay(AppConfig, prefix='APP_')
+cfg = load(AppConfig, 'config.yaml', overlays=[overlay])
+```
+
+With `prefix='APP_'`, the field `db.host` maps to `APP_DB_HOST`.
+An explicit `env=` annotation on a field always takes precedence over the derived name.
+`env_overlay()` reads from `os.environ` by default; pass `environ=` to supply a custom mapping.
+
+### Dotenv files
+
+```python
+from kaava import dotenv_environ, env_overlay, load
+
+environ = dotenv_environ('.env')
+overlay = env_overlay(AppConfig, environ=environ, prefix='APP_')
+cfg = load(AppConfig, 'config.yaml', overlays=[overlay])
+```
+
+`dotenv_environ()` parses `KEY=VALUE` pairs.
+Blank lines and `#` comments are skipped.
+An `export KEY=VALUE` prefix and surrounding quotes are stripped.
+
+### CLI arguments
+
+```python
+from kaava import cli_from_namespace, load
+
+overlay = cli_from_namespace(vars(args))
+cfg = load(AppConfig, 'config.yaml', overlays=[overlay])
+```
+
+`cli_from_namespace()` accepts an `argparse.Namespace` or a plain `dict`.
+Dotted keys (`db.host`) are unflattened into the nested config structure automatically.
+
+## Collecting all errors
+
+`validate()` returns every error as a list without raising, which is useful for CLI tools that want to report all problems at once.
+
+```python
+from kaava import validate
+
+errors = validate(AppConfig, 'config.yaml')
+for e in errors:
+    print(e)
+```
+
+`load_valid()` does the same collection but raises `ConfigErrors` at the end if any errors were found.
+
+## Source tracing and explain
+
+`load_traced()` returns the config kaava together with a `SourceMap` recording where each field value came from.
+
+```python
+from kaava import explain, load_traced
+
+cfg, source_map = load_traced(AppConfig, 'base.yaml', 'prod.yaml')
+print(explain(cfg, source_map))
+```
+
+`explain()` renders a table of field paths, current values, sources, and descriptions.
+Pass `show='non-default'` to show only fields whose value came from a source, not a dataclass default.
+
+## Diagnostics
+
+`doctor()` probes every source, captures all load and validation errors without raising,
+and reports which environment variables declared in the dataclass are set or unset.
+
+```python
+from kaava import doctor
+
+report = doctor(AppConfig, 'config.yaml', prefix='APP_')
+print(report)
+print('ok:', report.ok)
+```
+
+The returned `DoctorReport` has fields `sources_ok`, `sources_failed`, `errors`,
+`set_env`, `unset_env`, `kaava`, and `source_map`.
+`report.ok` is `True` only when no sources failed and no errors were found.
+
+## Ejecting a template
+
+`eject()` prints a YAML scaffold derived from the dataclass schema.
+Required fields are annotated with `# required`; defaults, descriptions, and env-var names appear as inline comments.
+
+```python
+from kaava import eject
+
+print(eject(AppConfig))
+```
+
+## Companion CLI
+
+The `kaava` command exposes the four diagnostic functions as subcommands.
+The target dataclass is identified by a dotted import path of the form `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    myapp.config:AppConfig
+```
+
+See `man kaava` for the full reference, including `--env-prefix`, `--dotenv`, and exit codes.
+
+## 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.

kaava-2026.6.8/docs/kaava.1

@@ -0,0 +1,222 @@
+.TH INSTANCE 1 "2026-06-09" "kaava 2026.6.8" "User Commands"
+.SH NAME
+kaava \- inspect and diagnose typed dataclass configuration
+.SH SYNOPSIS
+.B kaava
+[\fB\-\-version\fR]
+.I COMMAND
+[\fIoptions\fR]
+.I MODULE:CLASS
+[\fISOURCE\fR ...]
+.SH DESCRIPTION
+.B kaava
+is a companion CLI for the
+.B kaava
+Python library, which loads typed configuration from YAML, TOML, or JSON
+sources into Python dataclasses.
+.PP
+The CLI is intended as an example for library users and as a diagnostic tool
+during development and deployment.
+It exposes four subcommands that exercise the core library surface:
+.BR doctor ,
+.BR explain ,
+.BR validate ,
+and
+.BR eject .
+.PP
+Every subcommand takes a
+.I MODULE:CLASS
+argument that identifies the dataclass to operate on.
+The class is imported at runtime using
+.BR importlib.import_module ,
+so the target package must be importable from the current environment.
+.PP
+Sources are applied in order;
+later sources deep-merge over earlier ones.
+Environment variable overlays and dotenv files are applied on top, last-wins.
+.SH SUBCOMMANDS
+.TP
+.B doctor
+Probe every source, capture all load and validation errors without raising,
+and report which env vars are set or unset in the current environment.
+Exits 0 if the configuration is fully valid, 1 if any error or source failure
+was found.
+.TP
+.B explain
+Load the configuration with source tracing and print a table showing each
+field's current value, the source it came from, and its description (if any).
+Exits 0 on success, 1 if the configuration could not be loaded.
+.TP
+.B validate
+Collect all configuration errors without building the config kaava and
+print them to standard error.
+Exits 0 if the configuration is valid, 1 if errors were found.
+.TP
+.B eject
+Print a YAML template scaffold derived from the dataclass schema.
+Required fields are annotated with
+.IR # required .
+Default values, descriptions, env var names, and enum choices appear as
+inline comments.
+Exits 0.
+.SH OPTIONS
+The following options apply to
+.BR doctor ,
+.BR explain ,
+and
+.BR validate .
+.B eject
+takes only
+.IR MODULE:CLASS .
+.TP
+.BI \-\-env\-prefix " PREFIX"
+Derive environment variable names automatically from field paths using
+.IR PREFIX .
+For example,
+.B \-\-env\-prefix APP_
+maps
+.B db.host
+to
+.BR APP_DB_HOST .
+An explicit
+.B env=
+annotation on a field always takes precedence over the derived name.
+.TP
+.BI \-\-dotenv " PATH"
+Read environment variables from a
+.IR .env -format
+file instead of the process environment.
+The file is parsed as
+.IB KEY = VALUE
+pairs; blank lines and lines beginning with
+.B #
+are ignored;
+.B export KEY=VALUE
+prefix is stripped; quoted values are unquoted.
+.SH MODULE:CLASS
+The first positional argument to every subcommand is a dotted import path of
+the form
+.IB module.path : ClassName .
+The module is imported with
+.B importlib.import_module
+and the class is looked up by name.
+The target package must be installed or otherwise reachable on
+.B sys.path
+in the active Python environment.
+.PP
+Examples:
+.RS
+.PP
+.B myapp.config:AppConfig
+.br
+.B myapp.settings:DatabaseConfig
+.RE
+.SH EXIT STATUS
+.TP
+.B 0
+Success.
+For
+.B doctor
+and
+.BR validate ,
+the configuration is fully valid.
+For
+.BR explain ,
+the configuration was loaded and the table was printed.
+For
+.BR eject ,
+the YAML template was printed.
+.TP
+.B 1
+Configuration errors were found (
+.BR doctor ,
+.BR validate )
+or the configuration could not be loaded (
+.BR explain ).
+.TP
+.B 2
+A usage error occurred: an invalid
+.I MODULE:CLASS
+spec, a module that could not be imported, a class not found in the module,
+or a
+.B \-\-dotenv
+file that could not be read.
+.SH EXAMPLES
+Check whether a configuration is fully valid:
+.PP
+.RS
+.B kaava doctor myapp.config:AppConfig config.yaml
+.RE
+.PP
+Check with prefix-derived env vars (reads
+.BR APP_DB_HOST ,
+.BR APP_NAME ,
+etc. from the environment):
+.PP
+.RS
+.B kaava doctor myapp.config:AppConfig config.yaml \-\-env\-prefix APP_
+.RE
+.PP
+Use a
+.I .env
+file instead of the process environment:
+.PP
+.RS
+.B kaava doctor myapp.config:AppConfig config.yaml \-\-dotenv .env
+.RE
+.PP
+Show all field values and their sources after loading:
+.PP
+.RS
+.B kaava explain myapp.config:AppConfig config.yaml
+.RE
+.PP
+Show only fields that were overridden from a source (not at their dataclass default):
+.PP
+.RS
+.B kaava explain myapp.config:AppConfig config.yaml \-\-non\-default
+.RE
+.PP
+Merge two sources (the second overrides the first where keys overlap):
+.PP
+.RS
+.B kaava explain myapp.config:AppConfig base.yaml prod.yaml
+.RE
+.PP
+Validate without building the kaava, collecting all errors:
+.PP
+.RS
+.B kaava validate myapp.config:AppConfig config.yaml
+.RE
+.PP
+Generate a YAML template for a config class:
+.PP
+.RS
+.B kaava eject myapp.config:AppConfig
+.RE
+.PP
+Redirect the template to a file:
+.PP
+.RS
+.B kaava eject myapp.config:AppConfig > config.yaml
+.RE
+.SH FILES
+.TP
+.B quickstart/README.md
+Feature-by-feature tour of the library API, with code snippets for each concept.
+.TP
+.B tutorial/README.md
+Step-by-step tutorial that builds a complete command-line tool, one kaava feature
+per step, with runnable code at every stage.
+.SH SEE ALSO
+The
+.B kaava
+library README documents the Python API:
+.BR load (),
+.BR validate (),
+.BR doctor (),
+.BR eject (),
+.BR conf_field (),
+and the overlay system.
+.PP
+.BR python (1)