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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytex-preprocessor
-Version: 0.2.0
+Version: 0.4.0
 Summary: Type-safe LaTeX document generation with Python
 Author-email: Frederik Beimgraben <frederik@beimgraben.net>
 Requires-Python: >=3.13
@@ -28,6 +28,20 @@ uses.
 
 ## Install
 
+### Prebuilt binary
+
+Each release attaches standalone `pytex` binaries (Linux/macOS/Windows) — no
+Python or `pip` needed. Download one from the
+[Releases](https://github.com/frederikbeimgraben/PyTeX-Preprocessor/releases)
+page, make it executable, and run it. The binary bundles its own interpreter
+plus common data packages (numpy, pandas, openpyxl/calamine for spreadsheets,
+Pillow, PyYAML), so documents can `import` those without installing anything;
+see [`packaging/`](packaging/). It is built on Python 3.14, so documents may use
+`tex(t"...")` even on machines without 3.14. (`--build` still needs `tectonic`,
+which pytex downloads on first use.)
+
+### From PyPI
+
 To use the `pytex` command anywhere, install it as an isolated tool with
 [pipx](https://pipx.pypa.io/):
 
@@ -82,6 +96,22 @@ pytex example.tex.py --build  # render + compile -> build/example.out.pdf
 
 Bare strings are coerced to text nodes and LaTeX-escaped.
 
+### Template strings (Python 3.14+)
+
+On Python 3.14, `pytex.tex` accepts a [PEP 750](https://peps.python.org/pep-0750/)
+template string and builds a `TeX` tree from it. Static parts are literal LaTeX;
+interpolations are LaTeX-escaped when they are plain values and spliced as-is
+when they are `TeX` nodes (nested template strings and lists are handled too):
+
+```py
+from pytex import tex
+
+name = "Q&A: 50%"
+body = tex(t"{Bold('Heading')} — {name}")   # node spliced; name -> "Q\&A: 50\%"
+```
+
+`tex` is only exported on 3.14+; the rest of the library runs on 3.13.
+
 ## The `pytex` command
 
 The input file is dispatched by extension:
@@ -90,7 +120,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 +141,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 +154,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 +200,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 +228,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.4.0}/README.md

@@ -14,6 +14,20 @@ uses.
 
 ## Install
 
+### Prebuilt binary
+
+Each release attaches standalone `pytex` binaries (Linux/macOS/Windows) — no
+Python or `pip` needed. Download one from the
+[Releases](https://github.com/frederikbeimgraben/PyTeX-Preprocessor/releases)
+page, make it executable, and run it. The binary bundles its own interpreter
+plus common data packages (numpy, pandas, openpyxl/calamine for spreadsheets,
+Pillow, PyYAML), so documents can `import` those without installing anything;
+see [`packaging/`](packaging/). It is built on Python 3.14, so documents may use
+`tex(t"...")` even on machines without 3.14. (`--build` still needs `tectonic`,
+which pytex downloads on first use.)
+
+### From PyPI
+
 To use the `pytex` command anywhere, install it as an isolated tool with
 [pipx](https://pipx.pypa.io/):
 
@@ -68,6 +82,22 @@ pytex example.tex.py --build  # render + compile -> build/example.out.pdf
 
 Bare strings are coerced to text nodes and LaTeX-escaped.
 
+### Template strings (Python 3.14+)
+
+On Python 3.14, `pytex.tex` accepts a [PEP 750](https://peps.python.org/pep-0750/)
+template string and builds a `TeX` tree from it. Static parts are literal LaTeX;
+interpolations are LaTeX-escaped when they are plain values and spliced as-is
+when they are `TeX` nodes (nested template strings and lists are handled too):
+
+```py
+from pytex import tex
+
+name = "Q&A: 50%"
+body = tex(t"{Bold('Heading')} — {name}")   # node spliced; name -> "Q\&A: 50\%"
+```
+
+`tex` is only exported on 3.14+; the rest of the library runs on 3.13.
+
 ## The `pytex` command
 
 The input file is dispatched by extension:
@@ -76,7 +106,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 +127,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 +140,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 +186,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 +214,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.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pytex-preprocessor"
-version = "0.2.0"
+version = "0.4.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"]
@@ -36,6 +37,9 @@ addopts = "--import-mode=importlib"
 line-length = 88
 target-version = "py313"
 src = ["src", "tests"]
+# Uses Python 3.14 t-string syntax; the py313 target cannot parse it. Excluded
+# from lint/format (it is exercised by pytest on 3.14).
+extend-exclude = ["tests/pytex/test_template.py"]
 
 [tool.ruff.lint]
 select = [

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

@@ -1,3 +1,5 @@
+import sys
+
 from . import packages
 from .commands import (
     biblatex,
@@ -27,6 +29,7 @@ from .commands import (
 from .helpers import coerce, sanitize, with_package
 from .model import (
     color,
+    comment,
     concat,
     control_sequence,
     document,
@@ -51,6 +54,7 @@ __all__ = [
     "coerce",
     "color",
     "colors",
+    "comment",
     "concat",
     "conditionals",
     "control_sequence",
@@ -85,3 +89,10 @@ __all__ = [
     "tables",
     "with_package",
 ]
+
+# `tex(t"...")` needs PEP 750 template strings (Python 3.14+). Exposed only
+# there; the rest of the library stays importable on 3.13.
+if sys.version_info >= (3, 14):
+    from .template import tex as tex  # pyright: ignore[reportUnreachable]
+
+    __all__.append("tex")

pytex_preprocessor-0.4.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.4.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.4.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.4.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.4.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.4.0/src/pytex/template.py

@@ -0,0 +1,90 @@
+r"""`tex(t"...")` — build a `TeX` tree from a template string (PEP 750).
+
+Requires Python 3.14 (the ``t"..."`` syntax and :mod:`string.templatelib`).
+This module is import-safe on older versions — it contains no t-string literals
+and guards the runtime import — but :func:`tex` can only be called with a real
+``Template``, which cannot exist before 3.14. ``pytex`` only re-exports it on
+3.14+.
+
+The rendering model mirrors the escape boundary a LaTeX document needs:
+
+* static template parts are literal LaTeX (author-written, trusted);
+* interpolations are escaped when they are plain values, spliced as-is when
+  they are `TeX` nodes, and recursed when they are nested template strings or
+  iterables of the above.
+
+    name = "Q&A: 50%"
+    tex(t"{Bold('Heading')} - {name}")   # node spliced; name -> "Q\&A: 50\%"
+"""
+
+# `string.templatelib` has no type stub before 3.14, so a type-checker running
+# on an older Python cannot type the `Template` import; silence that noise for
+# this module only (its logic is exercised on 3.14 in CI / the docker test).
+# pyright: reportMissingImports=false, reportUnknownVariableType=false
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast
+
+from .helpers.sanitize import escape_latex
+from .interface.tex import TeX
+from .model.concat import Concat
+from .model.empty import Empty
+from .model.raw import Raw
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from typing import Protocol
+
+    class _Interpolation(Protocol):
+        @property
+        def value(self) -> object: ...
+        @property
+        def conversion(self) -> str | None: ...
+        @property
+        def format_spec(self) -> str: ...
+
+    class _Template(Protocol):
+        def __iter__(self) -> Iterator[str | _Interpolation]: ...
+
+
+# Real `Template` class at runtime (3.14+) for the nested-template check; an
+# empty tuple on older versions makes the isinstance test always False.
+try:
+    from string.templatelib import Template
+
+    _template_classes = (Template,)
+except ImportError:  # Python < 3.14
+    _template_classes = ()
+
+_TEMPLATE_TYPES: tuple[type, ...] = _template_classes
+
+__all__ = ["tex"]
+
+_CONVERSIONS = {"r": repr, "s": str, "a": ascii}
+
+
+def tex(template: _Template) -> TeX:
+    """Render a t-string into a `TeX` tree (see the module docstring)."""
+    parts: list[TeX] = []
+    for item in template:
+        if isinstance(item, str):
+            parts.append(Raw(item))  # literal LaTeX
+        else:
+            parts.append(_coerce(item.value, item.conversion, item.format_spec))
+    return Concat(*parts)
+
+
+def _coerce(value: object, conversion: str | None = None, spec: object = "") -> TeX:
+    if value is None:
+        return Empty
+    if isinstance(value, TeX):
+        return value
+    if isinstance(value, _TEMPLATE_TYPES):
+        return tex(cast("_Template", value))
+    if isinstance(value, (list, tuple)):
+        items = cast("tuple[object, ...] | list[object]", value)
+        return Concat(*(_coerce(item) for item in items))
+    if conversion in _CONVERSIONS:
+        value = _CONVERSIONS[conversion](value)
+    text = format(value, spec if isinstance(spec, str) else "")
+    return Raw(escape_latex(text))

pytex_preprocessor-0.4.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"]