Skip to main content

tomlclass

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.

PyPI Python CI License Ruff



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):

Check tomlclass 0.3.0
toml-test files-toml-1.0.0 (strict 1.0 mode) 205/205 valid, 474/474 invalid
toml-test files-toml-1.1.0 (default 1.1 mode) 214/214 valid, 467/467 invalid

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):

Library rtoml corpus tomli corpus
rtoml 0.11 (Rust) 0.72s / 0.16s 0.52s / 0.33s
tomli 2.4 + tomli_w 1.52s / 1.17s 1.26s / 0.84s
tomllib (CPython) 3.39s / — 2.15s / —
tomlclass 0.2.x 4.26s / 3.80s 3.12s / 2.22s
qtoml 0.3 7.78s / 2.97s 6.35s / 1.97s
tomlkit 0.15 60.45s / 1.75s 36.88s / 0.81s

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

Metadata

Release files for tomlclass 0.3.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tomlclass 0.3.3
File Size Uploaded Provenance Actions
tomlclass-0.3.3.tar.gz 284.7 kB With provenance Details for tomlclass-0.3.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tomlclass 0.3.3
File Interpreter ABI Platform Actions
tomlclass-0.3.3-py3-none-any.whl Python 3 none any Details for tomlclass-0.3.3-py3-none-any.whl

Total release size: 346.3 kB

Release files / tomlclass-0.3.3.tar.gz

Download URL tomlclass-0.3.3.tar.gz
Size 284.7 kB
Tags Source
SHA-256 checksum
How to use checksums
af1eac770838c4c45a0febe9cc96f9c1816db1dd30ad9cd906afc55ddd6cafa8
BLAKE2b-256 checksum
How to use checksums
a3a0ad550b4d0d0de84983e565f1f014c80be6b89751441f669c506d7896ed94
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.

Transparency log

Release files / tomlclass-0.3.3-py3-none-any.whl

Download URL tomlclass-0.3.3-py3-none-any.whl
Size 61.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a7d29d3d71b4d5defd307b69bc7b942e83e0200a4a091a5723569a7920aa9429
BLAKE2b-256 checksum
How to use checksums
4bdeb7dab8e75e80a4d690b9122a5236541829c2a4797e7d7292c0bf18881e5b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.

Transparency log

Security for tomlclass 0.3.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for tomlclass-0.3.3.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page