pytex-preprocessor 0.1.0rc1__tar.gz

pytex_preprocessor-0.1.0rc1/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: pytex-preprocessor
+Version: 0.1.0rc1
+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
+
+## Install
+
+```sh
+python -m venv venv && . venv/bin/activate
+pip install -e .            # add [dev] for pytest
+```
+
+`SVG` conversion needs `inkscape`. Compiling to PDF needs `tectonic` — if it
+is not on `PATH`, `pytex --build` downloads a self-contained binary into a
+temp folder and reuses it on later runs. Resolving glossaries/acronyms needs
+`makeindex` from a TeX distribution (e.g. TeX Live).
+
+## The `pytex` command
+
+```sh
+pytex example.tex.py          # render -> example.out.tex
+pytex example.tex.py --build  # render + compile -> build/example.out.pdf
+```
+
+The input is either:
+
+- a `.py` file exposing a module-level `__pytex__` variable that is a `TeX`
+  node (e.g. a `Document`) — it is rendered, or
+- a `.tex` file — wrapped in `IncludeTeX` (so `\iffalse pytex(...) \fi`
+  replacements are evaluated) and rendered.
+
+### Options
+
+| Flag | Default | Meaning |
+| --- | --- | --- |
+| `-o`, `--output` | `<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 enabled 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.
+
+## 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 are usable from `\iffalse pytex(...) \fi`
+replacements in `.tex` sources too.

pytex_preprocessor-0.1.0rc1/README.md

@@ -0,0 +1,68 @@
+# pytex
+
+## Install
+
+```sh
+python -m venv venv && . venv/bin/activate
+pip install -e .            # add [dev] for pytest
+```
+
+`SVG` conversion needs `inkscape`. Compiling to PDF needs `tectonic` — if it
+is not on `PATH`, `pytex --build` downloads a self-contained binary into a
+temp folder and reuses it on later runs. Resolving glossaries/acronyms needs
+`makeindex` from a TeX distribution (e.g. TeX Live).
+
+## The `pytex` command
+
+```sh
+pytex example.tex.py          # render -> example.out.tex
+pytex example.tex.py --build  # render + compile -> build/example.out.pdf
+```
+
+The input is either:
+
+- a `.py` file exposing a module-level `__pytex__` variable that is a `TeX`
+  node (e.g. a `Document`) — it is rendered, or
+- a `.tex` file — wrapped in `IncludeTeX` (so `\iffalse pytex(...) \fi`
+  replacements are evaluated) and rendered.
+
+### Options
+
+| Flag | Default | Meaning |
+| --- | --- | --- |
+| `-o`, `--output` | `<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 enabled 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.
+
+## 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 are usable from `\iffalse pytex(...) \fi`
+replacements in `.tex` sources too.

pytex_preprocessor-0.1.0rc1/pyproject.toml

