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.

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:

Source: performance baseline (same machine, same iteration count).

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