tomlrange 0.1.0__tar.gz

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

@@ -0,0 +1,121 @@
+name: Publish
+run-name: Publish ${{ github.event_name == 'workflow_dispatch' && inputs.target || (github.event.release.prerelease && 'testpypi' || 'testpypi+pypi') }} ${{ inputs.release_tag || github.ref_name }}
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Publish target"
+        required: true
+        type: choice
+        options:
+          - testpypi
+          - pypi
+      release_tag:
+        description: "Release tag to attach dist files (empty = skip attach)"
+        required: false
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          enable-cache: false
+      - run: uv build
+      - name: Tag matches pyproject version
+        if: github.event_name == 'release'
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          ver="$(uv run python -c 'import tomllib, pathlib; print(tomllib.loads(pathlib.Path("pyproject.toml").read_text())["project"]["version"])')"
+          test "$tag" = "$ver"
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: dist
+          path: dist/
+
+  pypi:
+    needs: build
+    if: >-
+      (github.event_name == 'release' && github.event.release.prerelease == false)
+      || (github.event_name == 'workflow_dispatch' && inputs.target == 'pypi')
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/tomlrange
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          enable-cache: false
+      - run: uv publish --index pypi --trusted-publishing always
+
+  testpypi:
+    needs: build
+    if: >-
+      github.event_name == 'release'
+      || (github.event_name == 'workflow_dispatch' && inputs.target == 'testpypi')
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/tomlrange
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          enable-cache: false
+      - run: uv publish --index testpypi --trusted-publishing always
+
+  attach:
+    needs: build
+    if: >-
+      github.event_name == 'release'
+      || (github.event_name == 'workflow_dispatch' && inputs.release_tag != '')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist
+      - name: Attach missing dist files
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_REPO: ${{ github.repository }}
+          RELEASE_TAG: ${{ github.event_name == 'release' && github.ref_name || inputs.release_tag }}
+        run: |
+          existing="$(gh release view "$RELEASE_TAG" --json assets --jq '.assets[].name')"
+          for f in dist/*; do
+            name="${f##*/}"
+            if printf '%s\n' "$existing" | grep -Fxq "$name"; then
+              echo "skip $name (already on release)"
+              continue
+            fi
+            err="$(gh release upload "$RELEASE_TAG" "$f" 2>&1)" || { printf '%s\n' "$err"; echo "$err" | grep -qi 'already exists'; }
+          done

tomlrange-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+.venv/
+venv/

tomlrange-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,20 @@
+# Hook rev should stay in step with the ruff pin in [dependency-groups] dev.
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-added-large-files
+      - id: debug-statements
+      - id: mixed-line-ending
+        args: [--fix=lf]
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.8
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format

tomlrange-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joseph Chiocchi
+
+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.

