rtfc 0.1.0__py3-none-any.whl

rtfc/_entry.py

@@ -0,0 +1,256 @@
+"""Changelog entry parsing and loading.
+
+An entry file is made of a TOML frontmatter delimited by ``+++`` lines,
+followed by the entry content::
+
+    +++
+    date = 2025-08-01
+    nonce = "k3jf9a"
+    section = "bugfix"
+
+    [metadata]
+    gh_issue = 123
+    +++
+    Fix a bug in the documentation format handling.
+
+The content is treated as opaque text: it is never parsed, only incorporated
+into the changelog where the documentation engine processes it.
+"""
+
+from __future__ import annotations
+
+import datetime
+import secrets
+import tomllib
+from collections.abc import Collection, Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import tomli_w
+
+from rtfc._validation import (
+    Field,
+    Schema,
+    ValidationContext,
+    ValidationError,
+    Validator,
+    dict_of,
+    iso_date,
+    nullable,
+    str_,
+)
+
+__all__ = ("ENTRY_SUFFIX", "Entry", "EntryError", "load_entries")
+
+ENTRY_SUFFIX = ".rtfc"
+"""File extension of changelog entry files."""
+
+
+def _file_name(nonce: str, section: str | None) -> str:
+    """The canonical entry file name: ``{nonce}.{section}.rtfc``, or ``{nonce}.rtfc`` without a section."""
+    stem = nonce if section is None else f"{nonce}.{section}"
+    return f"{stem}{ENTRY_SUFFIX}"
+
+
+_DELIMITER = "+++"
+
+
+class EntryError(Exception):
+    """Raised when a changelog entry cannot be read or is invalid."""
+
+
+class _FlatValue(Validator[Any]):
+    """Accepts any value except tables: metadata fields are top-level only."""
+
+    def validate(self, value: object, context: ValidationContext) -> Any:
+        if isinstance(value, Mapping):
+            raise ValidationError.single(context.path, "nested tables are not allowed")
+        return value
+
+
+class _Frontmatter(Schema):
+    date = Field(iso_date)
+    nonce = Field(str_)
+    section = Field(nullable(str_), default=None)
+    metadata = Field(dict_of(_FlatValue()), default_factory=dict)
+
+
+@dataclass(frozen=True, kw_only=True)
+class Entry:
+    """A changelog entry."""
+
+    path: Path
+    """The entry file."""
+
+    date: datetime.date
+    """Date of the change."""
+
+    nonce: str
+    """Unique identifier of the entry, part of the file name."""
+
+    section: str | None
+    """Id of the section the entry belongs to, if any."""
+
+    metadata: dict[str, Any]
+    """Free-form entry metadata."""
+
+    content: str
+    """Raw entry content, in the documentation format of the project."""
+
+    @classmethod
+    def create(
+        cls,
+        directory: Path,
+        *,
+        section: str | None = None,
+        metadata: dict[str, Any] | None = None,
+        content: str,
+    ) -> Entry:
+        """Create a new entry, dated today, with a generated nonce.
+
+        The entry file is named after the nonce and section.
+
+        Args:
+            directory: The entry directory, from the configuration.
+            section: Id of the section the entry belongs to, if any.
+            metadata: Entry metadata.
+            content: Entry content.
+        """
+        nonce = secrets.token_hex(4)
+        return cls(
+            path=directory / _file_name(nonce, section),
+            date=datetime.date.today(),
+            nonce=nonce,
+            section=section,
+            metadata=metadata or {},
+            content=content,
+        )
+
+    @classmethod
+    def from_file(
+        cls, file: Path, *, sections: Collection[str], metadata_validator: Validator[dict[str, Any]] | None = None
+    ) -> Entry:
+        """Load an entry from ``file``.
+
+        Args:
+            file: The entry file to load.
+            sections: Valid section ids, from the configuration.
+            metadata_validator: Validator applied to the entry metadata, built
+                from the configured metadata schema. ``None`` leaves metadata
+                free-form.
+
+        Raises:
+            EntryError: If the entry cannot be read or is invalid.
+        """
+        try:
+            text = file.read_text(encoding="utf-8")
+        except OSError as exc:
+            raise EntryError(f"{file.name}: {exc}") from exc
+        try:
+            data, body = _split_frontmatter(text)
+            try:
+                frontmatter = _Frontmatter.validate(data)
+            except ValidationError as exc:
+                raise EntryError(f"Invalid frontmatter:\n{exc}") from exc
+            if frontmatter.section is not None and frontmatter.section not in sections:
+                expected = ", ".join(map(repr, sections))
+                raise EntryError(f"Unknown section {frontmatter.section!r} (expected one of: {expected})")
+            metadata = frontmatter.metadata
+            if metadata_validator is not None:
+                try:
+                    metadata = metadata_validator.validate(metadata, ValidationContext(path=("metadata",)))
+                except ValidationError as exc:
+                    raise EntryError(f"Invalid metadata:\n{exc}") from exc
+            content = body.strip()
+            if not content:
+                raise EntryError("Entry has no content")
+        except EntryError as exc:
+            raise EntryError(f"{file.name}: {exc}") from exc
+        expected_name = _file_name(frontmatter.nonce, frontmatter.section)
+        if file.name != expected_name:
+            raise EntryError(
+                f"{file.name}: File name does not match the entry, expected {expected_name!r} "
+                "(derived from the 'nonce' and 'section' fields)"
+            )
+        return cls(
+            path=file,
+            date=frontmatter.date,
+            nonce=frontmatter.nonce,
+            section=frontmatter.section,
+            metadata=metadata,
+            content=content,
+        )
+
+    def write(self) -> None:
+        """Write the entry to its file, creating the entry directory if needed.
+
+        Raises:
+            EntryError: If a metadata value cannot be serialized to TOML.
+        """
+        frontmatter: dict[str, Any] = {"date": self.date, "nonce": self.nonce}
+        if self.section is not None:
+            frontmatter["section"] = self.section
+        if self.metadata:
+            frontmatter["metadata"] = self.metadata
+        try:
+            dumped = tomli_w.dumps(frontmatter)
+        except TypeError as exc:
+            raise EntryError(f"Cannot serialize frontmatter to TOML: {exc}") from exc
+        text = f"{_DELIMITER}\n{dumped}{_DELIMITER}\n{self.content}\n"
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.path.write_text(text, encoding="utf-8")
+
+
+def _split_frontmatter(text: str) -> tuple[dict[str, Any], str]:
+    """Split an entry file into its parsed TOML frontmatter and raw body."""
+    lines = text.split("\n")
+    if lines[0].rstrip() != _DELIMITER:
+        raise EntryError(f"Entry must start with a {_DELIMITER!r} frontmatter delimiter")
+    candidates = [i for i, line in enumerate(lines[1:], start=1) if line.rstrip() == _DELIMITER]
+    if not candidates:
+        raise EntryError(f"Missing closing {_DELIMITER!r} frontmatter delimiter")
+    first_error: tomllib.TOMLDecodeError | None = None
+    # The closing delimiter is the first `+++` line whose preceding text parses as valid
+    # TOML. A bare `+++` line can only appear inside a TOML multiline string, in which
+    # case the preceding text is invalid (unterminated string), so the first valid parse
+    # is necessarily the true delimiter.
+    for i in candidates:
+        try:
+            frontmatter = tomllib.loads("\n".join(lines[1:i]))
+        except tomllib.TOMLDecodeError as exc:
+            first_error = first_error or exc
+            continue
+        return frontmatter, "\n".join(lines[i + 1 :])
+    raise EntryError(f"Invalid frontmatter TOML: {first_error}") from first_error
+
+
+def load_entries(
+    directory: Path, *, sections: Collection[str], metadata_validator: Validator[dict[str, Any]] | None = None
+) -> list[Entry]:
+    """Load all changelog entries from ``directory``.
+
+    Only files with the ``.rtfc`` suffix are considered. Entries are returned
+    in file name order; all invalid entries are reported together.
+
+    Args:
+        directory: The entry directory, from the configuration.
+        sections: Valid section ids, from the configuration.
+        metadata_validator: Validator applied to the entry metadata, built from
+            the configured metadata schema. ``None`` leaves metadata free-form.
+
+    Raises:
+        EntryError: If the directory does not exist or any entry is invalid.
+    """
+    if not directory.is_dir():
+        raise EntryError(f"Entry directory {str(directory)!r} does not exist")
+    entries: list[Entry] = []
+    errors: list[str] = []
+    for file in sorted(directory.glob(f"*{ENTRY_SUFFIX}")):
+        try:
+            entries.append(Entry.from_file(file, sections=sections, metadata_validator=metadata_validator))
+        except EntryError as exc:
+            errors.append(str(exc))
+    if errors:
+        raise EntryError("\n".join(errors))
+    return entries

