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

pytex_preprocessor-0.2.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: pytex-preprocessor
+Version: 0.2.0
+Summary: Type-safe LaTeX document generation with Python
+Author-email: Frederik Beimgraben <frederik@beimgraben.net>
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic
+Requires-Dist: marko
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: basedpyright; extra == "dev"
+
+# PyTeX
+
+Type-safe LaTeX document generation with Python. Build a document as a tree of
+typed `TeX` nodes and render it to a `.tex` file, or drop inline Python
+expressions into an existing `.tex` source and have them evaluated at render
+time. Requires Python 3.13+.
+
+A `TeX` node is an immutable dataclass with a `.rendered` property. The public
+API mirrors LaTeX control sequences as PascalCase factories (`Section`,
+`Bold`, `Frac`, `Title`, ...), so a document reads like the LaTeX it produces
+while staying checkable by a type checker. Nodes track their package
+requirements, so the preamble is assembled automatically from what the body
+uses.
+
+## Install
+
+To use the `pytex` command anywhere, install it as an isolated tool with
+[pipx](https://pipx.pypa.io/):
+
+```sh
+pipx install pytex-preprocessor
+```
+
+It is also available via plain `pip install pytex-preprocessor`.
+
+For development, work in a virtualenv with an editable install instead:
+
+```sh
+python -m venv venv && . venv/bin/activate
+pip install -e .            # add [dev] for pytest, ruff, basedpyright
+```
+
+External tools, each needed only for the matching feature:
+
+- `tectonic` — compile to PDF (`--build`). If not on `PATH`, the build
+  downloads a self-contained binary into a temp folder and reuses it.
+- `inkscape` — `SVG` image conversion.
+- `makeindex` (from a TeX distribution, e.g. TeX Live) — resolve
+  glossaries/acronyms.
+
+## Quick start
+
+A `.tex.py` file is plain Python exposing a module-level `__pytex__` that holds
+a `TeX` node:
+
+```py
+from pytex.commands.builtin import Bold, Emph, Section, Title, MakeTitle
+from pytex.model.concat import Concat
+from pytex.model.document import Document
+from pytex.model.math import DisplayMath, Frac
+
+__pytex__ = Document(
+    preamble=Title("PyTeX Example"),
+    body=Concat(
+        MakeTitle(),
+        Section("Text"),
+        "A paragraph with ", Bold("bold"), " and ", Emph("emphasised"), " words.",
+        Section("Math"),
+        DisplayMath(Concat("x = ", Frac("-b", "2a"))),
+    ),
+)
+```
+
+```sh
+pytex example.tex.py          # render -> build/example.out.tex
+pytex example.tex.py --build  # render + compile -> build/example.out.pdf
+```
+
+Bare strings are coerced to text nodes and LaTeX-escaped.
+
+## The `pytex` command
+
+The input file is dispatched by extension:
+
+| Extension | Handling |
+| --- | --- |
+| `.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. |
+
+### Inline replacements in `.tex`
+
+Any registered factory is in scope inside a marker. The `\iffalse ... \fi` pair
+is a LaTeX no-op, so the source still compiles as-is without PyTeX:
+
+```tex
+Today is \iffalse{pytex(Today())}\fi.
+A fraction: $\iffalse{pytex(Frac("1", "2"))}\fi$.
+Plain Python works too: $3^2 = \iffalse{pytex(3 ** 2)}\fi$.
+```
+
+### Options
+
+| Flag | Default | Meaning |
+| --- | --- | --- |
+| `-o`, `--output` | `<build-dir>/<input>.out.tex` | rendered LaTeX output path |
+| `-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 |
+
+Shell-escape is on by default because inline images decode their base64
+payloads at compile time. The build runs tectonic, then `makeindex` (for
+`glossaries`/acronyms), then reruns tectonic when an index changed.
+
+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.
+
+## Packages
+
+`pytex` is the core; the rest are optional and build on it.
+
+| Package | Provides |
+| --- | --- |
+| `pytex` | core node model, `Document`, math, tables, graphics, and factories for the common LaTeX packages (biblatex, cleveref, glossaries, hyperref, listings, ...). |
+| `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_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`. |
+
+## Markdown
+
+`pytex_markdown` converts Markdown to native `TeX` nodes (via `marko`):
+
+```py
+from pytex_markdown import Markdown, IncludeMarkdown
+
+body = Markdown("# Title\n\nText with **bold**, `code`, [a link](https://x).")
+body = IncludeMarkdown("notes.md", base_level=-1)   # base_level=-1: # -> \chapter
+```
+
+Headings, emphasis, inline/fenced code, lists, links, images, block quotes and
+thematic breaks map to the standard pytex library; text is LaTeX-escaped.
+GitHub-style callouts become HSRT colored boxes (so the module depends on
+`pytex_hsrtreport`):
+
+```md
+> [!NOTE]      -> InfoBox        > [!IMPORTANT] -> ImportantBox
+> [!TIP]       -> SuccessBox     > [!WARNING]   -> WarningBox
+```
+
+Both factories are registered, so they work in `\iffalse{pytex(...)}\fi`
+replacements in `.tex` sources too.
+
+## Examples
+
+See `examples/` for one minimal input per kind (`.tex.py`, `.py.tex`, `.md`,
+mixed, and a full HSRT report). Run from the repository root so relative paths
+resolve:
+
+```sh
+pytex examples/document.tex.py --build
+pytex examples/replacements.py.tex --build
+pytex examples/notes.md --build
+```

pytex_preprocessor-0.2.0/README.md

@@ -0,0 +1,156 @@
+# PyTeX
+
+Type-safe LaTeX document generation with Python. Build a document as a tree of
+typed `TeX` nodes and render it to a `.tex` file, or drop inline Python
+expressions into an existing `.tex` source and have them evaluated at render
+time. Requires Python 3.13+.
+
+A `TeX` node is an immutable dataclass with a `.rendered` property. The public
+API mirrors LaTeX control sequences as PascalCase factories (`Section`,
+`Bold`, `Frac`, `Title`, ...), so a document reads like the LaTeX it produces
+while staying checkable by a type checker. Nodes track their package
+requirements, so the preamble is assembled automatically from what the body
+uses.
+
+## Install
+
+To use the `pytex` command anywhere, install it as an isolated tool with
+[pipx](https://pipx.pypa.io/):
+
+```sh
+pipx install pytex-preprocessor
+```
+
+It is also available via plain `pip install pytex-preprocessor`.
+
+For development, work in a virtualenv with an editable install instead:
+
+```sh
+python -m venv venv && . venv/bin/activate
+pip install -e .            # add [dev] for pytest, ruff, basedpyright
+```
+
+External tools, each needed only for the matching feature:
+
+- `tectonic` — compile to PDF (`--build`). If not on `PATH`, the build
+  downloads a self-contained binary into a temp folder and reuses it.
+- `inkscape` — `SVG` image conversion.
+- `makeindex` (from a TeX distribution, e.g. TeX Live) — resolve
+  glossaries/acronyms.
+
+## Quick start
+
+A `.tex.py` file is plain Python exposing a module-level `__pytex__` that holds
+a `TeX` node:
+
+```py
+from pytex.commands.builtin import Bold, Emph, Section, Title, MakeTitle
+from pytex.model.concat import Concat
+from pytex.model.document import Document
+from pytex.model.math import DisplayMath, Frac
+
+__pytex__ = Document(
+    preamble=Title("PyTeX Example"),
+    body=Concat(
+        MakeTitle(),
+        Section("Text"),
+        "A paragraph with ", Bold("bold"), " and ", Emph("emphasised"), " words.",
+        Section("Math"),
+        DisplayMath(Concat("x = ", Frac("-b", "2a"))),
+    ),
+)
+```
+
+```sh
+pytex example.tex.py          # render -> build/example.out.tex
+pytex example.tex.py --build  # render + compile -> build/example.out.pdf
+```
+
+Bare strings are coerced to text nodes and LaTeX-escaped.
+
+## The `pytex` command
+
+The input file is dispatched by extension:
+
+| Extension | Handling |
+| --- | --- |
+| `.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. |
+
+### Inline replacements in `.tex`
+
+Any registered factory is in scope inside a marker. The `\iffalse ... \fi` pair
+is a LaTeX no-op, so the source still compiles as-is without PyTeX:
+
+```tex
+Today is \iffalse{pytex(Today())}\fi.
+A fraction: $\iffalse{pytex(Frac("1", "2"))}\fi$.
+Plain Python works too: $3^2 = \iffalse{pytex(3 ** 2)}\fi$.
+```
+
+### Options
+
+| Flag | Default | Meaning |
+| --- | --- | --- |
+| `-o`, `--output` | `<build-dir>/<input>.out.tex` | rendered LaTeX output path |
+| `-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 |
+
+Shell-escape is on by default because inline images decode their base64
+payloads at compile time. The build runs tectonic, then `makeindex` (for
+`glossaries`/acronyms), then reruns tectonic when an index changed.
+
+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.
+
+## Packages
+
+`pytex` is the core; the rest are optional and build on it.
+
+| Package | Provides |
+| --- | --- |
+| `pytex` | core node model, `Document`, math, tables, graphics, and factories for the common LaTeX packages (biblatex, cleveref, glossaries, hyperref, listings, ...). |
+| `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_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`. |
+
+## Markdown
+
+`pytex_markdown` converts Markdown to native `TeX` nodes (via `marko`):
+
+```py
+from pytex_markdown import Markdown, IncludeMarkdown
+
+body = Markdown("# Title\n\nText with **bold**, `code`, [a link](https://x).")
+body = IncludeMarkdown("notes.md", base_level=-1)   # base_level=-1: # -> \chapter
+```
+
+Headings, emphasis, inline/fenced code, lists, links, images, block quotes and
+thematic breaks map to the standard pytex library; text is LaTeX-escaped.
+GitHub-style callouts become HSRT colored boxes (so the module depends on
+`pytex_hsrtreport`):
+
+```md
+> [!NOTE]      -> InfoBox        > [!IMPORTANT] -> ImportantBox
+> [!TIP]       -> SuccessBox     > [!WARNING]   -> WarningBox
+```
+
+Both factories are registered, so they work in `\iffalse{pytex(...)}\fi`
+replacements in `.tex` sources too.
+
+## Examples
+
+See `examples/` for one minimal input per kind (`.tex.py`, `.py.tex`, `.md`,
+mixed, and a full HSRT report). Run from the repository root so relative paths
+resolve:
+
+```sh
+pytex examples/document.tex.py --build
+pytex examples/replacements.py.tex --build
+pytex examples/notes.md --build
+```

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pytex-preprocessor"
-version = "0.1.3"
+version = "0.2.0"
 authors = [
   { name="Frederik Beimgraben", email="frederik@beimgraben.net" },
 ]

{pytex_preprocessor-0.1.3 → pytex_preprocessor-0.2.0}/src/pytex/commands/builtin.py

@@ -33,12 +33,12 @@ __all__ = [
     "Group",
     "Hfill",
     "Hspace",
+    "HspaceStar",
     "Immediate",
     "Include",
     "IncludeOnly",
     "Indent",
     "Input",
-    "Inputfile",
     "Italic",
     "Item",
     "Itemize",
@@ -93,6 +93,7 @@ __all__ = [
     "Verse",
     "Vfill",
     "Vspace",
+    "VspaceStar",
     "Whiledo",
     "Write18",
 ]
@@ -264,15 +265,23 @@ def Pagebreak(n: int | None = None) -> TeX:
 
 
 @Registry.add
-def Hspace(amount: str, star: bool = False) -> TeX:
-    name = "hspace*" if star else "hspace"
-    return ControlSequence(name, (Parameter(amount),))
+def Hspace(amount: str) -> TeX:
+    return ControlSequence("hspace", (Parameter(amount),))
 
 
 @Registry.add
-def Vspace(amount: str, star: bool = False) -> TeX:
-    name = "vspace*" if star else "vspace"
-    return ControlSequence(name, (Parameter(amount),))
+def HspaceStar(amount: str) -> TeX:
+    return ControlSequence("hspace*", (Parameter(amount),))
+
+
+@Registry.add
+def Vspace(amount: str) -> TeX:
+    return ControlSequence("vspace", (Parameter(amount),))
+
+
+@Registry.add
+def VspaceStar(amount: str) -> TeX:
+    return ControlSequence("vspace*", (Parameter(amount),))
 
 
 @Registry.add
@@ -552,12 +561,6 @@ def Verbatiminput(path: str) -> TeX:
     return ControlSequence("verbatiminput", (Parameter(path),))
 
 
-@Registry.add
-def Inputfile(path: str) -> TeX:
-    """Alias for `\\input{path}` — `Input` already defined above as Input(path)."""
-    return ControlSequence("input", (Parameter(path),))
-
-
 @Registry.add
 def Whiledo(condition: TeX | str, body: TeX | str) -> TeX:
     return ControlSequence("whiledo", (Parameter(condition), Parameter(body)))

{pytex_preprocessor-0.1.3 → pytex_preprocessor-0.2.0}/src/pytex/commands/definitions.py

@@ -5,11 +5,15 @@ from ..registry import Registry
 
 __all__ = [
     "DeclareRobustCommand",
+    "DeclareRobustCommandStar",
     "Def",
     "Newcommand",
+    "NewcommandStar",
     "Newenvironment",
     "Providecommand",
+    "ProvidecommandStar",
     "Renewcommand",
+    "RenewcommandStar",
     "Renewenvironment",
 ]
 
@@ -38,9 +42,18 @@ def Newcommand(
     body: TeX | str,
     nargs: int | None = None,
     default: str | None = None,
-    star: bool = False,
 ) -> TeX:
-    return _cmd("newcommand", cs, nargs, default, body, star)
+    return _cmd("newcommand", cs, nargs, default, body, star=False)
+
+
+@Registry.add
+def NewcommandStar(
+    cs: str,
+    body: TeX | str,
+    nargs: int | None = None,
+    default: str | None = None,
+) -> TeX:
+    return _cmd("newcommand", cs, nargs, default, body, star=True)
 
 
 @Registry.add
@@ -49,9 +62,18 @@ def Renewcommand(
     body: TeX | str,
     nargs: int | None = None,
     default: str | None = None,
-    star: bool = False,
 ) -> TeX:
-    return _cmd("renewcommand", cs, nargs, default, body, star)
+    return _cmd("renewcommand", cs, nargs, default, body, star=False)
+
+
+@Registry.add
+def RenewcommandStar(
+    cs: str,
+    body: TeX | str,
+    nargs: int | None = None,
+    default: str | None = None,
+) -> TeX:
+    return _cmd("renewcommand", cs, nargs, default, body, star=True)
 
 
 @Registry.add
@@ -60,9 +82,18 @@ def Providecommand(
     body: TeX | str,
     nargs: int | None = None,
     default: str | None = None,
-    star: bool = False,
 ) -> TeX:
-    return _cmd("providecommand", cs, nargs, default, body, star)
+    return _cmd("providecommand", cs, nargs, default, body, star=False)
+
+
+@Registry.add
+def ProvidecommandStar(
+    cs: str,
+    body: TeX | str,
+    nargs: int | None = None,
+    default: str | None = None,
+) -> TeX:
+    return _cmd("providecommand", cs, nargs, default, body, star=True)
 
 
 @Registry.add
@@ -70,9 +101,17 @@ def DeclareRobustCommand(
     cs: str,
     body: TeX | str,
     nargs: int | None = None,
-    star: bool = False,
 ) -> TeX:
-    return _cmd("DeclareRobustCommand", cs, nargs, None, body, star)
+    return _cmd("DeclareRobustCommand", cs, nargs, None, body, star=False)
+
+
+@Registry.add
+def DeclareRobustCommandStar(
+    cs: str,
+    body: TeX | str,
+    nargs: int | None = None,
+) -> TeX:
+    return _cmd("DeclareRobustCommand", cs, nargs, None, body, star=True)
 
 
 @Registry.add

{pytex_preprocessor-0.1.3 → pytex_preprocessor-0.2.0}/src/pytex/commands/glossaries.py

@@ -10,10 +10,10 @@ __all__ = [
     "Acrlong",
     "Acrshort",
     "Gls",
+    "GlsUpper",
     "Glsenablehyper",
     "Glspl",
-    "Glsplupper",
-    "Glsupper",
+    "GlsplUpper",
     "Makeglossaries",
     "Newacronym",
     "Newglossaryentry",
@@ -80,7 +80,7 @@ def Gls(label: str) -> TeX:
 
 @Registry.add
 @with_package(GLOSSARIES)
-def Glsupper(label: str) -> TeX:
+def GlsUpper(label: str) -> TeX:
     return ControlSequence("Gls", (Parameter(label),))
 
 
@@ -92,7 +92,7 @@ def Glspl(label: str) -> TeX:
 
 @Registry.add
 @with_package(GLOSSARIES)
-def Glsplupper(label: str) -> TeX:
+def GlsplUpper(label: str) -> TeX:
     return ControlSequence("Glspl", (Parameter(label),))
 
 

{pytex_preprocessor-0.1.3 → pytex_preprocessor-0.2.0}/src/pytex_hsrtreport/boxes.py

@@ -1,7 +1,7 @@
 from dataclasses import dataclass, field
 from typing import Final, override
 
-from pytex.commands.builtin import Hspace, Noindent, Vspace
+from pytex.commands.builtin import HspaceStar, Noindent, VspaceStar
 from pytex.commands.colors import SelectColor
 from pytex.commands.floats import Minipage
 from pytex.commands.font import Fontsize, Selectfont
@@ -105,7 +105,7 @@ class ColoredBox(TeX):
             bg = round((BASE_OPACITY + PER_LEVEL * level) * 100)
             icon_op = bg + ICON_BOOST
             return Concat(
-                Vspace(r"0.5\baselineskip", star=True),
+                VspaceStar(r"0.5\baselineskip"),
                 Raw("~\\\\"),
                 Noindent(),
                 Minipage(
@@ -135,7 +135,7 @@ class ColoredBox(TeX):
                                     ),
                                 ),
                             ),
-                            Hspace("0.25cm+2pt", star=True),
+                            HspaceStar("0.25cm+2pt"),
                             Minipage(
                                 r"\linewidth-0.5cm-2pt",
                                 self.body,

{pytex_preprocessor-0.1.3 → pytex_preprocessor-0.2.0}/src/pytex_hsrtreport/titlepage.py

@@ -4,7 +4,7 @@ from typing import Final, override
 
 from pytex.commands.builtin import (
     Blenderfont,
-    Hspace,
+    HspaceStar,
     Newline,
     Noindent,
     Rule,
@@ -12,6 +12,7 @@ from pytex.commands.builtin import (
     Textbf,
     Vfill,
     Vspace,
+    VspaceStar,
 )
 from pytex.commands.colors import SelectColor
 from pytex.commands.floats import Titlepage as TitlepageEnv
@@ -97,7 +98,7 @@ class TitlePage(TeX):
                     Concat(
                         Blenderfont(),
                         HugeBig(),
-                        Hspace("-2.5pt", star=True),
+                        HspaceStar("-2.5pt"),
                         self.title,
                     )
                 ),
@@ -121,7 +122,7 @@ class TitlePage(TeX):
             yield SectionStar("Abstract")
             yield Vspace("-1em")
             yield self.abstract
-            yield Vspace("1em", star=True)
+            yield VspaceStar("1em")
         if not _is_blank(self.keywords):
             yield Raw(r"\par\noindent ")
             yield Textbf("Keywords")

{pytex_preprocessor-0.1.3 → pytex_preprocessor-0.2.0}/src/pytex_hsrtreport/voting.py

@@ -1,7 +1,7 @@
 from dataclasses import dataclass, field
 from typing import Final, override
 
-from pytex.commands.builtin import Textbf, Vspace
+from pytex.commands.builtin import Textbf, VspaceStar
 from pytex.commands.floats import Columnbreak, Multicols
 from pytex.commands.fontawesome import FaIcon
 from pytex.helpers.parenting import attach
@@ -67,7 +67,7 @@ class VotingResults(TeX):
         return ColoredBox(
             body=Concat(
                 self.body,
-                Vspace("-2em", star=True),
+                VspaceStar("-2em"),
                 Multicols(
                     3,
                     Concat(