pytex-preprocessor 0.1.0__py3-none-any.whl

pytex_protocol/convert.py

@@ -0,0 +1,202 @@
+"""A Markdown converter for meeting protocols.
+
+Extends the base :class:`pytex_markdown.convert.MarkdownConverter` with:
+
+* protocol callouts - ``> [!beschluss]``, ``> [!abstimmung]`` (parsed into a
+  vote tally), ``> [!aufgabe]``, ``> [!frist]`` - on top of the inherited
+  GitHub/Obsidian callouts;
+* inline ``{{shortcode}}`` expansion in every run of text.
+
+Agenda items (TOPs) are plain Markdown headings, so they need no special
+handling - they become numbered sections via the base converter.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING, Final, cast, override
+
+from pytex.model.concat import Concat
+from pytex_markdown.convert import CALLOUT_RE, MarkdownConverter
+
+from .entries import ActionItem, Deadline, Decision, Vote
+from .shortcodes import expand_inline_shortcodes
+from .signatures import SignatureLines
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping
+
+    from pytex.interface.tex import TeX
+
+    from .frontmatter import FrontmatterValue
+
+__all__ = ["ProtocolConverter"]
+
+# Callout marker -> single-body entry factory.
+_PROTOCOL_CALLOUTS: Final[dict[str, Callable[[TeX | str], TeX]]] = {
+    "BESCHLUSS": Decision,
+    "DECISION": Decision,
+    "AUFGABE": ActionItem,
+    "TODO": ActionItem,
+    "ACTION": ActionItem,
+    "FRIST": Deadline,
+    "DEADLINE": Deadline,
+}
+_VOTE_MARKERS: Final[frozenset[str]] = frozenset({"ABSTIMMUNG", "VOTE"})
+_SIGNATURE_MARKERS: Final[frozenset[str]] = frozenset({"UNTERSCHRIFTEN", "SIGNATURES"})
+
+_TALLY_RE: Final[dict[str, re.Pattern[str]]] = {
+    "yes": re.compile(r"(?:ja|yes)\s*[:=]?\s*(\d+)", re.IGNORECASE),
+    "no": re.compile(r"(?:nein|no)\s*[:=]?\s*(\d+)", re.IGNORECASE),
+    "abstain": re.compile(r"(?:enthaltung|enth\.?|abstain)\s*[:=]?\s*(\d+)", re.I),
+}
+
+
+def _kind(node: object) -> str:
+    return type(node).__name__
+
+
+def _text(node: object) -> str | None:
+    children = getattr(node, "children", None)
+    return children if isinstance(children, str) else None
+
+
+def _children(node: object) -> list[object]:
+    children = getattr(node, "children", None)
+    return cast("list[object]", children) if isinstance(children, list) else []
+
+
+def _all_text(node: object) -> str:
+    """Concatenate every literal text fragment beneath `node`."""
+    text = _text(node)
+    if text is not None:
+        return text
+    return "".join(_all_text(c) for c in _children(node))
+
+
+def _tally(text: str, key: str) -> int:
+    match = _TALLY_RE[key].search(text)
+    return int(match.group(1)) if match else 0
+
+
+def _leaf_texts(node: object) -> list[str]:
+    """Every leaf text fragment beneath `node`, in order (one per source line)."""
+    text = _text(node)
+    if text is not None:
+        return [text]
+    out: list[str] = []
+    for child in _children(node):
+        out.extend(_leaf_texts(child))
+    return out
+
+
+class ProtocolConverter(MarkdownConverter):
+    """`MarkdownConverter` with protocol callouts and inline shortcodes."""
+
+    meta: Mapping[str, FrontmatterValue]
+
+    def __init__(
+        self,
+        *,
+        meta: Mapping[str, FrontmatterValue] | None = None,
+        base_level: int = 0,
+        callouts: bool = True,
+    ) -> None:
+        super().__init__(base_level=base_level, callouts=callouts)
+        self.meta = meta or {}
+
+    # -- inline: splice {{shortcodes}} into otherwise-plain text ----------
+
+    @override
+    def inline(self, node: object) -> TeX:
+        if _kind(node) != "CodeSpan":
+            text = _text(node)
+            if text is not None and "{{" in text:
+                return expand_inline_shortcodes(text, self.meta)
+        return super().inline(node)
+
+    # -- blocks: protocol callouts ----------------------------------------
+
+    @override
+    def _as_callout(self, kids: list[object]) -> TeX | None:
+        marker = self._protocol_marker(kids)
+        if marker is None:
+            return super()._as_callout(kids)
+        name, title, head_rest, rest_blocks = marker
+        if name in _VOTE_MARKERS:
+            return self._vote_callout(title, kids)
+        if name in _SIGNATURE_MARKERS:
+            return self._signature_callout(kids)
+        factory = _PROTOCOL_CALLOUTS.get(name)
+        if factory is None:
+            return super()._as_callout(kids)
+        # First paragraph: marker title + its remaining inlines; then any
+        # following blocks of the callout.
+        head = Concat(self.inline_text(title), *(self.inline(c) for c in head_rest))
+        body_parts = [head, *(self.block(b) for b in rest_blocks)]
+        return factory(Concat(*_join(body_parts)))
+
+    def _protocol_marker(
+        self, kids: list[object]
+    ) -> tuple[str, str, list[object], list[object]] | None:
+        """Return (MARKER, title-after-marker, rest-of-first-paragraph,
+        following-blocks) if kids open a protocol callout we own, else None."""
+        if not kids or _kind(kids[0]) != "Paragraph":
+            return None
+        inner = _children(kids[0])
+        first = _text(inner[0]) if inner else None
+        if first is None:
+            return None
+        match = CALLOUT_RE.match(first)
+        if match is None:
+            return None
+        name = match.group(1).upper()
+        if (
+            name not in _PROTOCOL_CALLOUTS
+            and name not in _VOTE_MARKERS
+            and name not in _SIGNATURE_MARKERS
+        ):
+            return None
+        title = first[match.end() :].strip()
+        return name, title, inner[1:], kids[1:]
+
+    def _signature_callout(self, kids: list[object]) -> TeX:
+        # Each line "Rolle: Name" becomes one signer; the marker is stripped
+        # from the first line.
+        lines = [frag for k in kids for frag in _leaf_texts(k)]
+        if lines:
+            lines[0] = CALLOUT_RE.sub("", lines[0], count=1)
+        signers: list[tuple[str, str]] = []
+        for line in (entry.strip() for entry in lines):
+            if not line:
+                continue
+            role, _, person = line.partition(":")
+            signers.append((role.strip(), person.strip()))
+        return SignatureLines(*signers)
+
+    def _vote_callout(self, title: str, kids: list[object]) -> TeX:
+        text = " ".join(_all_text(k) for k in kids)
+        return Vote(
+            yes=_tally(text, "yes"),
+            no=_tally(text, "no"),
+            abstain=_tally(text, "abstain"),
+            body=self.inline_text(title) if title else "",
+        )
+
+    def inline_text(self, text: str) -> TeX:
+        """Expand `{{shortcodes}}` and escape the rest of a bare string."""
+        return expand_inline_shortcodes(text, self.meta)
+
+
+def _join(blocks: list[TeX]) -> list[TeX]:
+    from pytex.model.empty import Empty
+    from pytex.model.raw import Raw
+
+    parbreak = Raw("\n\n")
+    kept = [b for b in blocks if b is not Empty]
+    out: list[TeX] = []
+    for i, b in enumerate(kept):
+        if i:
+            out.append(parbreak)
+        out.append(b)
+    return out

pytex_protocol/document.py

@@ -0,0 +1,91 @@
+"""Render a STUPA/AStA meeting protocol from Obsidian-flavoured Markdown.
+
+The protocol is an :class:`~pytex_hsrtreport.document.HSRTReport` configured for
+a short minutes document: no title page, a compact header block (built from the
+frontmatter) at the top, agenda items as numbered sections, and protocol
+entries (decisions, votes, action items) rendered as HSRT callout boxes.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import marko
+
+from pytex.model.concat import Concat
+from pytex.model.raw import Raw
+from pytex.registry import Registry
+from pytex_hsrtreport.document import HSRTReport
+from pytex_hsrtreport.variants import Variant
+
+from .convert import ProtocolConverter
+from .frontmatter import FrontmatterValue, split_frontmatter
+from .header import header_from_meta
+from .signatures import signature_block_from_meta
+
+if TYPE_CHECKING:
+    from pytex.interface.tex import TeX
+
+__all__ = ["IncludeProtocol", "Protocol", "render_protocol"]
+
+_PARSER = marko.Markdown()
+
+_VARIANTS: dict[str, Variant] = {
+    "stupa": Variant.STUPA,
+    "asta": Variant.ASTA,
+    "echo": Variant.ECHO,
+}
+
+
+def _variant(meta: dict[str, FrontmatterValue]) -> Variant:
+    gremium = meta.get("gremium", "")
+    key = gremium.lower().strip() if isinstance(gremium, str) else ""
+    return _VARIANTS.get(key, Variant.STUPA)
+
+
+def _document_title(meta: dict[str, FrontmatterValue]) -> str:
+    gremium = meta.get("gremium")
+    datum = meta.get("datum")
+    head = (
+        f"{gremium} — Protokoll"
+        if isinstance(gremium, str) and gremium
+        else "Protokoll"
+    )
+    return f"{head} ({datum})" if isinstance(datum, str) and datum else head
+
+
+def render_protocol(text: str, *, base_level: int = 0) -> HSRTReport:
+    """Build an `HSRTReport` from the Markdown source of a protocol."""
+    meta, body_md = split_frontmatter(text)
+    converter = ProtocolConverter(meta=meta, base_level=base_level)
+    converted = converter.block(_PARSER.parse(body_md))
+    header = header_from_meta(meta)
+    # Optional sign-off block, appended when the frontmatter lists `unterschriften`.
+    signatures = signature_block_from_meta(meta)
+    tail = (Raw("\n\n"), signatures) if signatures is not None else ()
+    return HSRTReport(
+        variant=_variant(meta),
+        document_class="scrbook",
+        show_titlepage=False,
+        show_toc=False,
+        show_footer_logos=True,
+        title=_document_title(meta),
+        # Agenda items are top-level `#` headings -> \section. In scrbook a
+        # chapterless section would number as "0.1"; flatten it to a plain
+        # arabic counter so TOPs read 1, 2, 3, ...
+        user_preamble=Raw(r"\renewcommand*{\thesection}{\arabic{section}}"),
+        body=Concat(header, Raw("\n\n"), converted, *tail),
+    )
+
+
+@Registry.add
+def Protocol(text: str, *, base_level: int = 0) -> TeX:
+    """Convert a protocol Markdown string to a renderable `HSRTReport`."""
+    return render_protocol(text, base_level=base_level)
+
+
+@Registry.add
+def IncludeProtocol(path: str | Path, *, encoding: str = "utf-8") -> TeX:
+    """Read a protocol Markdown file and render it (see :func:`render_protocol`)."""
+    return render_protocol(Path(path).read_text(encoding=encoding))