rtfc/_format/__init__.py

@@ -0,0 +1,39 @@
+"""Documentation format abstraction.
+
+A :class:`Format` produces the format-specific structure of the changelog
+(headings, list items, comments); it never parses entry content. The rst
+implementation is built in; third-party formats subclass :class:`Format` and
+register under the ``rtfc.formats`` entry point group.
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+
+from rtfc._format.base import Format, FormatError
+from rtfc._format.rst import RstFormat
+
+__all__ = ("Format", "FormatError", "RstFormat", "get_format")
+
+_ENTRY_POINT_GROUP = "rtfc.formats"
+
+_BUILTIN_FORMATS: dict[str, type[Format]] = {RstFormat.name: RstFormat}
+
+
+def get_format(name: str) -> Format:
+    """Resolve a format by name.
+
+    Built-in formats take priority; other names are looked up in the
+    ``rtfc.formats`` entry point group.
+
+    Raises:
+        FormatError: If the name cannot be resolved to a :class:`Format`.
+    """
+    if name in _BUILTIN_FORMATS:
+        return _BUILTIN_FORMATS[name]()
+    for entry_point in importlib.metadata.entry_points(group=_ENTRY_POINT_GROUP, name=name):
+        loaded = entry_point.load()
+        if not (isinstance(loaded, type) and issubclass(loaded, Format)):
+            raise FormatError(f"Entry point {name!r} in group {_ENTRY_POINT_GROUP!r} is not a Format subclass")
+        return loaded()
+    raise FormatError(f"Unknown format {name!r}")

rtfc/_format/base.py

@@ -0,0 +1,59 @@
+"""Base documentation format definition."""
+
+from __future__ import annotations
+
+import datetime
+from abc import ABC, abstractmethod
+from typing import ClassVar, final
+
+# The marker identity is format-independent (only the comment syntax around it
+# varies), so the changelog assembly logic can locate it in any format:
+_INSERT_MARKER = "rtfc-insert"
+
+
+class FormatError(Exception):
+    """Raised when a documentation format cannot be resolved."""
+
+
+class Format(ABC):
+    """A documentation format, defining the structure of the changelog."""
+
+    name: ClassVar[str]
+    """Name of the format, as referenced by the ``format`` configuration value."""
+
+    @abstractmethod
+    def heading(self, title: str, level: int) -> str:
+        """Format a heading.
+
+        Args:
+            title: The heading title.
+            level: Heading level, relative to the changelog document title:
+                ``1`` for versions, ``2`` for sections.
+        """
+
+    @abstractmethod
+    def comment(self, text: str) -> str:
+        """Format ``text`` as a comment, invisible in the rendered document."""
+
+    def version_header(self, version: str, date: datetime.date) -> str:
+        """Format the heading of a released version."""
+        return self.heading(f"v{version} ({date.isoformat()})", 1)
+
+    def unreleased_header(self) -> str:
+        """Format the heading of the unreleased changes."""
+        return self.heading("Unreleased", 1)
+
+    def section_header(self, label: str) -> str:
+        """Format the heading of an entry section."""
+        return self.heading(label, 2)
+
+    def list_item(self, text: str) -> str:
+        """Format already-rendered entry text as a list item."""
+        first, *rest = text.splitlines()
+        lines = [f"- {first}", *(f"  {line}" if line else "" for line in rest)]
+        return "\n".join(lines)
+
+    @final
+    def insert_marker(self) -> str:
+        """The comment after which new version blocks are inserted."""
+        return self.comment(_INSERT_MARKER)

rtfc/_format/rst.py

@@ -0,0 +1,22 @@
+"""The reStructuredText documentation format."""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+from rtfc._format.base import Format
+
+
+class RstFormat(Format):
+    """The reStructuredText format, for sphinx documentation."""
+
+    name: ClassVar[str] = "rst"
+
+    # Assumes the changelog document title is underlined with '=':
+    _underlines: ClassVar[dict[int, str]] = {1: "-", 2: "~"}
+
+    def heading(self, title: str, level: int) -> str:
+        return f"{title}\n{self._underlines[level] * len(title)}"
+
+    def comment(self, text: str) -> str:
+        return f".. {text}"

rtfc/_render/__init__.py

@@ -0,0 +1,15 @@
+"""Rendering of changelog entries into version blocks.
+
+A version block is the text added to the changelog for one release (or for the
+unreleased changes): a version header followed by the rendered entries, grouped
+by section. :class:`Renderer` orchestrates grouping, sorting and format
+structure; how a single entry is turned into text is left to subclasses, so
+that alternative template engines can be plugged in. :class:`JinjaRenderer` is
+the default, rendering entries through the configured Jinja template. Entry
+content is never parsed.
+"""
+
+from rtfc._render.base import Renderer, RenderError
+from rtfc._render.jinja import JinjaRenderer
+
+__all__ = ("JinjaRenderer", "RenderError", "Renderer")

rtfc/_render/base.py

@@ -0,0 +1,98 @@
+"""Base renderer definition."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Any
+
+from rtfc._config import Config
+from rtfc._entry import Entry
+from rtfc._format import Format
+
+_METADATA_SORT_PREFIX = "metadata."
+
+
+class RenderError(Exception):
+    """Raised when entries cannot be rendered."""
+
+
+@dataclass
+class SectionGroup:
+    """The entries of a changelog section, as exposed to version block templates."""
+
+    id: str | None
+    """Id of the section, or ``None`` for the unsectioned group."""
+
+    label: str | None
+    """Label of the section, or ``None`` for the unsectioned group."""
+
+    entries: list[Entry]
+    """The entries of the section, in file name order."""
+
+
+def sort_entries(entries: Sequence[Entry], keys: Sequence[str]) -> list[Entry]:
+    """Sort entries by the given keys: ``date``, ``nonce``, or ``metadata.<field>``.
+
+    Entries missing a value sort last.
+
+    Raises:
+        RenderError: If a key is unknown or entry values cannot be compared.
+    """
+    for sort_key in keys:
+        if sort_key not in ("date", "nonce") and not sort_key.startswith(_METADATA_SORT_PREFIX):
+            raise RenderError(f"Unknown sort key {sort_key!r} (expected 'date', 'nonce' or 'metadata.<key>')")
+
+    def key(entry: Entry) -> tuple[tuple[int, Any], ...]:
+        parts: list[tuple[int, Any]] = []
+        for sort_key in keys:
+            if sort_key.startswith(_METADATA_SORT_PREFIX):
+                # Metadata fields are top-level only, so the rest of the sort key is the literal field name:
+                value = entry.metadata.get(sort_key.removeprefix(_METADATA_SORT_PREFIX))
+            else:
+                value = getattr(entry, sort_key)
+            # Entries missing a value sort last, and (1, None) tuples compare equal:
+            parts.append((1, None) if value is None else (0, value))
+        return tuple(parts)
+
+    try:
+        return sorted(entries, key=key)
+    except TypeError as exc:
+        raise RenderError(f"Cannot sort entries by {list(keys)}: {exc}") from exc
+
+
+class Renderer(ABC):
+    """Renders changelog entries into version blocks."""
+
+    def __init__(self, *, config: Config, fmt: Format) -> None:
+        self.config = config
+        self.fmt = fmt
+
+    @abstractmethod
+    def render_entry(self, entry: Entry) -> str:
+        """Render a single entry into its changelog text, before list item wrapping.
+
+        Raises:
+            RenderError: If the entry cannot be rendered.
+        """
+
+    @abstractmethod
+    def render_block(self, entries: Sequence[Entry], *, header: str) -> str:
+        """Render entries into a version block, opened by the already-formatted ``header``.
+
+        Raises:
+            RenderError: If the entries cannot be rendered.
+        """
+
+    def group_entries(self, entries: Sequence[Entry]) -> list[SectionGroup]:
+        """Group entries by section: the unsectioned group first, then the configured sections in order.
+
+        Empty groups are included.
+        """
+        groups: dict[str | None, SectionGroup] = {None: SectionGroup(id=None, label=None, entries=[])}
+        for section_id, section in self.config.sections.items():
+            groups[section_id] = SectionGroup(id=section_id, label=section.label, entries=[])
+        for entry in entries:
+            groups[entry.section].entries.append(entry)
+        return list(groups.values())

