dature#

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.

Features#

• Type-safe — automatic conversion from strings to all Python types (int, float, bool, date, datetime, Enum, IPv4Address, etc.) and nested dataclasses
• Multiple formats — YAML (1.1, 1.2), JSON, JSON5, TOML (1.0, 1.1), INI, ENV, Docker secrets, environment variables
• Merge sources — combine defaults, overrides, and env vars with configurable strategies
• Validation — built-in validators via Annotated, root validators, custom validators
• Secret masking — auto-detect and mask secrets in errors, logs, and debug reports
• Human-readable errors — source location, line numbers, and formatted context
• Two modes — function call or decorator with caching

Installation#

pip install dature

uv add dature

poetry add dature

Optional format support#

pip install dature[yaml]    # YAML support (ruamel.yaml)
pip install dature[json5]   # JSON5 support
pip install dature[toml]    # TOML support (toml_rs)
pip install dature[secure]  # Secret detection heuristics

pip install dature[yaml,json5,toml,secure]

uv add dature[yaml]    # YAML support (ruamel.yaml)
uv add dature[json5]   # JSON5 support
uv add dature[toml]    # TOML support (toml_rs)
uv add dature[secure]  # Secret detection heuristics

uv add dature[yaml,json5,toml,secure]

poetry add dature[yaml]    # YAML support (ruamel.yaml)
poetry add dature[json5]   # JSON5 support
poetry add dature[toml]    # TOML support (toml_rs)
poetry add dature[secure]  # Secret detection heuristics

poetry add dature[yaml,json5,toml,secure]

Quick Start#

"""Function mode — load config from environment variables."""

import os
from dataclasses import dataclass

import dature

os.environ["APP_HOST"] = "0.0.0.0"
os.environ["APP_PORT"] = "8080"
os.environ["APP_DEBUG"] = "true"


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


config = dature.load(dature.EnvSource(prefix="APP_"), schema=AppConfig)

assert config.host == "0.0.0.0"
assert config.port == 8080
assert config.debug is True

"""Decorator mode — auto-load config on instantiation."""

import os
from dataclasses import dataclass

import dature

os.environ["APP_HOST"] = "0.0.0.0"
os.environ["APP_PORT"] = "8080"
os.environ["APP_DEBUG"] = "true"


@dature.load(dature.EnvSource(prefix="APP_"))
@dataclass
class AppConfig:
    host: str
    port: int
    debug: bool = False


config = AppConfig()

assert config.host == "0.0.0.0"
assert config.port == 8080
assert config.debug is True

Supported Formats#

Use the specific Source subclass for your format. File-based sources (FileSource subclasses) accept file as str, Path, or file-like object (BytesIO, StringIO). EnvSource reads from environment variables (no file parameter). DockerSecretsSource accepts dir pointing to a secrets directory.

mypy Plugin#

When using @dature.load() as a decorator, mypy will report call-arg errors because the original dataclass __init__ still requires all fields. dature ships with a mypy plugin that makes all fields optional in decorated classes:

[tool.mypy]
plugins = ["dature.mypy_plugin"]

What's Next#

• Introduction — function vs decorator mode, all formats, Source reference
• Naming — name_style, field_mapping, prefix, nested_sep
• Validation — Annotated validators, root validators, custom validators
• Merging — multiple sources, strategies, field groups
• Masking — SecretStr, auto-detection, configuration
• API Reference — full API documentation