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.

Versioning: tomlclass is pre-1.0 and does not strictly follow SemVer yet. Before the project stabilizes, minor version bumps may include new API additions — existing APIs will remain backward compatible.

Features

• Lossless editing engine: TOML 1.0/1.1 parse and write-back; the only library with a perfect 187/187 on toml-test 1.5.0 valid tests. Untouched documents render byte-identical to input
• TOML 1.1 with a version dial: \e / \x escapes, seconds-optional times, newlines and trailing commas in inline tables, non-ASCII bare keys — on by default; pass toml_version="1.0" to parse / loads / load / update / Config.load for strict legacy rejection semantics
• None your way: opt-in rtoml-style none_value sentinel — dumps(data, none_value="@None") and loads(text, none_value="@None") round-trip None through TOML strings
• 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

TOML version boundary: the 1.1 additions above are accepted by default. If your code relies on rejecting 1.0-invalid input (e.g. 13:37 times), switch to toml_version="1.0" — the same files then raise TOMLParseError.

Conformance & performance

Measured with toml-bench (toml-test 1.5.0 + CPython tomllib test data; speed = load/dump over 5000 iterations on one machine, tomlclass 0.2.0 — methodology in the benchmark baseline):

Speed (load / dump, 5000 iterations):

Lossless editing pays for bookkeeping: loads run ~2.5–2.8× tomli, dumps ~2.6–3.2× tomli_w — and 12–14× faster than tomlkit.

Installation## Installation

pip install tomlclass

Usage

Change one value, keep everything else

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)

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

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 — parse, edit, update(), comment API, errors
• Config — schema declaration, template, load/save semantics, validation errors
• Comments — comment ownership, injection modes
• Examples — end-to-end scenarios
• Performance — measured baseline

Docs are also available in 简体中文, 繁體中文, 日本語 and Русский.

Requirements

Python ≥ 3.10, no third-party dependencies.

License

MIT