pytex-preprocessor 0.2.0__tar.gz → 0.3.0__tar.gz

{pytex_preprocessor-0.2.0 → pytex_preprocessor-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytex-preprocessor
-Version: 0.2.0
+Version: 0.3.0
 Summary: Type-safe LaTeX document generation with Python
 Author-email: Frederik Beimgraben <frederik@beimgraben.net>
 Requires-Python: >=3.13
@@ -90,7 +90,7 @@ The input file is dispatched by extension:
 | --- | --- |
 | `.py` | imported as a module; its `__pytex__` node is rendered. Convention: name it `<doc>.tex.py`. |
 | `.tex` | wrapped in `IncludeTeX`; inline `\iffalse{pytex(...)}\fi` markers are evaluated, then rendered. Convention: `<doc>.py.tex`. |
-| `.md` / `.markdown` | converted to nodes via `IncludeMarkdown`. Frontmatter with `gremium:` or `typ: protokoll` routes to the protocol renderer instead. |
+| `.md` / `.markdown` | converted to nodes and wrapped in a document according to `--variant` (see below). Without `--variant` the style is auto-detected. |
 
 ### Inline replacements in `.tex`
 
@@ -111,6 +111,10 @@ Plain Python works too: $3^2 = \iffalse{pytex(3 ** 2)}\fi$.
 | `-b`, `--build` | off | compile the rendered `.tex` to PDF with tectonic |
 | `--build-dir DIR` | `build` | directory for artifacts and tectonic output |
 | `--no-shell-escape` | shell-escape on | disable shell-escape |
+| `-t`, `--tree` | off | also print the input's `TeX`-node tree (`tree`-style) before rendering/building |
+| `-f`, `--force` | off | skip the optimize + analysis pass and build even if problems are found |
+| `--variant STYLE` | auto-detect | Markdown output style (`plain`, `report`, `protocol-asta`, `protocol-stupa`) |
+| `--config JSON` | none | JSON object of document-class params, merged over the frontmatter |
 
 Shell-escape is on by default because inline images decode their base64
 payloads at compile time. The build runs tectonic, then `makeindex` (for
@@ -120,6 +124,42 @@ Output is minimal and color-tagged (`==>`, `note:`, `warning:`, `error:`),
 following tectonic's style; on failure it points at the likely cause and the
 log file. Set `NO_COLOR` to disable color.
 
+### Pre-flight optimize + analysis
+
+Before rendering, the builder runs two render-equivalent passes over the node
+tree. First `Optimize` tidies the tree (flatten nested `Concat`s, drop empty
+nodes, turn whole-`Raw` LaTeX constructs into native nodes) without changing
+the output (it also expands inline `pytex(...)` markers and turns `Raw`
+comments and math — `\[...\]`, `\(...\)`, `$...$` — into native nodes). Then
+`pytex_analyze` checks for problems that LaTeX would only surface later (or
+silently):
+
+- references (`\ref`, `\cref`, `\autoref`, ...) to a label that is never
+  defined,
+- labels defined more than once,
+- `\includegraphics` paths that do not exist on disk.
+
+Missing-image issues are errors and abort the build; the rest are warnings.
+Pass `-f`/`--force` to skip both passes and build regardless.
+
+### Inspecting the node tree
+
+`--tree` prints the parsed `TeX`-node tree (then renders/builds as usual),
+useful for debugging how an input maps to nodes. Nodes that require a package
+are tagged with it (`[+package]`):
+
+```
+$ pytex example.tex.py --tree
+Document (article)
+├── ControlSequence \title
+│   └── Parameter { }
+│       └── Raw "PyTeX Example"
+└── Concat
+    ├── ControlSequence \maketitle
+    ├── ControlSequence \cref [+cleveref]
+    └── ...
+```
+
 ## Packages
 
 `pytex` is the core; the rest are optional and build on it.
@@ -130,6 +170,7 @@ log file. Set `NO_COLOR` to disable color.
 | `pytex_koma` | KOMA-Script classes and commands (`Addchap`, `Minisec`, `KOMAoptions`, ...). |
 | `pytex_tikz` | TikZ pictures and primitives (`TikzPicture`, `Draw`, `Node`, `Circle`, ...). |
 | `pytex_markdown` | Markdown -> native `TeX` conversion (see below). |
+| `pytex_analyze` | static checks over the node tree (dangling refs, duplicate labels, missing images), plus `Optimize` to simplify a tree render-equivalently. |
 | `pytex_hsrtreport` | HSRT report document class, colored callout boxes, title pages, glossary/citation helpers. |
 | `pytex_protocol` | STUPA/AStA meeting minutes from Markdown, built on `pytex_hsrtreport`. |
 
@@ -157,6 +198,49 @@ GitHub-style callouts become HSRT colored boxes (so the module depends on
 Both factories are registered, so they work in `\iffalse{pytex(...)}\fi`
 replacements in `.tex` sources too.
 
+### Output variants
+
+When the `pytex` command renders a `.md` file it wraps the converted nodes in a
+document chosen by `--variant`:
+
+| Variant | Document |
+| --- | --- |
+| `plain` | a bare `Document` (default class `article`); `#` -> `\section`. |
+| `report` | an HSRT report with title page and table of contents; `#` -> `\chapter`. |
+| `protocol-asta` | an AStA meeting protocol (HSRT report, AStA logos). |
+| `protocol-stupa` | a StuPa meeting protocol (HSRT report, StuPa logos). |
+
+Without `--variant`, protocol frontmatter (`gremium:` or `typ: protokoll`) picks
+a protocol style and everything else falls back to `plain`.
+
+Document-class parameters come from the YAML frontmatter and from `--config`
+(a JSON object that overrides the frontmatter), e.g.:
+
+```sh
+pytex notes.md --variant plain --config '{"documentclass": "scrartcl", "classoptions": ["11pt", "twocolumn"]}'
+```
+
+`classoptions` accepts a list (`"twocolumn"`, `"DIV=12"`) or a `{key: value}`
+object. For styles with a title page (`report`), the title is taken from
+`title:`/`--config` if given, otherwise from the first `#` heading (which is then
+not also rendered as a chapter).
+
+## Converting LaTeX to PyTeX
+
+`pytex-tex2py` turns an existing `.tex` file into an equivalent `.tex.py`
+source. It reads the file, runs `Optimize` over it (expanding inline
+`pytex(...)` markers and recognising comments and math), and serialises the
+result to Python that rebuilds the same tree:
+
+```sh
+pytex-tex2py paper.tex            # -> paper.tex.py
+pytex-tex2py paper.tex -o out.py
+```
+
+Rendering the generated `.tex.py` reproduces the original output byte-for-byte;
+nodes the serialiser does not special-case fall back to a literal `Raw`, so the
+conversion always round-trips.
+
 ## Examples
 
 See `examples/` for one minimal input per kind (`.tex.py`, `.py.tex`, `.md`,

{pytex_preprocessor-0.2.0 → pytex_preprocessor-0.3.0}/README.md

@@ -76,7 +76,7 @@ The input file is dispatched by extension:
 | --- | --- |
 | `.py` | imported as a module; its `__pytex__` node is rendered. Convention: name it `<doc>.tex.py`. |
 | `.tex` | wrapped in `IncludeTeX`; inline `\iffalse{pytex(...)}\fi` markers are evaluated, then rendered. Convention: `<doc>.py.tex`. |
-| `.md` / `.markdown` | converted to nodes via `IncludeMarkdown`. Frontmatter with `gremium:` or `typ: protokoll` routes to the protocol renderer instead. |
+| `.md` / `.markdown` | converted to nodes and wrapped in a document according to `--variant` (see below). Without `--variant` the style is auto-detected. |
 
 ### Inline replacements in `.tex`
 
@@ -97,6 +97,10 @@ Plain Python works too: $3^2 = \iffalse{pytex(3 ** 2)}\fi$.
 | `-b`, `--build` | off | compile the rendered `.tex` to PDF with tectonic |
 | `--build-dir DIR` | `build` | directory for artifacts and tectonic output |
 | `--no-shell-escape` | shell-escape on | disable shell-escape |
+| `-t`, `--tree` | off | also print the input's `TeX`-node tree (`tree`-style) before rendering/building |
+| `-f`, `--force` | off | skip the optimize + analysis pass and build even if problems are found |
+| `--variant STYLE` | auto-detect | Markdown output style (`plain`, `report`, `protocol-asta`, `protocol-stupa`) |
+| `--config JSON` | none | JSON object of document-class params, merged over the frontmatter |
 
 Shell-escape is on by default because inline images decode their base64
 payloads at compile time. The build runs tectonic, then `makeindex` (for
@@ -106,6 +110,42 @@ Output is minimal and color-tagged (`==>`, `note:`, `warning:`, `error:`),
 following tectonic's style; on failure it points at the likely cause and the
 log file. Set `NO_COLOR` to disable color.
 
+### Pre-flight optimize + analysis
+
+Before rendering, the builder runs two render-equivalent passes over the node
+tree. First `Optimize` tidies the tree (flatten nested `Concat`s, drop empty
+nodes, turn whole-`Raw` LaTeX constructs into native nodes) without changing
+the output (it also expands inline `pytex(...)` markers and turns `Raw`
+comments and math — `\[...\]`, `\(...\)`, `$...$` — into native nodes). Then
+`pytex_analyze` checks for problems that LaTeX would only surface later (or
+silently):
+
+- references (`\ref`, `\cref`, `\autoref`, ...) to a label that is never
+  defined,
+- labels defined more than once,
+- `\includegraphics` paths that do not exist on disk.
+
+Missing-image issues are errors and abort the build; the rest are warnings.
+Pass `-f`/`--force` to skip both passes and build regardless.
+
+### Inspecting the node tree
+
+`--tree` prints the parsed `TeX`-node tree (then renders/builds as usual),
+useful for debugging how an input maps to nodes. Nodes that require a package
+are tagged with it (`[+package]`):
+
+```
+$ pytex example.tex.py --tree
+Document (article)
+├── ControlSequence \title
+│   └── Parameter { }
+│       └── Raw "PyTeX Example"
+└── Concat
+    ├── ControlSequence \maketitle
+    ├── ControlSequence \cref [+cleveref]
+    └── ...
+```
+
 ## Packages
 
 `pytex` is the core; the rest are optional and build on it.
@@ -116,6 +156,7 @@ log file. Set `NO_COLOR` to disable color.
 | `pytex_koma` | KOMA-Script classes and commands (`Addchap`, `Minisec`, `KOMAoptions`, ...). |
 | `pytex_tikz` | TikZ pictures and primitives (`TikzPicture`, `Draw`, `Node`, `Circle`, ...). |
 | `pytex_markdown` | Markdown -> native `TeX` conversion (see below). |
+| `pytex_analyze` | static checks over the node tree (dangling refs, duplicate labels, missing images), plus `Optimize` to simplify a tree render-equivalently. |
 | `pytex_hsrtreport` | HSRT report document class, colored callout boxes, title pages, glossary/citation helpers. |
 | `pytex_protocol` | STUPA/AStA meeting minutes from Markdown, built on `pytex_hsrtreport`. |
 
@@ -143,6 +184,49 @@ GitHub-style callouts become HSRT colored boxes (so the module depends on
 Both factories are registered, so they work in `\iffalse{pytex(...)}\fi`
 replacements in `.tex` sources too.
 
+### Output variants
+
+When the `pytex` command renders a `.md` file it wraps the converted nodes in a
+document chosen by `--variant`:
+
+| Variant | Document |
+| --- | --- |
+| `plain` | a bare `Document` (default class `article`); `#` -> `\section`. |
+| `report` | an HSRT report with title page and table of contents; `#` -> `\chapter`. |
+| `protocol-asta` | an AStA meeting protocol (HSRT report, AStA logos). |
+| `protocol-stupa` | a StuPa meeting protocol (HSRT report, StuPa logos). |
+
+Without `--variant`, protocol frontmatter (`gremium:` or `typ: protokoll`) picks
+a protocol style and everything else falls back to `plain`.
+
+Document-class parameters come from the YAML frontmatter and from `--config`
+(a JSON object that overrides the frontmatter), e.g.:
+
+```sh
+pytex notes.md --variant plain --config '{"documentclass": "scrartcl", "classoptions": ["11pt", "twocolumn"]}'
+```
+
+`classoptions` accepts a list (`"twocolumn"`, `"DIV=12"`) or a `{key: value}`
+object. For styles with a title page (`report`), the title is taken from
+`title:`/`--config` if given, otherwise from the first `#` heading (which is then
+not also rendered as a chapter).
+
+## Converting LaTeX to PyTeX
+
+`pytex-tex2py` turns an existing `.tex` file into an equivalent `.tex.py`
+source. It reads the file, runs `Optimize` over it (expanding inline
+`pytex(...)` markers and recognising comments and math), and serialises the
+result to Python that rebuilds the same tree:
+
+```sh
+pytex-tex2py paper.tex            # -> paper.tex.py
+pytex-tex2py paper.tex -o out.py
+```
+
+Rendering the generated `.tex.py` reproduces the original output byte-for-byte;
+nodes the serialiser does not special-case fall back to a literal `Raw`, so the
+conversion always round-trips.
+
 ## Examples
 
 See `examples/` for one minimal input per kind (`.tex.py`, `.py.tex`, `.md`,

{pytex_preprocessor-0.2.0 → pytex_preprocessor-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pytex-preprocessor"
-version = "0.2.0"
+version = "0.3.0"
 authors = [
   { name="Frederik Beimgraben", email="frederik@beimgraben.net" },
 ]
@@ -18,6 +18,7 @@ dev = ["pytest", "ruff", "basedpyright"]
 
 [project.scripts]
 pytex = "pytex_builder.build:main"
+pytex-tex2py = "pytex_builder.tex2py:main"
 
 [tool.setuptools.packages.find]
 where = ["src"]

{pytex_preprocessor-0.2.0 → pytex_preprocessor-0.3.0}/src/pytex/__init__.py

@@ -27,6 +27,7 @@ from .commands import (
 from .helpers import coerce, sanitize, with_package
 from .model import (
     color,
+    comment,
     concat,
     control_sequence,
     document,
@@ -51,6 +52,7 @@ __all__ = [
     "coerce",
     "color",
     "colors",
+    "comment",
     "concat",
     "conditionals",
     "control_sequence",

pytex_preprocessor-0.3.0/src/pytex/model/comment.py

@@ -0,0 +1,26 @@
+from dataclasses import dataclass, field
+from typing import Final, override
+
+from ..interface.tex import TeX
+from ..registry import Registry
+
+__all__ = ["Comment"]
+
+
+@Registry.add
+@dataclass(frozen=True)
+class Comment(TeX):
+    """A LaTeX comment: ``%`` followed by text and the terminating newline.
+
+    `text` is the content between the ``%`` and the end of the line (the
+    leading space in ``% note`` is part of it). The trailing newline *is* part
+    of the rendered output, so a comment ends its line as written.
+    """
+
+    text: Final[str]
+    _parent: "TeX | None" = field(default=None, init=False, compare=False, repr=False)
+
+    @property
+    @override
+    def rendered(self) -> str:
+        return f"%{self.text}\n"

pytex_preprocessor-0.3.0/src/pytex/model/concat.py

@@ -0,0 +1,55 @@
+from dataclasses import dataclass
+from typing import Final, override
+
+from ..helpers.coerce import coerce_tex
+from ..helpers.parenting import attach
+from ..interface.tex import TeX
+from ..registry import Registry
+from .empty import Empty, EmptyTeX
+from .raw import Raw
+
+__all__ = ["Concat"]
+
+
+def _is_empty(node: TeX) -> bool:
+    """A node that renders to nothing and can be dropped from a `Concat`."""
+    return isinstance(node, EmptyTeX) or (isinstance(node, Raw) and node.content == "")
+
+
+@Registry.add
+@dataclass(frozen=True, init=False)
+class Concat(TeX):
+    elements: Final[tuple[TeX, ...]]
+
+    def __new__(cls, *elements: TeX | str) -> TeX:
+        coerced = tuple(
+            node for node in map(coerce_tex, elements) if not _is_empty(node)
+        )
+        # Collapse trivial concatenations: nothing -> Empty, a single child ->
+        # that child unwrapped. (`__init__` is a no-op, so returning a node of
+        # any type here is safe.)
+        if not coerced:
+            return Empty
+        if len(coerced) == 1:
+            return coerced[0]
+        instance = super().__new__(cls)
+        object.__setattr__(instance, "elements", coerced)
+        object.__setattr__(instance, "_parent", None)
+        attach(instance, *coerced)
+        return instance
+
+    def __init__(self, *elements: TeX | str) -> None:
+        # All construction happens in `__new__`; this keeps the call signature
+        # and prevents dataclass from generating an `__init__` that would
+        # overwrite the already-built instance.
+        pass
+
+    @property
+    @override
+    def children(self) -> tuple[TeX, ...]:
+        return self.elements
+
+    @property
+    @override
+    def rendered(self) -> str:
+        return "".join(str(e) for e in self.elements)

{pytex_preprocessor-0.2.0 → pytex_preprocessor-0.3.0}/src/pytex/model/control_sequence.py

@@ -60,6 +60,11 @@ class ControlSequence[P: Parameters](TeX):
         if self.params is not None:
             attach(self, *self.params)
 
+    @property
+    @override
+    def children(self) -> tuple[TeX, ...]:
+        return tuple(self.params or ())
+
     @property
     @override
     def requires(self) -> frozenset[PackageProtocol]:

{pytex_preprocessor-0.2.0 → pytex_preprocessor-0.3.0}/src/pytex/model/document.py

@@ -29,6 +29,11 @@ class Document(TeX):
     def __post_init__(self) -> None:
         attach(self, self.body, self.preamble)
 
+    @property
+    @override
+    def children(self) -> tuple[TeX, ...]:
+        return (coerce_tex(self.preamble), coerce_tex(self.body))
+
     @property
     def packages(self) -> frozenset[PackageProtocol]:
         def get_packages(obj: TeX, found: set[PackageProtocol]) -> None:

{pytex_preprocessor-0.2.0 → pytex_preprocessor-0.3.0}/src/pytex/model/math.py

@@ -28,6 +28,7 @@ __all__ = [
     "Hat",
     "IIInt",
     "IInt",
+    "InlineMath",
     "Int",
     "LabelM",
     "Lim",
@@ -75,6 +76,12 @@ def Math(body: TeX | str) -> TeX:
     )
 
 
+@Registry.add
+def InlineMath(body: TeX | str) -> TeX:
+    """Dollar-delimited inline math: ``$body$``."""
+    return Concat(Raw("$"), body, Raw("$"))
+
+
 @Registry.add
 def DisplayMath(body: TeX | str) -> TeX:
     return Concat(

pytex_preprocessor-0.3.0/src/pytex_analyze/__init__.py

@@ -0,0 +1,16 @@
+"""Static analysis of a `TeX` node tree.
+
+Walks the document AST and reports likely problems before the source is handed
+to tectonic: references to undefined labels, labels defined more than once, and
+`\\includegraphics` paths that do not exist on disk.
+
+    from pytex_analyze import analyze, Severity
+
+    for issue in analyze(node):
+        print(issue.severity, issue.message)
+"""
+
+from .analyze import Issue, Severity, analyze
+from .optimize import Optimize
+
+__all__ = ["Issue", "Optimize", "Severity", "analyze"]

pytex_preprocessor-0.3.0/src/pytex_analyze/analyze.py

@@ -0,0 +1,106 @@
+"""Checks run over a `TeX` node tree to flag problems before compilation."""
+
+from __future__ import annotations
+
+from collections import Counter
+from dataclasses import dataclass
+from enum import Enum
+from typing import TYPE_CHECKING, cast
+
+from pytex.model.control_sequence import ControlSequence, Parameter
+from pytex.model.image import IncludeImage
+from pytex.model.raw import Raw
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from pytex.interface.control_sequence import Parameters
+    from pytex.interface.tex import TeX
+
+__all__ = ["Issue", "Severity", "analyze"]
+
+# Control sequences that reference a label by name. Each takes a single
+# (possibly comma-separated) argument of label names.
+_REF_COMMANDS = frozenset(
+    {"ref", "pageref", "nameref", "autoref", "eqref", "vref", "cref", "Cref"}
+)
+_LABEL_COMMANDS = frozenset({"label"})
+
+
+class Severity(Enum):
+    WARNING = "warning"
+    ERROR = "error"
+
+
+@dataclass(frozen=True)
+class Issue:
+    severity: Severity
+    message: str
+
+
+def _walk(node: TeX) -> Iterator[TeX]:
+    yield node
+    for child in node.children or ():
+        yield from _walk(child)
+
+
+def _first_required_text(cs: ControlSequence[Parameters]) -> str | None:
+    """Text of the first non-optional parameter of `cs`, if it is plain text."""
+    for param in cs.params or ():
+        if isinstance(param, Parameter) and not param.optional:
+            value = param.value
+            if isinstance(value, str):
+                return value
+            if isinstance(value, Raw):
+                return value.content
+            return None
+    return None
+
+
+def analyze(node: TeX) -> list[Issue]:
+    """Return the problems found in the tree rooted at `node`.
+
+    Pure and side-effect free: only reads the tree (and, for images, checks
+    whether source files exist on disk).
+    """
+    label_counts: Counter[str] = Counter()
+    references: list[str] = []
+    issues: list[Issue] = []
+
+    for current in _walk(node):
+        if isinstance(current, ControlSequence):
+            cs = cast("ControlSequence[Parameters]", current)
+            if (
+                cs.name in _LABEL_COMMANDS
+                and (text := _first_required_text(cs)) is not None
+            ):
+                label_counts[text] += 1
+            elif (
+                cs.name in _REF_COMMANDS
+                and (text := _first_required_text(cs)) is not None
+            ):
+                references.extend(
+                    name.strip() for name in text.split(",") if name.strip()
+                )
+        elif isinstance(current, IncludeImage) and not current.source_path.exists():
+            issues.append(
+                Issue(
+                    Severity.ERROR,
+                    f"image file not found: {current.source_path}",
+                )
+            )
+
+    for label, count in sorted(label_counts.items()):
+        if count > 1:
+            issues.append(
+                Issue(Severity.WARNING, f"label {label!r} defined {count} times")
+            )
+
+    defined = set(label_counts)
+    for name in sorted(set(references)):
+        if name not in defined:
+            issues.append(
+                Issue(Severity.WARNING, f"reference to undefined label {name!r}")
+            )
+
+    return issues