pytex_protocol/entries.py

@@ -0,0 +1,96 @@
+"""Protocol entry factories, styled to match the HSRTReport callout language.
+
+Each entry is a coloured box (or, for votes, the existing ``VotingResults``
+tally) so a protocol reads with the same visual vocabulary as a report. Labels
+are German, matching the STUPA/AStA context.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pytex.commands.builtin import Textbf, Textit
+from pytex.commands.colors import Textcolor
+from pytex.commands.fontawesome import FaIcon
+from pytex.model.concat import Concat
+from pytex.registry import Registry
+from pytex_hsrtreport.boxes import ColoredBox
+from pytex_hsrtreport.voting import VotingResults
+
+if TYPE_CHECKING:
+    from pytex.interface.tex import TeX
+
+__all__ = [
+    "ActionItem",
+    "Deadline",
+    "Decision",
+    "Timestamp",
+    "Vote",
+]
+
+
+def _labelled_box(
+    label: str,
+    body: TeX | str,
+    *,
+    icon: str,
+    color: str,
+) -> TeX:
+    """A ColoredBox whose body is prefixed with a bold label, matching _preset."""
+    return ColoredBox(
+        body=Concat(Textbf(f"{label}: "), body),
+        icon=FaIcon(icon),
+        icon_color=color,
+        icon_size="24pt",
+        icon_offset_x="1.5pt",
+        background_color=color,
+    )
+
+
+@Registry.add
+def Decision(body: TeX | str) -> TeX:
+    """A resolution/`Beschluss` box (gavel, HSRT green)."""
+    return _labelled_box("Beschluss", body, icon="gavel", color="britishracinggreen")
+
+
+@Registry.add
+def Deadline(body: TeX | str, due: str | None = None) -> TeX:
+    """A `Frist` (deadline) box. `due` is appended in parentheses when given."""
+    content = Concat(body, Textit(f" (bis {due})")) if due else body
+    return _labelled_box("Frist", content, icon="hourglass-half", color="orange")
+
+
+@Registry.add
+def ActionItem(
+    body: TeX | str,
+    who: str | None = None,
+    due: str | None = None,
+) -> TeX:
+    """An `Aufgabe` (action item) box with optional assignee and due date."""
+    meta = ", ".join(
+        part
+        for part in (
+            f"Zuständig: {who}" if who else "",
+            f"Frist: {due}" if due else "",
+        )
+        if part
+    )
+    content = Concat(body, Textit(f" ({meta})")) if meta else body
+    return _labelled_box("Aufgabe", content, icon="clipboard-check", color="navyblue")
+
+
+@Registry.add
+def Vote(
+    yes: int,
+    no: int,
+    abstain: int = 0,
+    body: TeX | str = "",
+) -> TeX:
+    """A voting tally, reusing the report's `VotingResults` box."""
+    return VotingResults(yes=yes, no=no, abstain=abstain, body=body)
+
+
+@Registry.add
+def Timestamp(time: str) -> TeX:
+    """Inline timestamp: a clock glyph plus the time, in HSRT blue."""
+    return Textcolor("hanblue", Concat(FaIcon("clock"), " ", Textbf(time)))