tomlrange-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.5
+Name: tomlrange
+Version: 0.1.0
+Summary: Parse and validate { from, to } tables from decoded TOML.
+Project-URL: Homepage, https://github.com/yyolk/tomlrange
+Project-URL: Repository, https://github.com/yyolk/tomlrange
+Project-URL: Issues, https://github.com/yyolk/tomlrange/issues
+Author-email: Joseph Chiocchi <joe@yolk.cc>
+License: MIT License
+        
+        Copyright (c) 2026 Joseph Chiocchi
+        
+        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.
+License-File: LICENSE
+Keywords: config,range,toml,validation
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# tomlrange
+
+Parse and validate `{ from = …, to = … }` tables. Not a TOML parser —
+feed it the dicts `tomllib` already produced.
+
+The four spellings below are alternatives, not one document — a
+`[table]` header owns every following key until the next header.
+After `tomllib`, they collapse to two Python values. `Bound` accepts
+a single table. `Bounds` accepts a table or a list of tables.
+
+```toml
+# one table
+months = { from = 1, to = 12 }
+
+[months]
+from = 1
+to = 12
+
+# many tables
+windows = [
+    { from = 1, to = 4 },
+    { from = 6, to = 10 },
+]
+
+[[windows]]
+from = 1
+to = 4
+
+[[windows]]
+from = 6
+to = 10
+```
+
+```python
+import tomllib
+from tomlrange import Domain
+
+Month = Domain(int, lo=1, hi=12, name="month")
+
+data = tomllib.loads(config)
+year = Month.bound(data["months"])       # 1..12
+windows = Month.bounds(data["windows"])  # 1..4 and 6..10
+
+assert list(year) == list(range(1, 13))
+assert 5 not in windows
+```
+
+No runtime dependencies. Endpoints stay the type `tomllib` gave you.
+
+## Domain as schema
+
+A `Domain` is the constraint object. `Bound` / `Bounds` are the values.
+
+```python
+from tomlrange import Domain
+
+Hour = Domain(int, lo=0, hi=23, name="hour")
+Hour.bound({"from": 7, "to": 16})
+Hour.full()  # requires lo and hi
+```
+
+Or name the domain by subclassing `Spec` — the class body is the schema:
+
+```python
+from tomlrange import Spec
+
+class Month(Spec):
+    typ = int
+    lo = 1
+    hi = 12
+
+Month.parse({"from": 1, "to": 4})
+Month.parse_many([{ "from": 1, "to": 4 }, { "from": 6, "to": 10 }])
+```
+
+## Validation
+
+On one table:
+
+- value is a mapping
+- keys are exactly `from` and `to` (override with `Domain(..., keys=("start", "end"))`)
+- each endpoint is `type(raw) is domain.typ` (so `1.0` and `True` are not `int`)
+- endpoints sit inside `lo` / `hi` when those are set
+- `from <= to` (a singleton is `{ from = 3, to = 3 }`)
+
+On a list, `overlap=` is `"reject"` (default), `"allow"`, or `"merge"`.
+Reject treats a shared endpoint as overlap (`1–4` and `4–6` fail).
+Adjacent integers (`1–4` then `5–8`) are fine; `merge()` will coalesce them.
+
+Errors carry a path:
+
+```
+months_ranges[1].to: 13 is above month 12
+```
+
+## What this is not
+
+- Not a file loader. Call `tomllib` yourself.
+- Not string ranges (`"1-12"`, `"Jan–Apr"`).
+- Not a two-element array (`[1, 12]`). After TOML decode that is a list, not a table.
+- Not wrap-around (`from = 11, to = 2`). Write two spans.
+- Not `step`. A range table is a closed interval.
+
+## Install
+
+```
+pip install tomlrange
+```
+
+Python 3.12+.

tomlrange-0.1.0/README.md

@@ -0,0 +1,110 @@
+# tomlrange
+
+Parse and validate `{ from = …, to = … }` tables. Not a TOML parser —
+feed it the dicts `tomllib` already produced.
+
+The four spellings below are alternatives, not one document — a
+`[table]` header owns every following key until the next header.
+After `tomllib`, they collapse to two Python values. `Bound` accepts
+a single table. `Bounds` accepts a table or a list of tables.
+
+```toml
+# one table
+months = { from = 1, to = 12 }
+
+[months]
+from = 1
+to = 12
+
+# many tables
+windows = [
+    { from = 1, to = 4 },
+    { from = 6, to = 10 },
+]
+
+[[windows]]
+from = 1
+to = 4
+
+[[windows]]
+from = 6
+to = 10
+```
+
+```python
+import tomllib
+from tomlrange import Domain
+
+Month = Domain(int, lo=1, hi=12, name="month")
+
+data = tomllib.loads(config)
+year = Month.bound(data["months"])       # 1..12
+windows = Month.bounds(data["windows"])  # 1..4 and 6..10
+
+assert list(year) == list(range(1, 13))
+assert 5 not in windows
+```
+
+No runtime dependencies. Endpoints stay the type `tomllib` gave you.
+
+## Domain as schema
+
+A `Domain` is the constraint object. `Bound` / `Bounds` are the values.
+
+```python
+from tomlrange import Domain
+
+Hour = Domain(int, lo=0, hi=23, name="hour")
+Hour.bound({"from": 7, "to": 16})
+Hour.full()  # requires lo and hi
+```
+
+Or name the domain by subclassing `Spec` — the class body is the schema:
+
+```python
+from tomlrange import Spec
+
+class Month(Spec):
+    typ = int
+    lo = 1
+    hi = 12
+
+Month.parse({"from": 1, "to": 4})
+Month.parse_many([{ "from": 1, "to": 4 }, { "from": 6, "to": 10 }])
+```
+
+## Validation
+
+On one table:
+
+- value is a mapping
+- keys are exactly `from` and `to` (override with `Domain(..., keys=("start", "end"))`)
+- each endpoint is `type(raw) is domain.typ` (so `1.0` and `True` are not `int`)
+- endpoints sit inside `lo` / `hi` when those are set
+- `from <= to` (a singleton is `{ from = 3, to = 3 }`)
+
+On a list, `overlap=` is `"reject"` (default), `"allow"`, or `"merge"`.
+Reject treats a shared endpoint as overlap (`1–4` and `4–6` fail).
+Adjacent integers (`1–4` then `5–8`) are fine; `merge()` will coalesce them.
+
+Errors carry a path:
+
+```
+months_ranges[1].to: 13 is above month 12
+```
+
+## What this is not
+
+- Not a file loader. Call `tomllib` yourself.
+- Not string ranges (`"1-12"`, `"Jan–Apr"`).
+- Not a two-element array (`[1, 12]`). After TOML decode that is a list, not a table.
+- Not wrap-around (`from = 11, to = 2`). Write two spans.
+- Not `step`. A range table is a closed interval.
+
+## Install
+
+```
+pip install tomlrange
+```
+
+Python 3.12+.

