Metadata-Version: 2.5
Name: tomlclass
Version: 0.1.3
Summary: Annotation-driven TOML configuration with comment preservation — declare classes, keep your config files human.
Project-URL: Homepage, https://github.com/wsu2059q/tomlclass
Project-URL: Repository, https://github.com/wsu2059q/tomlclass
Project-URL: Issues, https://github.com/wsu2059q/tomlclass/issues
Project-URL: Changelog, https://github.com/wsu2059q/tomlclass/blob/main/CHANGELOG.md
Author: wsu2059q
License-Expression: MIT
License-File: LICENSE
Keywords: comments,config,configuration,dataclass,declarative,toml
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: lint
Requires-Dist: basedpyright>=1.20; extra == 'lint'
Requires-Dist: ruff>=0.8; extra == 'lint'
Provides-Extra: test
Requires-Dist: pytest-cov>=5.0; extra == 'test'
Requires-Dist: pytest-timeout>=2.3; extra == 'test'
Requires-Dist: pytest-xdist>=3.5; extra == 'test'
Requires-Dist: pytest>=8.0; extra == 'test'
Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'test'
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/wsu2059q/tomlclass/main/.github/assets/tomlclass-logo.svg" alt="tomlclass" width="520">
</p>

# tomlclass

Lossless TOML editing and typed configuration in one zero-dependency package.

Change one value in a config file without breaking a single comment; declare schemas as Python classes to get commented templates, aggregated validation and diff-based write-back.

<p>
  <a href="https://pypi.org/project/tomlclass/"><img src="https://img.shields.io/pypi/v/tomlclass?style=for-the-badge&logo=pypi&logoColor=white" alt="PyPI"></a>
  <a href="https://pypi.org/project/tomlclass/"><img src="https://img.shields.io/badge/Python-3.10+-FFD43B?style=for-the-badge&logo=python&logoColor=blue" alt="Python"></a>
  <a href="https://github.com/wsu2059q/tomlclass/actions/workflows/code-quality-check.yml"><img src="https://img.shields.io/github/actions/workflow/status/wsu2059q/tomlclass/code-quality-check.yml?style=for-the-badge&label=CI" alt="CI"></a>
  <a href="https://github.com/wsu2059q/tomlclass/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue?style=for-the-badge" alt="License"></a>
  <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json&style=for-the-badge" alt="Ruff"></a>
</p>

<br clear="both">

---

## Features

- **Lossless editing engine**: full-type TOML 1.0/1.1 parse and write-back; all 709 toml-test 1.0 cases pass. Untouched documents render byte-identical to input
- **One-line updates**: `tomlclass.update("app.toml", {"server.port": 9090})` — read, change, atomically write back; comments, ordering and formatting survive everywhere else
- **Typed config**: declare the schema as classes — docstrings become template comments, validation aggregates all errors with each field's documented intent, defaults are merged in memory and never written back
- **Comment operations**: read, replace and delete comments per key; schema descriptions can be injected as comments (three strategies)
- **tomllib compatible**: `loads` / `load` follow the stdlib calling convention — migrating costs nothing

## Why not tomlkit

tomlkit is the de facto standard for lossless editing, and this project's engine was built against it as a baseline. Where tomlclass wins:

| Dimension | tomlkit 0.15 | tomlclass 0.1 |
|---|---|---|
| Parse speed (same machine) | baseline | **5.8–6.4× faster** |
| Getting a plain dict | `parse(dumps(doc))` round trip | `to_dict()` builds it directly, zero round trip |
| Comment operations | buried in style objects, no per-key API | `doc.comment(key)` / `set_comment` as first-class citizens |
| Schema / template / validation | none — assemble it yourself | built into `Config` (template, aggregate validation, env overrides, migration) |
| Resident memory | baseline | **0.67×** |

Source: [performance baseline](https://github.com/wsu2059q/tomlclass/blob/main/tests/bench/BASELINE.md) (same machine, same iteration count).

## Installation

```bash
pip install tomlclass
```

## Usage

### Change one value, keep everything else

```python
import tomlclass

tomlclass.update("pyproject.toml", {"project.version": "1.0.0"})
# only that line changed — comments, ordering and formatting all intact
```

### Editing a TOML file (full control)

```python
import tomlclass

doc = tomlclass.parse(text)
doc["project"]["version"] = "1.0.0"
doc["project"]["dependencies"].append("rich>=13.0")  # spliced in place, comments kept
text = doc.dumps()                                   # only touched lines change
```

### Declarative config

```python
from tomlclass import Config

class Server(Config):
    """
    HTTP server settings.

    host:
        Address to bind.
    port:
        Port to listen on.
    """

    host: str = "127.0.0.1"
    port: int = 8000


server = Server.load("server.toml")  # read + validate + merge defaults
server.port = 9000
server.save("server.toml")           # only changed keys are written
```

## Documentation

- [Engine](https://github.com/wsu2059q/tomlclass/blob/main/docs/en/engine.md) — parse, edit, `update()`, comment API, errors
- [Config](https://github.com/wsu2059q/tomlclass/blob/main/docs/en/config.md) — schema declaration, template, load/save semantics, validation errors
- [Comments](https://github.com/wsu2059q/tomlclass/blob/main/docs/en/comments.md) — comment ownership, injection modes
- [Examples](https://github.com/wsu2059q/tomlclass/blob/main/docs/en/examples.md) — end-to-end scenarios
- [Performance](https://github.com/wsu2059q/tomlclass/blob/main/docs/en/performance.md) — measured baseline

Docs are also available in [简体中文](https://github.com/wsu2059q/tomlclass/blob/main/docs/zh-CN/index.md), [繁體中文](https://github.com/wsu2059q/tomlclass/blob/main/docs/zh-TW/index.md), [日本語](https://github.com/wsu2059q/tomlclass/blob/main/docs/ja/index.md) and [Русский](https://github.com/wsu2059q/tomlclass/blob/main/docs/ru/index.md).

## Requirements

Python ≥ 3.10, no third-party dependencies.

## License

[MIT](https://github.com/wsu2059q/tomlclass/blob/main/LICENSE)
