tomlrt 0.1.0__tar.gz

tomlrt-0.1.0/.github/copilot-instructions.md

@@ -0,0 +1,131 @@
+# Instructions for AI coding agents
+
+This file is read by GitHub Copilot, Copilot CLI, and similar agents
+when they work in this repository. Humans are welcome to read it too —
+it doubles as a high-signal contributor guide.
+
+## What this project is
+
+`tomlrt` is a **pure-Python, format-preserving** TOML parser and
+writer. The non-negotiable invariant is:
+
+> Parsing a document and dumping it again, with no mutations in
+> between, must return the **exact same bytes** — including comments,
+> whitespace, string style (literal vs basic, single vs multiline),
+> number formatting, and line endings (LF vs CRLF).
+
+If a change you are about to make could break that, stop and rethink.
+
+## Toolchain
+
+- **`uv`** is the only supported package/dependency manager. Do not
+  introduce `pip`, `poetry`, `pipenv`, `tox`, `nox`, `setuptools`, or
+  `requirements.txt`.
+- Build backend is **`hatchling`**.
+- Supported Python versions: **3.10 – 3.14**.
+
+## Common commands
+
+```bash
+uv sync                          # install dev deps
+uv run pytest -q                 # run the test suite (~1s)
+uv run pytest --cov              # tests + branch coverage
+uv run mypy                      # strict type-check src/ and tests/
+uv run ruff check .              # lint
+uv run ruff format .             # apply formatting
+uv run ruff format --check .     # CI-style format check
+```
+
+All four checks (`pytest`, `mypy`, `ruff check`, `ruff format --check`)
+must pass before any commit. CI runs the same set on Python 3.10–3.14.
+
+## Coding standards
+
+- **`mypy --strict`** clean — no `# type: ignore` without a specific
+  error code, and ideally no ignores at all. Prefer fixing the type.
+- **`ruff` with `select = ["ALL"]`** clean — see `[tool.ruff.lint.ignore]`
+  in `pyproject.toml` for the curated exceptions. Do not add new
+  per-line `# noqa` without a strong reason.
+- **`ruff format`** is the source of truth for formatting. Run it
+  before committing.
+- **No runtime dependencies.** The project is and will remain pure
+  stdlib. Only `dependency-groups.dev` may grow, and only with care.
+- **No `cast()` in user-facing code paths.** Tests should not need
+  `cast()` either; the typed accessors `Table.array(k)`,
+  `Table.table(k)`, `Table.aot(k)`, `Array.array(i)`, `Array.table(i)`
+  exist precisely to avoid this.
+- **`from __future__ import annotations`** at the top of every module
+  (enforced by ruff's isort `required-imports`).
+- Do not add comments that merely restate the code. Comment intent and
+  invariants, not mechanics.
+
+## Architecture (in `src/tomlrt/`)
+
+The codebase is small and deliberately layered. Read in this order:
+
+- **`_nodes.py`** — the **concrete syntax tree (CST)**: dataclasses
+  that hold every byte of the original source (including trivia,
+  comments, and the literal lexeme of every value). Mutate these only
+  through helpers that maintain the round-trip invariant.
+- **`_parser.py`** — hand-written recursive-descent parser, TOML 1.0 +
+  1.1, that produces the CST. Performance-sensitive: prefer bulk
+  `str` scans over per-character loops.
+- **`_synthesise.py`** — converts plain Python values (`str`, `int`,
+  `bool`, `datetime`, `list`, `dict`, …) into newly synthesised CST
+  nodes when the user assigns into the document.
+- **`_document.py`** — the **logical view layer**: `Document`, `Table`,
+  `Array`, `AoT` wrappers that present a dict/list-shaped API while
+  delegating all mutation to the CST. The Comment API and typed
+  accessors live here. This is by far the largest file.
+- **`_public.py`** — the top-level `parse` / `loads` / `load` /
+  `dumps` / `dump` functions. `load` and `dump` require **binary**
+  file objects (`IO[bytes]`); text mode would silently translate
+  newlines on Windows and break round-tripping.
+- **`_errors.py`** — public exception hierarchy.
+- **`__init__.py`** — re-exports the public API; keep `__all__`
+  alphabetised.
+
+When in doubt: a change that touches only one of these layers is
+usually right; a change that has to touch all of them is usually wrong.
+
+## Tests
+
+- `tests/test_basic.py`, `test_spacing.py`, `test_edit_golden.py` —
+  parser and writer regressions, including byte-exact round-trip
+  fixtures.
+- `tests/test_comments.py` — the comment manipulation API.
+- `tests/test_compliance.py` — the official **`toml-test`** suite
+  (vendored under `vendor/`). Do not edit fixtures there to make
+  failures pass.
+- `tests/test_toml11.py` — TOML 1.1-specific coverage.
+- `tests/test_hypothesis.py` — property-based round-trip tests. If you
+  break round-tripping, this will usually catch it; add new strategies
+  here when you add a new construct.
+- `tests/test_mutation.py` — the dict/list mutation API.
+- `tests/test_synthesise_and_io.py` — value synthesis and binary I/O.
+
+When adding behaviour, add a focused unit test in the relevant file
+**and** consider whether the property tests should grow.
+
+## Things to avoid
+
+- Adding a runtime dependency.
+- Reaching into `_nodes` from user-facing code instead of going through
+  `_document`.
+- "Fixing" formatting differences in the writer's output without
+  adding a round-trip test that proves it.
+- Touching `vendor/` (it is third-party, vendored verbatim).
+- Editing `uv.lock` by hand — let `uv` regenerate it.
+- Bumping action versions in `.github/workflows/*.yml` to a tag instead
+  of a 40-char commit SHA. The workflows are **`zizmor` clean** and
+  must stay that way (`uv tool run zizmor .`).
+
+## Commit conventions
+
+- Subject line: imperative mood, ≤ ~70 chars, no trailing period.
+- Body: wrap around 72 chars; explain *why* not *what*. Bullets are
+  fine.
+- One logical change per commit. Keep mechanical reformat passes
+  separate from substantive changes.
+- Append a `Co-authored-by` trailer when an AI agent did the work, e.g.
+  `Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>`.

tomlrt-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,68 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions: {}
+
+jobs:
+  test:
+    name: test (py${{ matrix.python-version }} on ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-latest
+        python-version:
+          - "3.10"
+          - "3.11"
+          - "3.12"
+          - "3.13"
+          - "3.14"
+          - "3.15"
+        include:
+          - os: macos-latest
+            python-version: "3.14"
+          - os: windows-latest
+            python-version: "3.14"
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Set up python {{ matrix.python-version }}
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          allow-prereleases: true
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+
+      - name: Check lockfile
+        run: uv lock --check
+
+      - name: Install project
+        run: uv sync -p ${{ matrix.python-version }}
+
+      - name: Install ruff
+        uses: astral-sh/ruff-action@0ce1b0bf8b818ef400413f810f8a11cdbda0034b # v4.0.0
+
+      - name: ruff check
+        run: ruff check .
+
+      - name: ruff format
+        run: ruff format --check .
+
+      - name: pytest
+        run: uv run pytest
+
+      - name: mypy
+        run: uv run mypy

tomlrt-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,78 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: "3.14"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78  # v7
+        with:
+          enable-cache: false
+
+      - name: Check tag matches pyproject version
+        if: startsWith(github.ref, 'refs/tags/v')
+        env:
+          REF_NAME: ${{ github.ref_name }}
+        run: |
+          TAG_VERSION="${REF_NAME#v}"
+          PROJECT_VERSION=$(python -c '
+            import tomllib
+            with open("pyproject.toml", "rb") as f:
+                print(tomllib.load(f)["project"]["version"])
+            ')
+          if [ "$TAG_VERSION" != "$PROJECT_VERSION" ]; then
+            echo "Tag $REF_NAME (version $TAG_VERSION) does not match pyproject version $PROJECT_VERSION" >&2
+            exit 1
+          fi
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/tomlrt
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          path: dist
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
+        with:
+          packages-dir: dist/

tomlrt-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+vendor/
+.coverage
+dist/
+.hypothesis/

tomlrt-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

tomlrt-0.1.0/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-04-20
+
+Initial release.
+
+[Unreleased]: https://github.com/dimbleby/tomlrt/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/dimbleby/tomlrt/releases/tag/v0.1.0

tomlrt-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tomlrt contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tomlrt-0.1.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: tomlrt
+Version: 0.1.0
+Summary: A format-preserving TOML parser and writer for Python.
+Project-URL: Repository, https://github.com/dimbleby/tomlrt
+Project-URL: Issues, https://github.com/dimbleby/tomlrt/issues
+Project-URL: Changelog, https://github.com/dimbleby/tomlrt/blob/main/CHANGELOG.md
+Author-email: David Hotham <david.hotham@blueyonder.co.uk>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: config,configuration,format-preserving,pyproject,round-trip,toml,toml-parser,toml-writer,tomlrt
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: typing-extensions>=4; python_version < '3.12'
+Description-Content-Type: text/markdown
+
+# tomlrt
+
+[![PyPI](https://img.shields.io/pypi/v/tomlrt.svg)](https://pypi.org/project/tomlrt/)
+[![Python versions](https://img.shields.io/pypi/pyversions/tomlrt.svg)](https://pypi.org/project/tomlrt/)
+[![License](https://img.shields.io/pypi/l/tomlrt.svg)](https://github.com/dimbleby/tomlrt/blob/main/LICENSE)
+[![CI](https://github.com/dimbleby/tomlrt/actions/workflows/ci.yml/badge.svg)](https://github.com/dimbleby/tomlrt/actions/workflows/ci.yml)
+
+A format-preserving TOML parser and writer for Python.
+
+## Usage
+
+```python
+import tomlrt
+
+# Files must be opened in binary mode.
+with open("pyproject.toml", "rb") as f:
+    doc = tomlrt.load(f)
+
+doc["project"]["version"] = "0.2.0"
+doc["project"]["dependencies"].append("requests>=2")
+
+print(tomlrt.dumps(doc))   # comments and layout are preserved
+```
+
+### Comment API
+
+```python
+doc = tomlrt.loads("""
+[server]
+host = "localhost"  # default
+port = 8080
+""")
+
+server = doc.table("server")
+server.comments["port"] = "override with $PORT"
+server.comments["host"] = None         # clear
+
+print(tomlrt.dumps(doc))
+# [server]
+# host = "localhost"
+# port = 8080 # override with $PORT
+```

tomlrt-0.1.0/README.md

@@ -0,0 +1,42 @@
+# tomlrt
+
+[![PyPI](https://img.shields.io/pypi/v/tomlrt.svg)](https://pypi.org/project/tomlrt/)
+[![Python versions](https://img.shields.io/pypi/pyversions/tomlrt.svg)](https://pypi.org/project/tomlrt/)
+[![License](https://img.shields.io/pypi/l/tomlrt.svg)](https://github.com/dimbleby/tomlrt/blob/main/LICENSE)
+[![CI](https://github.com/dimbleby/tomlrt/actions/workflows/ci.yml/badge.svg)](https://github.com/dimbleby/tomlrt/actions/workflows/ci.yml)
+
+A format-preserving TOML parser and writer for Python.
+
+## Usage
+
+```python
+import tomlrt
+
+# Files must be opened in binary mode.
+with open("pyproject.toml", "rb") as f:
+    doc = tomlrt.load(f)
+
+doc["project"]["version"] = "0.2.0"
+doc["project"]["dependencies"].append("requests>=2")
+
+print(tomlrt.dumps(doc))   # comments and layout are preserved
+```
+
+### Comment API
+
+```python
+doc = tomlrt.loads("""
+[server]
+host = "localhost"  # default
+port = 8080
+""")
+
+server = doc.table("server")
+server.comments["port"] = "override with $PORT"
+server.comments["host"] = None         # clear
+
+print(tomlrt.dumps(doc))
+# [server]
+# host = "localhost"
+# port = 8080 # override with $PORT
+```

tomlrt-0.1.0/pyproject.toml

@@ -0,0 +1,111 @@
+[project]
+name = "tomlrt"
+version = "0.1.0"
+description = "A format-preserving TOML parser and writer for Python."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "David Hotham", email = "david.hotham@blueyonder.co.uk" }]
+keywords = [
+  "toml",
+  "toml-parser",
+  "toml-writer",
+  "tomlrt",
+  "format-preserving",
+  "round-trip",
+  "config",
+  "configuration",
+  "pyproject",
+]
+dependencies = ["typing_extensions>=4; python_version < '3.12'"]
+classifiers = [
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Repository = "https://github.com/dimbleby/tomlrt"
+Issues = "https://github.com/dimbleby/tomlrt/issues"
+Changelog = "https://github.com/dimbleby/tomlrt/blob/main/CHANGELOG.md"
+
+[dependency-groups]
+dev = [
+  "pytest>=9",
+  "pytest-cov>=5",
+  "hypothesis>=6",
+  "mypy>=1.11",
+  "tomli>=2; python_version < '3.11'",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.pytest]
+addopts = ["-ra"]
+testpaths = ["tests"]
+strict = true
+
+[tool.coverage.run]
+source = ["src/tomlrt"]
+branch = true
+
+[tool.coverage.report]
+skip_covered = false
+exclude_also = [
+  "if TYPE_CHECKING:",
+  "raise NotImplementedError",
+  "@overload",
+  "pragma: no cover",
+]
+
+[tool.mypy]
+files = ["src", "tests"]
+strict = true
+warn_unreachable = true
+disallow_any_unimported = true
+enable_error_code = [
+  "deprecated",
+  "explicit-override",
+  "ignore-without-code",
+  "possibly-undefined",
+  "redundant-expr",
+  "redundant-self",
+  "truthy-bool",
+  "truthy-iterable",
+  "unused-awaitable",
+]
+
+[tool.ruff]
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+  "C90",               # mccabe
+  "COM",               # flake8-commas
+  "CPY",               # flake8-copyright
+  "D",                 # pydocstyle
+  "DOC",               # pydoclint
+  "ERA",               # eradicate
+  "PD",                # pandas-vet
+  "PLR",               # pylint-refactor
+  "T20",               # flake8-print
+  "ANN401",            # any-type
+  "E203",              # whitespace before ':'
+  "S101",              # assert-used
+]
+extend-safe-fixes = ["TC"]
+unfixable = ["F841"]
+
+[tool.ruff.lint.flake8-tidy-imports]
+ban-relative-imports = "all"
+
+[tool.ruff.lint.flake8-type-checking]
+strict = true
+
+[tool.ruff.lint.isort]
+required-imports = ["from __future__ import annotations"]

tomlrt-0.1.0/renovate.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": [
+    "config:recommended"
+  ],
+  "lockFileMaintenance": {
+    "enabled": true
+  }
+}

tomlrt-0.1.0/src/tomlrt/__init__.py

@@ -0,0 +1,23 @@
+"""tomlrt: a format-preserving TOML parser and writer."""
+
+from __future__ import annotations
+
+from tomlrt._document import AoT, Array, Document, Table
+from tomlrt._errors import TOMLError, TOMLParseError
+from tomlrt._public import dump, dumps, load, loads, parse
+
+__all__ = [
+    "AoT",
+    "Array",
+    "Document",
+    "TOMLError",
+    "TOMLParseError",
+    "Table",
+    "dump",
+    "dumps",
+    "load",
+    "loads",
+    "parse",
+]
+
+__version__ = "0.1.0"