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.

The configuration semantics come from the ErisPulse framework's config system.

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

• Typed config with schema: declare the structure as annotated classes — docstrings become template comments, validation aggregates all errors with each field's documented intent, defaults are merged in memory and never written back
• Lossless editing engine: TOML 1.0/1.1 parse and write-back; untouched documents render byte-identical to input. Full official toml-test coverage: both the 1.0 and 1.1 manifests pass (205/474 + 214/467)
• Comment operations: read, replace and delete comments per key — on tables, dotted keys and array-of-tables elements; schema descriptions can be injected as comments
• TOML 1.1 with a version dial: \e / \x escapes, seconds-optional times, newlines and trailing commas in inline tables — on by default; pass toml_version="1.0" for strict legacy rejection
• tomllib compatible: loads / load follow the stdlib calling convention; dump / load_path and a from-scratch builder (document() / table() / aot()) complete the surface

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

Conformance against the official toml-test suite (both manifests, live-pinned at toml-test v2.2.0, verified in CI on Linux, Windows and macOS):

Speed measured with toml-bench (toml-test 1.5.0 + CPython tomllib test data; load/dump over 5000 iterations on one machine — methodology in the benchmark baseline):

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. 0.3.0 adds no parse regression (±4% vs 0.1.0 on the in-repo baseline).

Installation

pip install tomlclass

Usage

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
Server.template()                    # commented starter template from the schema

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

Documentation

• Engine — parse, edit, path addressing, update(), comment API, errors
• Config — schema declaration, template, load/save semantics, validation errors
• Comments — comment addressability, injection modes
• Migration — from tomlkit, and from 0.2.x
• Examples — end-to-end scenarios

Docs are also available in 简体中文.

Requirements

Python ≥ 3.10, no third-party dependencies.

License

MIT