rtfc/_render/jinja.py

@@ -0,0 +1,78 @@
+"""The Jinja template based renderer."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+import jinja2
+
+from rtfc._config import Config
+from rtfc._entry import Entry
+from rtfc._format import Format
+from rtfc._render.base import Renderer, RenderError, sort_entries
+
+_env = jinja2.Environment(trim_blocks=True, lstrip_blocks=True)
+_env.filters["sort_entries"] = lambda entries, *keys: sort_entries(entries, keys or ("date",))
+
+
+class JinjaRenderer(Renderer):
+    """The default renderer, driven by the configured Jinja templates.
+
+    The version block template receives ``header``, ``entries`` (all entries),
+    ``sections`` (the :class:`~rtfc._render.base.SectionGroup` of each
+    section), the ``render_entry()``, ``list_item()`` and ``section_header()``
+    functions, and can sort entries with the ``sort_entries()`` filter. The
+    entry template receives ``content``, ``date``, ``nonce``, ``section`` and
+    ``metadata``.
+    """
+
+    def __init__(self, *, config: Config, fmt: Format) -> None:
+        """
+        Args:
+            config: The project configuration.
+            fmt: The documentation format.
+
+        Raises:
+            RenderError: If a template is invalid.
+            ConfigError: If a template file cannot be read.
+        """
+        super().__init__(config=config, fmt=fmt)
+        try:
+            self._template = _env.from_string(config.render.resolve_template())
+        except jinja2.TemplateSyntaxError as exc:
+            raise RenderError(f"Invalid template: {exc}") from exc
+        try:
+            self._entry_template = _env.from_string(config.render.resolve_entry_template())
+        except jinja2.TemplateSyntaxError as exc:
+            raise RenderError(f"Invalid entry template: {exc}") from exc
+
+    def render_entry(self, entry: Entry) -> str:
+        try:
+            text = self._entry_template.render(
+                content=entry.content,
+                date=entry.date,
+                nonce=entry.nonce,
+                section=entry.section,
+                metadata=entry.metadata,
+            )
+        except Exception as exc:
+            raise RenderError(f"{entry.path.name}: Failed to render entry: {exc}") from exc
+        return text.strip()
+
+    def render_block(self, entries: Sequence[Entry], *, header: str) -> str:
+        context: dict[str, Any] = {
+            "header": header,
+            "entries": list(entries),
+            "sections": self.group_entries(entries),
+            "render_entry": self.render_entry,
+            "list_item": self.fmt.list_item,
+            "section_header": self.fmt.section_header,
+        }
+        try:
+            text = self._template.render(context)
+        except RenderError:
+            raise
+        except Exception as exc:
+            raise RenderError(f"Failed to render version block: {exc}") from exc
+        return text.strip()