pytex_protocol/frontmatter.py

@@ -0,0 +1,80 @@
+"""Minimal YAML-frontmatter splitter for protocol Markdown files.
+
+Obsidian writes a ``---`` fenced YAML block at the top of a note. We only need
+a tiny subset - scalars, inline flow lists (``[a, b]``) and block lists
+(``- item``) - so this is parsed without a YAML dependency.
+"""
+
+from __future__ import annotations
+
+__all__ = ["FrontmatterValue", "split_frontmatter"]
+
+type FrontmatterValue = str | list[str]
+
+
+def _strip_quotes(text: str) -> str:
+    text = text.strip()
+    if len(text) >= 2 and text[0] in "\"'" and text[-1] == text[0]:
+        return text[1:-1]
+    return text
+
+
+def _parse_flow_list(text: str) -> list[str]:
+    """Parse an inline ``[a, b, c]`` list into stripped, unquoted items."""
+    inner = text.strip()[1:-1]
+    return [_strip_quotes(item) for item in inner.split(",") if item.strip()]
+
+
+def _parse_block(lines: list[str]) -> dict[str, FrontmatterValue]:
+    meta: dict[str, FrontmatterValue] = {}
+    key: str | None = None
+    for raw in lines:
+        line = raw.rstrip()
+        if not line.strip():
+            continue
+        # A block-list continuation belongs to the most recent key.
+        if line.lstrip().startswith("- ") and key is not None:
+            item = _strip_quotes(line.lstrip()[2:])
+            existing = meta.get(key)
+            if isinstance(existing, list):
+                existing.append(item)
+            else:
+                meta[key] = [item]
+            continue
+        if ":" not in line:
+            continue
+        key, _, value = line.partition(":")
+        key = key.strip()
+        value = value.strip()
+        if not value:
+            # Either a block list follows, or an empty scalar.
+            meta[key] = ""
+        elif value.startswith("[") and value.endswith("]"):
+            meta[key] = _parse_flow_list(value)
+        else:
+            meta[key] = _strip_quotes(value)
+    return meta
+
+
+def split_frontmatter(text: str) -> tuple[dict[str, FrontmatterValue], str]:
+    """Split ``text`` into (frontmatter mapping, remaining body).
+
+    Returns an empty mapping and the unchanged text when no ``---`` fence opens
+    the document.
+    """
+    if not text.lstrip().startswith("---"):
+        return {}, text
+    # Normalise to make the leading fence easy to consume.
+    stripped = text.lstrip("\n")
+    lines = stripped.splitlines()
+    if not lines or lines[0].strip() != "---":
+        return {}, text
+    end = next(
+        (i for i in range(1, len(lines)) if lines[i].strip() == "---"),
+        None,
+    )
+    if end is None:
+        return {}, text
+    meta = _parse_block(lines[1:end])
+    body = "\n".join(lines[end + 1 :]).lstrip("\n")
+    return meta, body

