Metadata-Version: 2.4
Name: dature
Version: 0.15.0
Summary: Type-safe configuration loader for Python dataclasses with support for YAML, JSON, TOML, INI, ENV and environment variables
Project-URL: Homepage, https://github.com/Niccolum/dature
Project-URL: Repository, https://github.com/Niccolum/dature
Project-URL: Issues, https://github.com/Niccolum/dature/issues
Project-URL: Documentation, https://dature.readthedocs.io/
Author-email: Niccolum <lastsal@mail.ru>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: config,configuration,dataclass,env,ini,json,json5,loader,settings,toml,type-safe,yaml
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: adaptix>=3.0.0b11
Provides-Extra: json5
Requires-Dist: json-five>=1.1.2; extra == 'json5'
Provides-Extra: secure
Requires-Dist: random-string-detector>=1.1.1; extra == 'secure'
Provides-Extra: toml
Requires-Dist: toml-rs>=0.3.4; extra == 'toml'
Provides-Extra: yaml
Requires-Dist: ruamel-yaml>=0.18; extra == 'yaml'
Description-Content-Type: text/markdown

# dature

---

<div align="center">

[![PyPI](https://img.shields.io/pypi/v/dature)](https://pypi.org/project/dature/)
[![Supported Python versions](https://img.shields.io/pypi/pyversions/dature)](https://pypi.org/project/dature/)
[![Documentation](https://readthedocs.org/projects/dature/badge/?version=latest)](https://dature.readthedocs.io/)
[![License](https://img.shields.io/github/license/Niccolum/dature.svg)](https://github.com/Niccolum/dature/blob/main/LICENSE)
\
[![CI](https://github.com/Niccolum/dature/actions/workflows/ci.yml/badge.svg)](https://github.com/Niccolum/dature/actions/workflows/ci.yml)
[![CodeQL](https://github.com/Niccolum/dature/actions/workflows/scorecard.yml/badge.svg)](https://github.com/Niccolum/dature/actions/workflows/scorecard.yml)
[![Dependency Review](https://github.com/Niccolum/dature/actions/workflows/dependency-review.yml/badge.svg)](https://github.com/Niccolum/dature/actions/workflows/dependency-review.yml)
\
[![Monthly downloads](https://static.pepy.tech/badge/dature/month)](https://pypi.org/project/dature/)
[![Commits since latest release](https://img.shields.io/github/commits-since/Niccolum/dature/latest?logo=github)](https://github.com/Niccolum/dature/commits)
[![Last commit date](https://img.shields.io/github/last-commit/Niccolum/dature?logo=github&label=Last%20Commit)](https://github.com/Niccolum/dature/commits)
[![Last release date](https://img.shields.io/github/release-date/Niccolum/dature?logo=github&label=Release%20Date)](https://github.com/Niccolum/dature/releases)

</div>

**[Documentation](https://dature.readthedocs.io/)** | **[Changelog](https://dature.readthedocs.io/en/latest/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

```bash
pip install dature
```

With optional format support:

```bash
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

```python
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](https://dature.readthedocs.io/)** for detailed guides and API reference.

## Requirements

- Python >= 3.12
- [adaptix](https://github.com/reagento/adaptix) >= 3.0.0b11

## Development

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

Run tests:

```bash
uv run pytest tests/ -v
```

Lint and type check:

```bash
uv run prek run --all-files
```

Build docs locally:

```bash
uv run mkdocs serve
```

## License

Apache License 2.0
