---

Documentation | Changelog

Type-safe configuration loader for Python dataclasses. Load config from YAML, JSON, TOML, INI, ENV files, environment variables, Docker secrets, CLI arguments, HashiCorp Vault, Consul, etcd, Apache ZooKeeper, AWS SSM, AWS Secrets Manager, Azure App Configuration, Azure Key Vault, and GCP Secret Manager — with automatic type conversion, validation, and human-readable error messages.

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[consul]     # Consul (py-consul)
pip install dature[etcd]       # etcd (etcd3gw)
pip install dature[zookeeper]  # Apache ZooKeeper (kazoo)
pip install dature[aws]        # AWS SSM & Secrets Manager (boto3)
pip install dature[azure-appconfig] # Azure App Configuration
pip install dature[azure-keyvault]  # Azure Key Vault
pip install dature[gcp]        # GCP Secret Manager
pip install dature[secure]     # Secret detection heuristics
pip install dature[type-stubs] # Type stubs for the integrations above (mypy/pyright users)

from dataclasses import dataclass

import dature


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


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

• Multiple sources — YAML, JSON, JSON5, TOML, INI, ENV, environment variables, Docker secrets, CLI args (argparse or your own), HashiCorp Vault, Consul, etcd, Apache ZooKeeper, AWS SSM, AWS Secrets Manager, Azure App Configuration, Azure Key Vault, GCP Secret Manager
• 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
• CLI — dature validate and dature inspect console commands for CI and debugging
• Cross-source refs & conditional sources — reference values across sources, activate sources based on environment
• Extensible — plug in custom sources, type loaders, and remote backends via SourceProtocol

See the documentation for detailed guides and API reference.

• Python >= 3.12
• adaptix >= 3.0.0b11

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

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:

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

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

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.

Apache License 2.0