tomlclass 0.1.0__py3-none-any.whl

tomlclass/__init__.py

@@ -0,0 +1,109 @@
+"""
+tomlclass — annotation-driven TOML configuration with comment preservation.
+
+Declare configuration as annotated classes; tomlclass renders commented TOML
+templates, validates and fills values, and updates existing TOML files in
+place while keeping user comments, ordering and formatting intact.
+
+Public API:
+
+- :func:`parse` / :func:`loads`  — parse TOML text into a :class:`Document`
+- :func:`load`                   — parse a TOML file
+- :func:`dumps`                  — render a :class:`Document` back to text
+- :class:`Document`              — lossless CST document with mapping access
+                                  and atomic :meth:`Document.save`
+- :class:`Config` / :class:`Field` — the annotation layer
+- :class:`TOMLError` hierarchy   — TOMLParseError / TOMLTypeError / ConfigError
+"""
+
+from pathlib import Path
+from typing import Any
+
+from .document import Document
+from .errors import (
+    ConfigError,
+    FieldError,
+    TOMLError,
+    TOMLParseError,
+    TOMLTypeError,
+    ValidationError,
+)
+from .nodes import Array, ArrayOfTables, InlineTable, Table
+from .parser import parse_source
+from .schema import Config, Field
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Array",
+    "ArrayOfTables",
+    "Config",
+    "ConfigError",
+    "Document",
+    "Field",
+    "FieldError",
+    "InlineTable",
+    "TOMLError",
+    "TOMLParseError",
+    "TOMLTypeError",
+    "Table",
+    "ValidationError",
+    "__version__",
+    "dumps",
+    "load",
+    "loads",
+    "parse",
+]
+
+
+def parse(source: str) -> Document:
+    """
+    Parse TOML text into a :class:`Document`.
+
+    :param source: TOML text (must be a valid TOML 1.0 document)
+    :raises TOMLParseError: on any syntax or semantic error, with ``line`` /
+        ``col`` / ``offset`` / ``segment`` attached
+    """
+    root, parts = parse_source(source)
+    return Document(source, root, parts)
+
+
+def loads(source: str) -> dict[str, Any]:
+    """
+    Parse TOML text into a plain dict — stdlib :mod:`tomllib` compatible.
+
+    For lossless editing (comments, ordering, formatting) use :func:`parse`,
+    which returns a :class:`Document`.
+
+    :param source: TOML text
+    :raises TOMLParseError: on any syntax or semantic error
+    """
+    return parse(source).to_dict()
+
+
+def load(path: Any) -> Any:
+    """
+    Parse TOML — dual-mode entry point.
+
+    - *path* (``str`` / ``os.PathLike``) → :class:`Document` — lossless,
+      editable, atomic :meth:`Document.save`
+    - binary file object (``open(path, "rb")``) → plain nested ``dict`` —
+      stdlib :mod:`tomllib` compatible
+
+    :raises TOMLParseError: on any syntax or semantic error
+    """
+    if hasattr(path, "read"):
+        data = path.read()
+        text = data.decode("utf-8") if isinstance(data, bytes) else data
+        return parse(text).to_dict()
+    return parse(Path(path).read_text(encoding="utf-8"))
+
+
+def dumps(doc: Document) -> str:
+    """
+    Render a :class:`Document` back to text.
+
+    Unchanged documents round-trip byte-exactly; edited parts re-render with
+    canonical formatting while everything else stays untouched.
+    """
+    return doc.dumps()

tomlclass/document.py

