English | 简体中文 | 繁體中文 | 日本語 | Русский

tomlclass

TOML configuration library: a home-grown lossless editing engine plus typed config annotations. Zero third-party dependencies.

Writing a config file back keeps every comment and every bit of formatting intact; declare the structure as Python classes to get a commented template with validation. The configuration semantics come from the ErisPulse framework's config system.

Features

• Lossless editing engine: full-type TOML 1.0 parse and write-back; all 709 toml-test 1.0 cases pass. Untouched documents render byte-identical to input
• Typed config: declare the schema as classes, docstrings become template comments, validation aggregates all errors, 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 designed against it as a baseline. Where tomlclass wins:

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

Installation

pip install tomlclass

Usage

Editing a TOML file

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 — Document, editing, tomllib compatibility, errors
• Annotations — Config, Field, view semantics, env overrides
• Comments — ownership model, reading and replacing
• Examples — common scenarios
• Performance — baseline numbers and measurements
• Design — layers, semantics, test strategy

Requirements

Python ≥ 3.10, no third-party dependencies.

License

MIT