---

Documentation | Changelog

Type-safe configuration loader for Python dataclasses. Load config from YAML, JSON, TOML, INI, ENV files, environment variables, Docker secrets, CLI arguments, and HashiCorp Vault — with automatic type conversion, validation, and human-readable error messages.

Installation

pip install dature

With optional format support:

pip install dature[yaml]       # YAML (ruamel.yaml)
pip install dature[json5]      # JSON5
pip install dature[toml]       # TOML (toml_rs)
pip install dature[vault]      # HashiCorp Vault (hvac)
pip install dature[secure]     # Secret detection heuristics
pip install dature[type-stubs] # Type stubs for the integrations above (mypy/pyright users)

Quick Start

from dataclasses import dataclass

import dature


@dataclass
class Config:
    host: str
    port: int
    debug: bool = False


config = dature.load(dature.Yaml12Source(file="config.yaml"), Config)

Key Features

• Multiple sources — YAML, JSON, JSON5, TOML, INI, ENV, environment variables, Docker secrets, CLI args (argparse), HashiCorp Vault
• Merging — combine multiple sources with configurable strategies ("last_wins", "first_wins", "raise_on_conflict")
• Validation — Annotated field validators, root validators, __post_init__ support
• Naming — automatic field name mapping (snake_case ↔ camelCase ↔ UPPER_SNAKE etc.)
• Secret masking — automatic masking in error messages and logs by field type, name, or heuristic
• ENV expansion — $VAR, ${VAR:-default} substitution in all file formats
• Special types — SecretStr, ByteSize, PaymentCardNumber, URL, Base64UrlStr
• Debug report — debug=True shows which source provided each field value
• Decorator mode — @dature.load(meta) auto-loads config on dataclass instantiation with caching

See the documentation for detailed guides and API reference.

Requirements

• Python >= 3.12
• adaptix >= 3.0.0b11

Development

git clone https://github.com/reagento/dature.git
cd dature
uv sync --all-extras --all-groups

Run tests:

uv run pytest tests/ -v

Lint and type check:

uv run prek run --all-files

Build docs locally:

uv run mkdocs serve

Changelog

Each PR must include a towncrier fragment in the changes/ directory:

# Format: changes/<issue-or-pr-number>.<type>
echo "Added support for YAML anchors." > changes/42.feature

Available <type> values:

Type	Description
feature	New features
bugfix	Bug fixes
doc	Documentation improvements
removal	Deprecations and removals
misc	Other changes

Use +<description> instead of an issue number for changes without a linked issue:

echo "Fixed typo in error message." > changes/+fix-typo.bugfix.md

Releasing

1. Run the Release workflow and choose bump type (patch / minor / major). The next version is calculated from the latest git tag automatically.
2. The workflow builds the changelog from fragments and creates a PR.
3. Merge the PR — CI automatically creates the tag, publishes to PyPI, creates a GitHub Release, and updates docs.

License

Apache License 2.0