@@ -0,0 +1,195 @@
+"""
+The parsed document object.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import tempfile
+from collections.abc import Iterator
+from pathlib import Path
+from typing import Any
+
+from .nodes import ArrayOfTables, Table
+from .render import render_document
+
+__all__ = ["Document", "atomic_write_text"]
+
+
+def atomic_write_text(path: str | os.PathLike[str], text: str) -> None:
+    """
+    Atomically write *text* to *path* (same-dir tempfile + ``os.replace``).
+    """
+    target = Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=target.parent, prefix=target.name + ".", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8", newline="") as f:
+            f.write(text)
+        Path(tmp).replace(target)
+    except BaseException:
+        with contextlib.suppress(OSError):
+            Path(tmp).unlink()
+        raise
+
+
+class Document:
+    """
+    A parsed TOML document: lossless CST + mapping access + atomic save.
+    """
+
+    def __init__(self, source: str, root: Table, parts: list[tuple[int, int, str, Any]]) -> None:
+        self._source = source
+        self.root = root
+        self._parts = parts
+
+    # -- mapping passthrough --------------------------------------------- #
+
+    def __getitem__(self, key: str) -> Any:
+        return self.root[key]
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        self.root[key] = value
+
+    def __delitem__(self, key: str) -> None:
+        del self.root[key]
+
+    def __contains__(self, key: object) -> bool:
+        return key in self.root
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self.root)
+
+    def __len__(self) -> int:
+        return len(self.root)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self.root.get(key, default)
+
+    # -- rendering --------------------------------------------------------- #
+
+    def dumps(self) -> str:
+        """
+        Render the document. Unchanged documents round-trip byte-exactly.
+        """
+        return render_document(self._source, self._parts, self.root)
+
+    def save(self, path: str | os.PathLike[str]) -> None:
+        """
+        Render and atomically write to *path* (tempfile + ``os.replace``).
+        """
+        atomic_write_text(path, self.dumps())
+
+    # -- navigation / conversion ------------------------------------------ #
+
+    def find(self, dotted_path: str) -> Any:
+        """
+        Return the value at *dotted_path* (``"a.b.c"``), or ``None``.
+        """
+        node: Any = self.root
+        for part in dotted_path.split("."):
+            if isinstance(node, Table) and part in node:
+                node = node[part]
+            else:
+                return None
+        return node
+
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Convert to plain nested dicts (datetimes stay as-is).
+        """
+        return _to_plain(self.root)
+
+    # -- comment API -------------------------------------------------------- #
+
+    def comment(self, dotted_path: str) -> str | None:
+        """
+        Return the comment trailing *dotted_path* (without ``#``), or None.
+
+        Comments belong to the key they trail; table-level comments live on
+        the header line and are addressed by the table's path.
+        """
+        parts = dotted_path.split(".")
+        block = self._block_for(parts[:-1])
+        if block is None:
+            return None
+        located = self._block_for(parts)
+        if located is None:
+            return None
+        block, phys = located
+        if phys in block.comments:  # set_comment override wins
+            return block.comments[phys]
+        span = block.entry_spans.get(phys)
+        if span is None:
+            return None
+        _vs, _ve, cs = span
+        line_end = self._line_end(cs)
+        text = self._source[cs:line_end].strip()
+        if not text.startswith("#"):
+            return None
+        return text[1:].lstrip() or None
+
+    def set_comment(self, dotted_path: str, comment: str | None) -> None:
+        """
+        Replace (or, with ``None``, remove) the comment trailing *dotted_path*.
+        """
+        parts = dotted_path.split(".")
+        located = self._block_for(parts)
+        if located is None:
+            raise KeyError(dotted_path)
+        block, phys = located
+        if phys not in block.entry_spans:
+            raise KeyError(dotted_path)
+        block.comments[phys] = comment
+
+    def _block_for(self, parts: list[str]) -> tuple[Table, tuple[str, ...]] | None:
+        """
+        Resolve *parts* to (hosting block, block-relative path).
+        """
+        node: Any = self.root
+        consumed: list[str] = []
+        for part in parts:
+            child = node[part] if isinstance(node, Table) and part in node else None
+            if isinstance(child, Table):
+                node = child
+                consumed.append(part)
+            else:
+                # leaf value: the current table hosts the key; the rest of the path is the dotted key
+                return node, tuple(parts[len(consumed):])
+        return node, ()
+
+    def _line_end(self, offset: int) -> int:
+        nxt = self._source.find(chr(10), offset)
+        return nxt if nxt != -1 else len(self._source)
+
+    def __repr__(self) -> str:
+        return f"Document({dict.__repr__(self.root)})"
+
+
+def _to_plain(table: Table) -> dict[str, Any]:
+    out: dict[str, Any] = {}
+    for key in table:
+        value = table[key]
+        if isinstance(value, Table):
+            out[key] = _to_plain(value)
+        elif isinstance(value, (ArrayOfTables, list)):
+            out[key] = [_to_plain_value(v) for v in value]
+        else:
+            out[key] = value
+    return out
+
+
+def _to_plain_value(value: Any) -> Any:
+    if isinstance(value, Table):
+        return _to_plain(value)
+    if isinstance(value, (ArrayOfTables, list)):
+        return [_to_plain_value(v) for v in value]
+    return value
+
+
+def plain_dict(doc: Document) -> dict[str, Any]:
+    """
+    tomllib-style plain-dict conversion of a whole :class:`Document`.
+    """
+    return _to_plain(doc.root)