tomlrange-0.1.0/pyproject.toml

@@ -0,0 +1,78 @@
+[project]
+name = "tomlrange"
+version = "0.1.0"
+description = "Parse and validate { from, to } tables from decoded TOML."
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.12"
+authors = [
+  { name = "Joseph Chiocchi", email = "joe@yolk.cc" },
+]
+keywords = ["toml", "range", "validation", "config"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/yyolk/tomlrange"
+Repository = "https://github.com/yyolk/tomlrange"
+Issues = "https://github.com/yyolk/tomlrange/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tomlrange"]
+
+[tool.uv]
+package = true
+
+[[tool.uv.index]]
+name = "pypi"
+url = "https://pypi.org/simple/"
+publish-url = "https://upload.pypi.org/legacy/"
+
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.16.8",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+target-version = "py312"
+src = ["src"]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "W",
+    "F",
+    "I",
+    "UP",
+    "B",
+    "C4",
+    "PT",
+    "RUF",
+    "SIM",
+    "TC",
+]
+ignore = ["E501"]

tomlrange-0.1.0/src/tomlrange/__init__.py

@@ -0,0 +1,14 @@
+"""Parse and validate `{ from = …, to = … }` tables from decoded TOML."""
+
+from tomlrange.bound import Bound, Bounds
+from tomlrange.domain import Domain, Spec
+from tomlrange.error import TomlRangeError
+
+__all__ = [
+    "Bound",
+    "Bounds",
+    "Domain",
+    "Spec",
+    "TomlRangeError",
+]
+__version__ = "0.1.0"

tomlrange-0.1.0/src/tomlrange/bound.py

