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: on the toml-bench harness above, loads run ~2.8× tomli; the current same-process in-repo baseline (2026-10) reads parsing at 1.2–1.6× tomli — inside its ≤2× budget — with parse + edit + dumps cycles 6–10× faster than tomlkit on the same edits, and edit cost scaling with edit size, not document length.

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.4.0

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.4.0
File Size Uploaded Provenance Actions
tomlclass-0.4.0.tar.gz 288.0 kB With provenance Details for tomlclass-0.4.0.tar.gz

Built distribution (wheel)

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

Total release size: 351.5 kB

Release files / tomlclass-0.4.0.tar.gz

Download URL tomlclass-0.4.0.tar.gz
Size 288.0 kB
Tags Source
SHA-256 checksum
How to use checksums
b545572b19491764cd1829d8dcb3a9beb671c9e2b410170efe1cd4b896ccc8be
BLAKE2b-256 checksum
How to use checksums
a34c469828a15f88edab87636a1abac1e79bd388d354f94af1ed065db30cd02f
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.4.0-py3-none-any.whl

Download URL tomlclass-0.4.0-py3-none-any.whl
Size 63.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
14286ee4713a564d750400cf7f6fe3d49dc7bc3825fd308a6b6883b0f41b7516
BLAKE2b-256 checksum
How to use checksums
abf7183a76c17d152dcf152913602adccb77af1bce575f08de2d00e3a172432f
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.4.0

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.4.0.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