@@ -0,0 +1,77 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pytex-preprocessor"
+version = "0.1.0rc1"
+authors = [
+  { name="Frederik Beimgraben", email="frederik@beimgraben.net" },
+]
+description = "Type-safe LaTeX document generation with Python"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = ["pydantic", "marko"]
+
+[project.optional-dependencies]
+dev = ["pytest", "ruff", "basedpyright"]
+
+[project.scripts]
+pytex = "pytex_builder.build:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+pytex_hsrtreport = ["assets/**/*", "tex/**/*"]
+
+[tool.pyright]
+extraPaths = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--import-mode=importlib"
+
+[tool.ruff]
+line-length = 88
+target-version = "py313"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+  "E",    # pycodestyle errors
+  "W",    # pycodestyle warnings
+  "F",    # pyflakes
+  "I",    # isort
+  "N",    # pep8-naming
+  "UP",   # pyupgrade
+  "B",    # flake8-bugbear
+  "C4",   # flake8-comprehensions
+  "SIM",  # flake8-simplify
+  "RET",  # flake8-return
+  "PIE",  # flake8-pie
+  "TC",   # flake8-type-checking
+  "ANN",  # flake8-annotations
+  "RUF",  # ruff-specific
+]
+# N802 (non-lowercase function names) is intentional: the public API mirrors
+# LaTeX control sequences as PascalCase factories (`Bfseries`, `Author`,
+# `Align`, ...). Renaming would break every document and downstream package.
+ignore = ["N802"]
+
+[tool.ruff.lint.per-file-ignores]
+# Tests favour readability over full annotation coverage.
+"tests/**" = ["ANN"]
+# These modules embed raw LaTeX templates whose German typography uses
+# non-ASCII glyphs on purpose (EN DASH separators, MULTIPLICATION SIGN). An
+# inline `noqa` is impossible since it would land inside the template string.
+# pagesetup is one large raw LaTeX template string; its lines cannot be
+# reflowed (a source break would alter the emitted LaTeX).
+"src/pytex_hsrtreport/pagesetup.py" = ["RUF001", "E501"]
+"src/pytex_hsrtreport/watermark.py" = ["RUF002"]
+# glossary holds raw LaTeX template constants (column types, style, labels)
+# that exceed the line length and cannot be reflowed.
+"src/pytex_hsrtreport/glossary.py" = ["E501"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["pytex", "pytex_builder", "pytex_koma", "pytex_tikz", "pytex_hsrtreport", "pytex_markdown"]

pytex_preprocessor-0.1.0rc1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pytex_preprocessor-0.1.0rc1/src/pytex/__init__.py

@@ -0,0 +1,87 @@
+from . import packages
+from .commands import (
+    biblatex,
+    builtin,
+    captions,
+    cleveref,
+    colors,
+    conditionals,
+    counters,
+    definitions,
+    floats,
+    font,
+    fontawesome,
+    fontspec,
+    geometry,
+    glossaries,
+    graphics,
+    hooks,
+    hyperref,
+    lengths,
+    listings,
+    mdframed,
+    picture,
+    setspace,
+    tables,
+)
+from .helpers import coerce, sanitize, with_package
+from .model import (
+    color,
+    concat,
+    control_sequence,
+    document,
+    document_class,
+    empty,
+    environment,
+    image,
+    include,
+    length,
+    math,
+    package,
+    raw,
+)
+from .registry import Registry
+
+__all__ = [
+    "Registry",
+    "biblatex",
+    "builtin",
+    "captions",
+    "cleveref",
+    "coerce",
+    "color",
+    "colors",
+    "concat",
+    "conditionals",
+    "control_sequence",
+    "counters",
+    "definitions",
+    "document",
+    "document_class",
+    "empty",
+    "environment",
+    "floats",
+    "font",
+    "fontawesome",
+    "fontspec",
+    "geometry",
+    "glossaries",
+    "graphics",
+    "hooks",
+    "hyperref",
+    "image",
+    "include",
+    "length",
+    "lengths",
+    "listings",
+    "math",
+    "mdframed",
+    "package",
+    "packages",
+    "picture",
+    "raw",
+    "sanitize",
+    "setspace",
+    "tables",
+    "with_package",
+]

pytex_preprocessor-0.1.0rc1/src/pytex/commands/__init__.py

@@ -0,0 +1,51 @@
+from . import (
+    biblatex,
+    builtin,
+    captions,
+    cleveref,
+    colors,
+    conditionals,
+    counters,
+    definitions,
+    floats,
+    font,
+    fontawesome,
+    fontspec,
+    geometry,
+    glossaries,
+    graphics,
+    hooks,
+    hyperref,
+    lengths,
+    listings,
+    mdframed,
+    picture,
+    setspace,
+    tables,
+)
+
+__all__ = [
+    "biblatex",
+    "builtin",
+    "captions",
+    "cleveref",
+    "colors",
+    "conditionals",
+    "counters",
+    "definitions",
+    "floats",
+    "font",
+    "fontawesome",
+    "fontspec",
+    "geometry",
+    "glossaries",
+    "graphics",
+    "hooks",
+    "hyperref",
+    "lengths",
+    "listings",
+    "mdframed",
+    "picture",
+    "setspace",
+    "tables",
+]

pytex_preprocessor-0.1.0rc1/src/pytex/commands/biblatex.py

@@ -0,0 +1,98 @@
+from ..helpers.with_package import with_package
+from ..interface.tex import TeX
+from ..model.control_sequence import ControlSequence, Parameter
+from ..packages import BIBLATEX
+from ..registry import Registry
+
+__all__ = [
+    "Addbibresource",
+    "Autocite",
+    "Citeauthor",
+    "Citetitle",
+    "Citeyear",
+    "ExecuteBibliographyOptions",
+    "Footcite",
+    "Nocite",
+    "Parencite",
+    "Printbibliography",
+    "Textcite",
+]
+
+
+@Registry.add
+@with_package(BIBLATEX)
+def Addbibresource(path: str) -> TeX:
+    return ControlSequence("addbibresource", (Parameter(path),))
+
+
+@Registry.add
+@with_package(BIBLATEX)
+def Printbibliography(
+    heading: str | None = None,
+    title: str | None = None,
+) -> TeX:
+    opts = [
+        f"{key}={value}"
+        for key, value in (("heading", heading), ("title", title))
+        if value is not None
+    ]
+    if not opts:
+        return ControlSequence("printbibliography", ())
+    return ControlSequence(
+        "printbibliography",
+        (Parameter(",".join(opts), optional=True),),
+    )
+
+
+@Registry.add
+@with_package(BIBLATEX)
+def Textcite(*keys: str) -> TeX:
+    return ControlSequence("textcite", (Parameter(",".join(keys)),))
+
+
+@Registry.add
+@with_package(BIBLATEX)
+def Parencite(*keys: str) -> TeX:
+    return ControlSequence("parencite", (Parameter(",".join(keys)),))
+
+
+@Registry.add
+@with_package(BIBLATEX)
+def Autocite(*keys: str) -> TeX:
+    return ControlSequence("autocite", (Parameter(",".join(keys)),))
+
+
+@Registry.add
+@with_package(BIBLATEX)
+def Footcite(*keys: str) -> TeX:
+    return ControlSequence("footcite", (Parameter(",".join(keys)),))
+
+
+@Registry.add
+@with_package(BIBLATEX)
+def Citeauthor(key: str) -> TeX:
+    return ControlSequence("citeauthor", (Parameter(key),))
+
+
+@Registry.add
+@with_package(BIBLATEX)
+def Citeyear(key: str) -> TeX:
+    return ControlSequence("citeyear", (Parameter(key),))
+
+
+@Registry.add
+@with_package(BIBLATEX)
+def Citetitle(key: str) -> TeX:
+    return ControlSequence("citetitle", (Parameter(key),))
+
+
+@Registry.add
+@with_package(BIBLATEX)
+def Nocite(*keys: str) -> TeX:
+    return ControlSequence("nocite", (Parameter(",".join(keys)),))
+
+
+@Registry.add
+@with_package(BIBLATEX)
+def ExecuteBibliographyOptions(options: dict[str, str]) -> TeX:
+    return ControlSequence("ExecuteBibliographyOptions", (Parameter(options),))