@@ -0,0 +1,187 @@
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping
+from dataclasses import dataclass
+from typing import Any, Generic, TypeVar
+
+from tomlrange.domain import Domain
+from tomlrange.error import TomlRangeError
+from tomlrange.paths import Overlap, index_path, join_path
+
+T = TypeVar("T")
+
+
+def _as_table(raw: Any, *, path: str) -> Mapping[str, Any]:
+    if isinstance(raw, Mapping):
+        return raw
+    raise TomlRangeError(path, "expected a table { from = …, to = … }", raw)
+
+
+@dataclass(frozen=True, slots=True)
+class Bound(Generic[T]):
+    """One inclusive interval parsed from a `{ from, to }` table."""
+
+    start: T
+    stop: T
+    domain: Domain[T]
+
+    @classmethod
+    def parse(cls, raw: Any, domain: Domain[T], *, path: str = ".") -> Bound[T]:
+        table = _as_table(raw, path=path)
+        start_key, stop_key = domain.keys
+        extra = set(table) - {start_key, stop_key}
+        if extra:
+            raise TomlRangeError(
+                path,
+                f"unknown keys {sorted(extra)}",
+                raw,
+            )
+        if start_key not in table or stop_key not in table:
+            raise TomlRangeError(
+                path,
+                f"table must have keys {start_key!r} and {stop_key!r}",
+                raw,
+            )
+        start = domain.convert(table[start_key], path=join_path(path, start_key))
+        stop = domain.convert(table[stop_key], path=join_path(path, stop_key))
+        if start > stop:  # type: ignore[operator]
+            raise TomlRangeError(
+                path,
+                f"{start_key} ({start}) is after {stop_key} ({stop})",
+                raw,
+            )
+        return cls(start, stop, domain)
+
+    @property
+    def width(self) -> int:
+        if type(self.start) is not int or type(self.stop) is not int:
+            raise TypeError(f"{self.domain.name} width is only defined for int")
+        return self.stop - self.start + 1
+
+    def as_range(self) -> range:
+        if type(self.start) is not int or type(self.stop) is not int:
+            raise TypeError(f"{self.domain.name} as_range() is only defined for int")
+        return range(self.start, self.stop + 1)
+
+    def as_tuple(self) -> tuple[T, T]:
+        return (self.start, self.stop)
+
+    def as_table(self) -> dict[str, T]:
+        start_key, stop_key = self.domain.keys
+        return {start_key: self.start, stop_key: self.stop}
+
+    def __contains__(self, item: object) -> bool:
+        if type(item) is not self.domain.typ:
+            return False
+        return self.start <= item <= self.stop  # type: ignore[operator]
+
+    def __iter__(self) -> Iterator[T]:
+        yield from self.as_range()  # type: ignore[misc]
+
+    def __len__(self) -> int:
+        return self.width
+
+    def overlaps(self, other: Bound[T]) -> bool:
+        return self.start <= other.stop and other.start <= self.stop  # type: ignore[operator]
+
+    def adjacent_to(self, other: Bound[T]) -> bool:
+        if self.domain.typ is not int:
+            return False
+        return self.stop + 1 == other.start or other.stop + 1 == self.start  # type: ignore[operator, return-value]
+
+    def __repr__(self) -> str:
+        return f"Bound({self.start!r}, {self.stop!r}, {self.domain.name})"
+
+
+@dataclass(frozen=True, slots=True)
+class Bounds(Generic[T]):
+    """One table or an array of `{ from, to }` tables."""
+
+    spans: tuple[Bound[T], ...]
+    domain: Domain[T]
+
+    @classmethod
+    def parse(
+        cls,
+        raw: Any,
+        domain: Domain[T],
+        *,
+        path: str = ".",
+        overlap: Overlap = "reject",
+    ) -> Bounds[T]:
+        if isinstance(raw, Mapping):
+            return cls((Bound.parse(raw, domain, path=path),), domain)
+        if isinstance(raw, list):
+            spans = tuple(
+                Bound.parse(item, domain, path=index_path(path, i))
+                for i, item in enumerate(raw)
+            )
+            return cls._apply_overlap(spans, domain, path=path, overlap=overlap)
+        raise TomlRangeError(path, "expected a table or an array of tables", raw)
+
+    @classmethod
+    def _apply_overlap(
+        cls,
+        spans: tuple[Bound[T], ...],
+        domain: Domain[T],
+        *,
+        path: str,
+        overlap: Overlap,
+    ) -> Bounds[T]:
+        if overlap == "allow":
+            return cls(spans, domain)
+        if overlap == "merge":
+            return cls(_coalesce(spans, domain), domain)
+        if overlap != "reject":
+            raise ValueError(f"unknown overlap policy {overlap!r}")
+        for i, left in enumerate(spans):
+            for j, right in enumerate(spans):
+                if j <= i:
+                    continue
+                if left.overlaps(right):
+                    raise TomlRangeError(
+                        path,
+                        f"{index_path(path, i)} overlaps {index_path(path, j)}",
+                        (left.as_tuple(), right.as_tuple()),
+                    )
+        return cls(spans, domain)
+
+    def merge(self) -> Bounds[T]:
+        return Bounds(_coalesce(self.spans, self.domain), self.domain)
+
+    def covers(self, item: object) -> bool:
+        return any(item in span for span in self.spans)
+
+    def __contains__(self, item: object) -> bool:
+        return self.covers(item)
+
+    def __iter__(self) -> Iterator[T]:
+        seen: set[T] = set()
+        for span in self.spans:
+            for item in span:
+                if item in seen:
+                    continue
+                seen.add(item)
+                yield item
+
+    def __len__(self) -> int:
+        return sum(1 for _ in self)
+
+    def __repr__(self) -> str:
+        inner = ", ".join(f"{s.start!r}..{s.stop!r}" for s in self.spans)
+        return f"Bounds({inner}, {self.domain.name})"
+
+
+def _coalesce(spans: tuple[Bound[T], ...], domain: Domain[T]) -> tuple[Bound[T], ...]:
+    if not spans:
+        return ()
+    ordered = sorted(spans, key=lambda s: (s.start, s.stop))
+    out = [ordered[0]]
+    for cur in ordered[1:]:
+        prev = out[-1]
+        if prev.overlaps(cur) or prev.adjacent_to(cur):
+            stop = prev.stop if prev.stop >= cur.stop else cur.stop  # type: ignore[operator]
+            out[-1] = Bound(prev.start, stop, domain)
+        else:
+            out.append(cur)
+    return tuple(out)