pytex_protocol/header.py

@@ -0,0 +1,139 @@
+"""The compact protocol header block rendered at the top of a protocol.
+
+Maps the parsed frontmatter to a single HSRT-styled box: meeting body + date
+on top, then the organisational fields and the attendance lists. German labels
+throughout (STUPA/AStA context).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, override
+
+from pytex.commands.builtin import Textbf
+from pytex.commands.fontawesome import FaIcon
+from pytex.helpers.sanitize import escape_latex
+from pytex.interface.tex import TeX
+from pytex.model.concat import Concat
+from pytex.model.raw import Raw
+from pytex.registry import Registry
+from pytex_hsrtreport.boxes import ColoredBox
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator, Mapping
+
+    from .frontmatter import FrontmatterValue
+
+__all__ = ["ProtocolHeader", "header_from_meta"]
+
+# Frontmatter key -> human label for the single-value organisational fields.
+_FIELD_LABELS: tuple[tuple[str, str], ...] = (
+    ("ort", "Ort"),
+    ("sitzungsleitung", "Sitzungsleitung"),
+    ("protokoll", "Protokoll"),
+)
+# Frontmatter key -> label for the attendance lists (rendered with a count).
+_LIST_LABELS: tuple[tuple[str, str], ...] = (
+    ("anwesend", "Anwesend"),
+    ("entschuldigt", "Entschuldigt"),
+    ("abwesend", "Abwesend"),
+    ("gaeste", "Gäste"),
+)
+
+
+def _as_list(value: FrontmatterValue | None) -> list[str]:
+    if value is None:
+        return []
+    if isinstance(value, list):
+        return value
+    return [v.strip() for v in value.split(",") if v.strip()]
+
+
+def _line(label: str, value: str) -> TeX:
+    return Concat(Textbf(f"{label}: "), Raw(escape_latex(value)))
+
+
+@Registry.add
+@dataclass(frozen=True)
+class ProtocolHeader(TeX):
+    """A compact meeting-header box: title, date/time, fields, attendance."""
+
+    gremium: str = ""
+    datum: str = ""
+    beginn: str = ""
+    ende: str = ""
+    fields: Mapping[str, str] = field(default_factory=dict[str, str])
+    attendance: Mapping[str, list[str]] = field(default_factory=dict[str, list[str]])
+    _parent: TeX | None = field(default=None, init=False, compare=False, repr=False)
+
+    @property
+    def title(self) -> str:
+        body = self.gremium.strip()
+        return f"{body} — Protokoll" if body else "Protokoll"
+
+    def _datetime_line(self) -> str | None:
+        when = " – ".join(t for t in (self.beginn, self.ende) if t)  # noqa: RUF001
+        parts = ", ".join(p for p in (self.datum, when) if p)
+        return parts or None
+
+    def _lines(self) -> Iterator[TeX]:
+        yield Textbf(Raw(escape_latex(self.title)))
+        dt = self._datetime_line()
+        if dt:
+            yield _line("Datum", dt)
+        for key, label in _FIELD_LABELS:
+            value = self.fields.get(key, "")
+            if value:
+                yield _line(label, value)
+        for key, label in _LIST_LABELS:
+            people = self.attendance.get(key) or []
+            if people:
+                yield _line(f"{label} ({len(people)})", ", ".join(people))
+
+    @property
+    @override
+    def rendered(self) -> str:
+        body = Concat(*_intersperse(self._lines(), Raw(r"\\")))
+        return ColoredBox(
+            body=body,
+            icon=FaIcon("users"),
+            icon_color="hanblue",
+            icon_size="26pt",
+            background_color="hanblue",
+        ).rendered
+
+
+def _intersperse(items: Iterator[TeX], sep: TeX) -> Iterator[TeX]:
+    for i, item in enumerate(items):
+        if i:
+            yield sep
+        yield item
+
+
+def header_from_meta(meta: Mapping[str, FrontmatterValue]) -> ProtocolHeader:
+    """Build a `ProtocolHeader` from parsed frontmatter (German keys, aliases)."""
+
+    def scalar(*keys: str) -> str:
+        for key in keys:
+            value = meta.get(key)
+            if isinstance(value, str) and value:
+                return value
+        return ""
+
+    fields = {key: scalar(key) for key, _ in _FIELD_LABELS if scalar(key)}
+    attendance = {
+        key: _as_list(meta.get(key))
+        for key, _ in _LIST_LABELS
+        if _as_list(meta.get(key))
+    }
+    # `gäste` is the natural German spelling; accept it as an alias for `gaeste`.
+    if "gaeste" not in attendance and _as_list(meta.get("gäste")):
+        attendance["gaeste"] = _as_list(meta.get("gäste"))
+    return ProtocolHeader(
+        gremium=scalar("gremium", "gremium"),
+        datum=scalar("datum", "date"),
+        beginn=scalar("beginn", "start"),
+        ende=scalar("ende", "end"),
+        fields=fields,
+        attendance=attendance,
+    )