dature 0.15.1

Type-safe configuration loader for Python dataclasses with support for YAML, JSON, TOML, INI, ENV and environment variables

dature

---

Documentation | Changelog

Type-safe configuration loader for Python dataclasses. Load config from YAML, JSON, TOML, INI, ENV files, environment variables, and Docker secrets — 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[secure]  # Secret detection heuristics

Quick Start

from dataclasses import dataclass
from dature import Source, load

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

config = load(Source(file_="config.yaml"), Config)

Key Features

• Multiple formats — YAML, JSON, JSON5, TOML, INI, ENV, environment variables, Docker secrets
• 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 — @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/Niccolum/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>
# Types: feature, bugfix, doc, removal, misc
echo "Added support for YAML anchors." > changes/42.feature

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

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

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