tomlrange-0.1.0/src/tomlrange/domain.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Generic, TypeVar
+
+from tomlrange.error import TomlRangeError
+from tomlrange.paths import Overlap
+
+if TYPE_CHECKING:
+    from tomlrange.bound import Bound, Bounds
+
+T = TypeVar("T")
+
+_FROM = "from"
+_TO = "to"
+
+
+@dataclass(frozen=True, slots=True)
+class Domain(Generic[T]):
+    """Closed interval domain for a `{ from, to }` table.
+
+    `typ` is matched with `type(raw) is typ` — `bool` is not an `int`,
+    and a TOML float is not an `int`.
+    """
+
+    typ: type[T]
+    lo: T | None = None
+    hi: T | None = None
+    name: str = "value"
+    keys: tuple[str, str] = (_FROM, _TO)
+
+    def __post_init__(self) -> None:
+        if len(self.keys) != 2 or self.keys[0] == self.keys[1]:
+            raise ValueError("keys must be two distinct TOML key names")
+        if self.lo is not None and type(self.lo) is not self.typ:
+            raise TypeError(f"lo must be {self.typ.__name__}")
+        if self.hi is not None and type(self.hi) is not self.typ:
+            raise TypeError(f"hi must be {self.typ.__name__}")
+        if self.lo is not None and self.hi is not None and self.lo > self.hi:  # type: ignore[operator]
+            raise ValueError("domain lo is after hi")
+
+    @property
+    def start_key(self) -> str:
+        return self.keys[0]
+
+    @property
+    def stop_key(self) -> str:
+        return self.keys[1]
+
+    def convert(self, raw: Any, *, path: str) -> T:
+        if type(raw) is not self.typ:
+            raise TomlRangeError(
+                path,
+                f"expected {self.typ.__name__}, got {type(raw).__name__}",
+                raw,
+            )
+        if self.lo is not None and raw < self.lo:  # type: ignore[operator]
+            raise TomlRangeError(
+                path,
+                f"{raw!r} is below {self.name} {self.lo}",
+                raw,
+            )
+        if self.hi is not None and raw > self.hi:  # type: ignore[operator]
+            raise TomlRangeError(
+                path,
+                f"{raw!r} is above {self.name} {self.hi}",
+                raw,
+            )
+        return raw
+
+    def bound(self, raw: Any, *, path: str = ".") -> Bound[T]:
+        from tomlrange.bound import Bound
+
+        return Bound.parse(raw, self, path=path)
+
+    def bounds(
+        self,
+        raw: Any,
+        *,
+        path: str = ".",
+        overlap: Overlap = "reject",
+    ) -> Bounds[T]:
+        from tomlrange.bound import Bounds
+
+        return Bounds.parse(raw, self, path=path, overlap=overlap)
+
+    def full(self) -> Bound[T]:
+        from tomlrange.bound import Bound
+
+        if self.lo is None or self.hi is None:
+            raise TomlRangeError(".", f"{self.name} domain has no closed lo/hi")
+        return Bound(self.lo, self.hi, self)
+
+
+class Spec:
+    """Subclass to name a domain. The class body is the schema.
+
+    ```
+    class Month(Spec):
+        typ = int
+        lo = 1
+        hi = 12
+
+    Month.parse({"from": 1, "to": 4})
+    Month.parse_many([{ "from": 1, "to": 4 }, { "from": 6, "to": 10 }])
+    ```
+    """
+
+    typ: type = int
+    lo: Any = None
+    hi: Any = None
+    name: str | None = None
+    keys: tuple[str, str] = (_FROM, _TO)
+    overlap: Overlap = "reject"
+    domain: Domain[Any]
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        name = cls.name
+        if name is None:
+            name = cls.__name__
+            for suffix in ("Bounds", "Range", "Spec"):
+                if name.endswith(suffix) and name != suffix:
+                    name = name[: -len(suffix)]
+                    break
+            name = name.lower()
+        cls.domain = Domain(
+            typ=cls.typ,
+            lo=cls.lo,
+            hi=cls.hi,
+            name=name,
+            keys=cls.keys,
+        )
+
+    @classmethod
+    def parse(cls, raw: Any, *, path: str = ".") -> Bound[Any]:
+        from tomlrange.bound import Bound
+
+        return Bound.parse(raw, cls.domain, path=path)
+
+    @classmethod
+    def parse_many(
+        cls,
+        raw: Any,
+        *,
+        path: str = ".",
+        overlap: Overlap | None = None,
+    ) -> Bounds[Any]:
+        from tomlrange.bound import Bounds
+
+        return Bounds.parse(
+            raw,
+            cls.domain,
+            path=path,
+            overlap=cls.overlap if overlap is None else overlap,
+        )
+
+    @classmethod
+    def full(cls) -> Bound[Any]:
+        return cls.domain.full()