tomlclass/engine_set.py

@@ -0,0 +1,146 @@
+"""
+Edit hooks backing :meth:`Table.__setitem__` / :meth:`Table.__delitem__`.
+
+Assignments do not mutate rendered text directly; they register the change on
+the *physical block* that hosts the entry, and the renderer picks it up:
+
+- ``block.dirty[path]``       — edited entries, spliced into their line
+- ``block.pending[path]``     — new entries, rendered after the block's last
+  parsed entry (values assigned to existing keys only go to ``dirty``)
+- ``block.pending_tables``    — newly created ``[sub]`` tables
+- ``block.deleted[path]``     — entries removed via ``del``
+
+Validation happens eagerly: values that cannot be represented in TOML raise
+:class:`TOMLTypeError` at assignment time, not at render time.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .errors import TOMLTypeError
+from .nodes import ArrayOfTables, Table, format_value
+
+__all__: list[str] = []
+
+
+def engine_set(table: Table, rel: tuple[str, ...], value: Any) -> Any:
+    """
+    Register the edit; return the object that must be stored in the tree.
+    """
+    if table.inline:
+        path = table._phys + rel
+        raise TOMLTypeError(
+            "inline tables are closed; reassign the whole value instead",
+            path=path,
+            value=value,
+        )
+
+    # new keys on sealed (dotted) tables render as dotted lines anchored to
+    # their own last physical line — register on the sealed table itself
+    if table.sealed and table._block is not None and rel[0] not in table:
+        table.pending.append((rel, value))
+        table.deleted.discard(rel)
+        return value
+
+    block = table._block if table._block is not None else table
+    path = table._phys + rel
+
+    if isinstance(value, Table):
+        if value._block is not None or value.kind == "root":
+            raise TOMLTypeError(
+                "cannot reassign a table that already belongs to a document",
+                path=path,
+                value=value,
+            )
+        # new [sub]table: register a pending header block
+        value._block = block
+        value._phys = path
+        value.kind = "header"
+        block.pending_tables.append((path, value))
+        block.deleted.discard(path)
+        return value
+
+    if isinstance(value, dict):
+        # plain dicts become [table] blocks (use InlineTable explicitly for inline)
+        from .nodes import Table as _Table
+
+        sub = _Table(kind="header")
+        for k, v in value.items():
+            sub[k] = v
+        block.pending_tables.append((path, sub))
+        block.deleted.discard(path)
+        return sub
+
+    existing = table._raw_get(rel[0]) if len(rel) == 1 else None
+    if isinstance(existing, ArrayOfTables) and isinstance(value, list):
+        # whole replacement: old elements stop rendering,
+        # new elements render as [[...]] blocks and are immediately readable
+
+        for element in list(existing):
+            if isinstance(element, Table):
+                mark_dead(element)
+        for item in value:
+            if not isinstance(item, dict):
+                raise TOMLTypeError(
+                    "array-of-tables replacement accepts dicts only",
+                    path=path,
+                    value=item,
+                )
+        list.clear(existing)
+        for item in value:
+            list.append(existing, dict(item))
+        existing.pending_elements = [dict(item) for item in value]
+        block.deleted.discard(path)
+        return value
+
+    # eager serializability check — None, functions, arbitrary objects raise here
+    format_value(value)
+    block.dirty[path] = value
+    block.deleted.discard(path)
+    if path not in block.entry_spans:
+        block.pending.append((path, value))
+    return value
+
+
+def engine_del(table: Table, rel: tuple[str, ...]) -> None:
+    if table.inline:
+        path = table._phys + rel
+        raise TOMLTypeError(
+            "inline tables are closed; reassign the whole value instead",
+            path=path,
+            value=None,
+        )
+
+    # engine-created keys on sealed tables: drop from their own pending
+    if table.sealed and table._block is not None and rel[0] not in table:
+        table.pending = [(p, v) for (p, v) in table.pending if p != rel]
+        table.deleted.discard(rel)
+        return
+
+    block = table._block if table._block is not None else table
+    path = table._phys + rel
+    target = table._raw_get(rel[0])
+
+    if isinstance(target, ArrayOfTables):
+        for element in target:
+            if isinstance(element, Table):
+                mark_dead(element)
+    elif isinstance(target, Table):
+        mark_dead(target)
+
+    if path in block.entry_spans:
+        block.deleted.add(path)
+    block.dirty.pop(path, None)
+    block.pending = [(p, v) for (p, v) in block.pending if p != path]
+    block.pending_tables = [(p, t) for (p, t) in block.pending_tables if p != path]
+
+
+def mark_dead(table: Table) -> None:
+    """
+    Mark a parsed table subtree dead — its parts render as nothing.
+    """
+    table.dead = True
+    for value in table.values():
+        if isinstance(value, Table):
+            mark_dead(value)

tomlclass/errors.py

@@ -0,0 +1,116 @@
+"""
+tomlclass exception hierarchy.
+
+Integrates with stdlib conventions:
+
+- :class:`TOMLParseError` subclasses :class:`ValueError` (the same contract as
+  :class:`tomllib.TOMLDecodeError`), so ``except ValueError`` keeps working.
+- :class:`TOMLTypeError` subclasses :class:`TypeError` — raised when a value
+  cannot be represented in TOML (``None``, functions, arbitrary objects …).
+- :class:`ConfigError` / :class:`ValidationError` power the annotation layer;
+  :class:`ValidationError` aggregates *all* offending fields instead of
+  failing on the first one.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class TOMLError(Exception):
+    """
+    Base class for every error raised by tomlclass.
+    """
+
+
+class TOMLParseError(TOMLError, ValueError):
+    """
+    A TOML document failed to parse.
+
+    Also a :class:`ValueError` (stdlib convention, mirroring
+    :class:`tomllib.TOMLDecodeError`).
+
+    :param message: human-readable failure description
+    :param offset: character offset into the source (``None`` for semantic errors)
+    :param line: 1-based line number (``None`` for semantic errors)
+    :param col: 1-based column number (``None`` for semantic errors)
+    :param segment: the offending source line, trimmed
+    """
+
+    def __init__(
+        self,
+        message: str,
+        offset: int | None = None,
+        line: int | None = None,
+        col: int | None = None,
+        segment: str = "",
+    ) -> None:
+        if line is not None:
+            loc = f" (line {line}, column {col})"
+            body = f"{message}{loc}:\n    {segment}"
+        else:
+            body = message
+        super().__init__(body)
+        self.message = message
+        self.offset = offset
+        self.line = line
+        self.col = col
+        self.segment = segment
+
+
+class TOMLTypeError(TOMLError, TypeError):
+    """
+    A value cannot be represented in TOML.
+
+    :param message: human-readable description
+    :param path: dotted key path the value was assigned to, if known
+    :param value: the offending value
+    """
+
+    def __init__(self, message: str, *, path: tuple[str, ...] | None = None, value: Any = None) -> None:
+        loc = f" at '{'.'.join(path)}'" if path else ""
+        super().__init__(f"{message}{loc}")
+        self.message = message
+        self.path = path
+        self.value = value
+
+
+class FieldError:
+    """
+    A single schema violation.
+
+    :param path: dotted key path of the offending field
+    :param message: human-readable description
+    """
+
+    __slots__ = ("message", "path")
+
+    def __init__(self, path: str, message: str) -> None:
+        self.path = path
+        self.message = message
+
+    def __str__(self) -> str:
+        return f"{self.path}: {self.message}"
+
+    def __repr__(self) -> str:
+        return f"FieldError({self.path!r}, {self.message!r})"
+
+
+class ConfigError(TOMLError, ValueError):
+    """
+    Base class for annotation-layer errors.
+    """
+
+
+class ValidationError(ConfigError):
+    """
+    Schema validation failed; aggregates every offending field.
+
+    :param errors: list of :class:`FieldError`
+    """
+
+    def __init__(self, errors: list[FieldError]) -> None:
+        self.errors = errors
+        summary = "; ".join(str(e) for e in errors[:5])
+        more = f" (+{len(errors) - 5} more)" if len(errors) > 5 else ""
+        super().__init__(f"{len(errors)} validation error(s): {summary}{more}")