tomlrange-0.1.0/src/tomlrange/error.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class TomlRangeError(ValueError):
+    """A `{ from, to }` table failed to parse or validate."""
+
+    def __init__(self, path: str, message: str, value: Any = None) -> None:
+        self.path = path
+        self.message = message
+        self.value = value
+        loc = path if path not in {"", "."} else "range"
+        super().__init__(f"{loc}: {message}")

tomlrange-0.1.0/src/tomlrange/paths.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from typing import Literal
+
+Overlap = Literal["reject", "allow", "merge"]
+
+
+def join_path(parent: str, child: str) -> str:
+    if parent in {"", "."}:
+        return child
+    return f"{parent}.{child}"
+
+
+def index_path(parent: str, i: int) -> str:
+    if parent in {"", "."}:
+        return f"[{i}]"
+    return f"{parent}[{i}]"

tomlrange-0.1.0/src/tomlrange/py.typed

@@ -0,0 +1 @@
+

tomlrange-0.1.0/tests/test_tomlrange.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+import tomllib
+
+import pytest
+
+from tomlrange import Bound, Domain, Spec, TomlRangeError
+
+MONTH = Domain(int, lo=1, hi=12, name="month")
+
+INLINE = "months = { from = 1, to = 12 }\n"
+STANDARD = """
+[months_copy]
+from = 1
+to = 12
+"""
+ARRAY_INLINE = """
+months_ranges = [
+    { from = 1, to = 4 },
+    { from = 6, to = 10 }
+]
+"""
+ARRAY_TABLES = """
+[[months_ranges_copy]]
+from = 1
+to = 4
+
+[[months_ranges_copy]]
+from = 6
+to = 10
+"""
+
+
+def test_inline_table_and_standard_table_are_the_same() -> None:
+    a = MONTH.bound(tomllib.loads(INLINE)["months"])
+    b = MONTH.bound(tomllib.loads(STANDARD)["months_copy"])
+    assert a == b
+    assert a.as_tuple() == (1, 12)
+    assert a.as_table() == {"from": 1, "to": 12}
+    assert list(a) == list(range(1, 13))
+    assert 12 in a
+    assert 0 not in a
+
+
+def test_array_of_inline_tables_and_array_of_tables_are_the_same() -> None:
+    a = MONTH.bounds(tomllib.loads(ARRAY_INLINE)["months_ranges"])
+    b = MONTH.bounds(tomllib.loads(ARRAY_TABLES)["months_ranges_copy"])
+    assert a == b
+    assert list(a) == [1, 2, 3, 4, 6, 7, 8, 9, 10]
+    assert 4 in a
+    assert 5 not in a
+
+
+def test_bounds_accepts_a_single_table() -> None:
+    one = MONTH.bounds({"from": 2, "to": 3})
+    assert one.spans == (Bound.parse({"from": 2, "to": 3}, MONTH),)
+
+
+def test_singleton_and_full() -> None:
+    one = MONTH.bound({"from": 7, "to": 7})
+    assert list(one) == [7]
+    assert MONTH.full().as_tuple() == (1, 12)
+
+
+def test_rejects_inverted_and_out_of_domain() -> None:
+    with pytest.raises(TomlRangeError, match="from \\(5\\) is after to \\(1\\)"):
+        MONTH.bound({"from": 5, "to": 1})
+    with pytest.raises(TomlRangeError, match="above month 12"):
+        MONTH.bound({"from": 1, "to": 13})
+    with pytest.raises(TomlRangeError, match="below month 1"):
+        MONTH.bound({"from": 0, "to": 3})
+
+
+def test_rejects_wrong_shape_and_unknown_keys() -> None:
+    with pytest.raises(TomlRangeError, match="expected a table"):
+        MONTH.bound([1, 12])
+    with pytest.raises(TomlRangeError, match="unknown keys"):
+        MONTH.bound({"from": 1, "to": 2, "step": 1})
+    with pytest.raises(TomlRangeError, match="must have keys"):
+        MONTH.bound({"from": 1})
+    with pytest.raises(TomlRangeError, match="expected int, got float"):
+        MONTH.bound({"from": 1.0, "to": 2})
+    with pytest.raises(TomlRangeError, match="expected int, got bool"):
+        MONTH.bound({"from": True, "to": 2})
+
+
+def test_overlap_policies() -> None:
+    raw = [{"from": 1, "to": 4}, {"from": 4, "to": 6}]
+    with pytest.raises(TomlRangeError, match="overlaps"):
+        MONTH.bounds(raw)
+    allowed = MONTH.bounds(raw, overlap="allow")
+    assert list(allowed) == [1, 2, 3, 4, 5, 6]
+    merged = MONTH.bounds(raw, overlap="merge")
+    assert merged.spans == (Bound(1, 6, MONTH),)
+
+    adjacent = [{"from": 1, "to": 4}, {"from": 5, "to": 6}]
+    kept = MONTH.bounds(adjacent)
+    assert len(kept.spans) == 2
+    assert kept.merge().spans == (Bound(1, 6, MONTH),)
+
+
+def test_spec_metaprogramming() -> None:
+    class Month(Spec):
+        typ = int
+        lo = 1
+        hi = 12
+
+    bound = Month.parse({"from": 3, "to": 5})
+    assert bound.domain.name == "month"
+    assert list(Month.parse_many([{"from": 1, "to": 2}, {"from": 11, "to": 12}])) == [
+        1,
+        2,
+        11,
+        12,
+    ]
+    assert Month.full().width == 12
+
+
+def test_custom_keys() -> None:
+    hours = Domain(int, lo=0, hi=23, name="hour", keys=("start", "end"))
+    bound = hours.bound({"start": 7, "end": 16})
+    assert bound.as_table() == {"start": 7, "end": 16}
+    with pytest.raises(TomlRangeError, match="unknown keys"):
+        hours.bound({"from": 7, "to": 16})
+    with pytest.raises(TomlRangeError, match="must have keys"):
+        hours.bound({"start": 7})
+
+
+def test_error_paths() -> None:
+    with pytest.raises(TomlRangeError, match=r"months_ranges\[1\].to:") as exc:
+        MONTH.bounds(
+            [{"from": 1, "to": 2}, {"from": 3, "to": 13}],
+            path="months_ranges",
+        )
+    assert exc.value.path == "months_ranges[1].to"