pytex-preprocessor 0.1.0rc1__py3-none-any.whl

pytex/packages.py

@@ -0,0 +1,221 @@
+from enum import Enum
+
+from pytex.model.package import DefinePackage, Package
+
+__all__ = ["Packages"]
+
+AMSMATH: Package = DefinePackage("amsmath")
+AMSSYMB: Package = DefinePackage("amssymb")
+AMSFONTS: Package = DefinePackage("amsfonts")
+MATHTOOLS: Package = DefinePackage("mathtools")
+HYPERREF: Package = DefinePackage("hyperref")
+URL: Package = DefinePackage("url")
+GRAPHICX: Package = DefinePackage("graphicx")
+XCOLOR: Package = DefinePackage("xcolor")
+GEOMETRY: Package = DefinePackage("geometry")
+FONTENC: Package = DefinePackage("fontenc")
+INPUTENC: Package = DefinePackage("inputenc")
+BABEL: Package = DefinePackage("babel", options={"ngerman"})
+MICROTYPE: Package = DefinePackage("microtype")
+CSQUOTES: Package = DefinePackage("csquotes")
+BOOKTABS: Package = DefinePackage("booktabs")
+ARRAY: Package = DefinePackage("array")
+TABULARX: Package = DefinePackage("tabularx")
+LONGTABLE: Package = DefinePackage("longtable")
+MULTIROW: Package = DefinePackage("multirow")
+CAPTION: Package = DefinePackage("caption")
+SUBCAPTION: Package = DefinePackage("subcaption")
+FLOAT: Package = DefinePackage("float")
+FANCYHDR: Package = DefinePackage("fancyhdr")
+TITLESEC: Package = DefinePackage("titlesec")
+ENUMITEM: Package = DefinePackage("enumitem")
+LISTINGS: Package = DefinePackage("listings")
+MINTED: Package = DefinePackage("minted")
+TIKZ: Package = DefinePackage("tikz")
+PGFPLOTS: Package = DefinePackage("pgfplots")
+TCOLORBOX: Package = DefinePackage("tcolorbox")
+SIUNITX: Package = DefinePackage("siunitx")
+GLOSSARIES: Package = DefinePackage("glossaries", options={"acronym"})
+SVG: Package = DefinePackage("svg")
+SOUL: Package = DefinePackage("soul")
+ULEM: Package = DefinePackage("ulem")
+WRAPFIG: Package = DefinePackage("wrapfig")
+PARSKIP: Package = DefinePackage("parskip")
+SETSPACE: Package = DefinePackage("setspace")
+TIKZ_LIB_ARROWS: Package = DefinePackage("tikz-arrows", after={TIKZ})
+PGF: Package = DefinePackage("pgf")
+LIPSUM: Package = DefinePackage("lipsum")
+BLINDTEXT: Package = DefinePackage("blindtext")
+TODONOTES: Package = DefinePackage("todonotes")
+COMMENT: Package = DefinePackage("comment")
+IFTHEN: Package = DefinePackage("ifthen")
+ETOOLBOX: Package = DefinePackage("etoolbox")
+XPARSE: Package = DefinePackage("xparse")
+CALC: Package = DefinePackage("calc")
+MAKEIDX: Package = DefinePackage("makeidx")
+APPENDIX: Package = DefinePackage("appendix")
+TITLING: Package = DefinePackage("titling")
+LASTPAGE: Package = DefinePackage("lastpage")
+CLEVEREF: Package = DefinePackage("cleveref", after={HYPERREF, AMSMATH})
+VARIOREF: Package = DefinePackage("varioref")
+FRAMED: Package = DefinePackage("framed")
+# framemethod=tikz must be set at load time (preamble) for mdframed's rounded
+# backgrounds; it cannot be switched on per-environment mid-document.
+MDFRAMED: Package = DefinePackage("mdframed", options={("framemethod", "tikz")})
+PDFPAGES: Package = DefinePackage("pdfpages")
+FONTSPEC: Package = DefinePackage("fontspec")
+UNICODE_MATH: Package = DefinePackage("unicode-math")
+BIBLATEX: Package = DefinePackage("biblatex")
+TOCLOFT: Package = DefinePackage("tocloft")
+NOTOCCITE: Package = DefinePackage("notoccite")
+NATBIB: Package = DefinePackage("natbib")
+ACRONYM: Package = DefinePackage("acronym")
+NOMENCL: Package = DefinePackage("nomencl")
+ALGORITHM2E: Package = DefinePackage("algorithm2e")
+ALGORITHMS: Package = DefinePackage("algorithms")
+ALGORITHMICX: Package = DefinePackage("algorithmicx")
+LSTLISTING: Package = LISTINGS  # alias
+TBL_THEOREM: Package = DefinePackage("amsthm", after={AMSMATH})
+AMSTHM: Package = TBL_THEOREM
+THMTOOLS: Package = DefinePackage("thmtools")
+ENUMERATE: Package = DefinePackage("enumerate")
+PARALIST: Package = DefinePackage("paralist")
+TYPEAREA: Package = DefinePackage("typearea")
+SCRLAYER_SCRPAGE: Package = DefinePackage("scrlayer-scrpage")
+KOMA_SCRIPT: Package = DefinePackage("koma-script")
+ADJUSTBOX: Package = DefinePackage("adjustbox")
+RAGGED2E: Package = DefinePackage("ragged2e")
+NEEDSPACE: Package = DefinePackage("needspace")
+PLACEINS: Package = DefinePackage("placeins")
+FOOTMISC: Package = DefinePackage("footmisc")
+ROTATING: Package = DefinePackage("rotating")
+CHANGEPAGE: Package = DefinePackage("changepage")
+EVERYPAGE: Package = DefinePackage("everypage")
+EVERYSHI: Package = DefinePackage("everyshi")
+TIKZ_LIB_POSITIONING: Package = DefinePackage("tikz-positioning", after={TIKZ})
+TIKZPAGENODES: Package = DefinePackage("tikzpagenodes", after={TIKZ})
+PGFFOR: Package = DefinePackage("pgffor")
+ARRAYJOBX: Package = DefinePackage("arrayjobx")
+BOPHOOK: Package = DefinePackage("bophook")
+ENVIRON: Package = DefinePackage("environ")
+EXPL3: Package = DefinePackage("expl3")
+L3KEYS2E: Package = DefinePackage("l3keys2e")
+PDFTEXCMDS: Package = DefinePackage("pdftexcmds")
+XFP: Package = DefinePackage("xfp")
+KEYVAL: Package = DefinePackage("keyval")
+PIFONT: Package = DefinePackage("pifont")
+FONTAWESOME: Package = DefinePackage("fontawesome")
+FLOATROW: Package = DefinePackage("floatrow")
+CHNGCNTR: Package = DefinePackage("chngcntr")
+ACCSUPP: Package = DefinePackage("accsupp")
+AFTERPAGE: Package = DefinePackage("afterpage")
+ARYDSHLN: Package = DefinePackage("arydshln")
+LMODERN: Package = DefinePackage("lmodern")
+HYPHENAT: Package = DefinePackage("hyphenat")
+FP: Package = DefinePackage("fp")
+
+
+class Packages(Enum):
+    AMSMATH = AMSMATH
+    AMSSYMB = AMSSYMB
+    AMSFONTS = AMSFONTS
+    MATHTOOLS = MATHTOOLS
+    HYPERREF = HYPERREF
+    URL = URL
+    GRAPHICX = GRAPHICX
+    XCOLOR = XCOLOR
+    GEOMETRY = GEOMETRY
+    FONTENC = FONTENC
+    INPUTENC = INPUTENC
+    BABEL = BABEL
+    MICROTYPE = MICROTYPE
+    CSQUOTES = CSQUOTES
+    BOOKTABS = BOOKTABS
+    ARRAY = ARRAY
+    TABULARX = TABULARX
+    LONGTABLE = LONGTABLE
+    MULTIROW = MULTIROW
+    CAPTION = CAPTION
+    SUBCAPTION = SUBCAPTION
+    FLOAT = FLOAT
+    FANCYHDR = FANCYHDR
+    TITLESEC = TITLESEC
+    ENUMITEM = ENUMITEM
+    LISTINGS = LISTINGS
+    MINTED = MINTED
+    TIKZ = TIKZ
+    PGFPLOTS = PGFPLOTS
+    TCOLORBOX = TCOLORBOX
+    SIUNITX = SIUNITX
+    BIBLATEX = BIBLATEX
+    GLOSSARIES = GLOSSARIES
+    SVG = SVG
+    SOUL = SOUL
+    ULEM = ULEM
+    WRAPFIG = WRAPFIG
+    PARSKIP = PARSKIP
+    SETSPACE = SETSPACE
+    PGF = PGF
+    LIPSUM = LIPSUM
+    BLINDTEXT = BLINDTEXT
+    TODONOTES = TODONOTES
+    COMMENT = COMMENT
+    IFTHEN = IFTHEN
+    ETOOLBOX = ETOOLBOX
+    XPARSE = XPARSE
+    CALC = CALC
+    MAKEIDX = MAKEIDX
+    APPENDIX = APPENDIX
+    TITLING = TITLING
+    LASTPAGE = LASTPAGE
+    CLEVEREF = CLEVEREF
+    VARIOREF = VARIOREF
+    FRAMED = FRAMED
+    MDFRAMED = MDFRAMED
+    PDFPAGES = PDFPAGES
+    FONTSPEC = FONTSPEC
+    UNICODE_MATH = UNICODE_MATH
+    TOCLOFT = TOCLOFT
+    NOTOCCITE = NOTOCCITE
+    NATBIB = NATBIB
+    ACRONYM = ACRONYM
+    NOMENCL = NOMENCL
+    ALGORITHM2E = ALGORITHM2E
+    ALGORITHMS = ALGORITHMS
+    ALGORITHMICX = ALGORITHMICX
+    AMSTHM = AMSTHM
+    THMTOOLS = THMTOOLS
+    ENUMERATE = ENUMERATE
+    PARALIST = PARALIST
+    TYPEAREA = TYPEAREA
+    SCRLAYER_SCRPAGE = SCRLAYER_SCRPAGE
+    KOMA_SCRIPT = KOMA_SCRIPT
+    ADJUSTBOX = ADJUSTBOX
+    RAGGED2E = RAGGED2E
+    NEEDSPACE = NEEDSPACE
+    PLACEINS = PLACEINS
+    FOOTMISC = FOOTMISC
+    ROTATING = ROTATING
+    CHANGEPAGE = CHANGEPAGE
+    EVERYPAGE = EVERYPAGE
+    EVERYSHI = EVERYSHI
+    TIKZPAGENODES = TIKZPAGENODES
+    PGFFOR = PGFFOR
+    ARRAYJOBX = ARRAYJOBX
+    BOPHOOK = BOPHOOK
+    ENVIRON = ENVIRON
+    EXPL3 = EXPL3
+    L3KEYS2E = L3KEYS2E
+    PDFTEXCMDS = PDFTEXCMDS
+    XFP = XFP
+    KEYVAL = KEYVAL
+    PIFONT = PIFONT
+    FONTAWESOME = FONTAWESOME
+    FLOATROW = FLOATROW
+    CHNGCNTR = CHNGCNTR
+    ACCSUPP = ACCSUPP
+    AFTERPAGE = AFTERPAGE
+    ARYDSHLN = ARYDSHLN
+    LMODERN = LMODERN
+    HYPHENAT = HYPHENAT
+    FP = FP

pytex/registry.py

@@ -0,0 +1,49 @@
+from collections.abc import Callable
+from logging import Logger
+from typing import ClassVar, Self
+
+from pytex.interface.tex import TeX
+
+__all__ = ["Registry"]
+
+type TeXFactory = Callable[..., TeX]
+
+type RegistryType = type[TeX] | TeXFactory
+
+
+class Registry:
+    types: ClassVar[dict[str, RegistryType]] = {}
+    instance: ClassVar[Self | None] = None
+
+    def __new__(cls) -> Self:
+        if cls.instance is None:
+            cls.instance = super().__new__(cls)
+
+        return cls.instance
+
+    @classmethod
+    def add[O: RegistryType](cls, obj: O) -> O:
+        if (key := obj.__name__) in cls.types:
+            Logger(cls.__name__).warning(
+                f"Duplicate key in registry (overwritten): {key}"
+            )
+
+        cls.types[key] = obj
+
+        return obj
+
+    @classmethod
+    def get(cls, name: str) -> RegistryType:
+        return cls.types[name]
+
+    @classmethod
+    def has(cls, name: str) -> bool:
+        return name in cls.types
+
+    @classmethod
+    def names(cls) -> frozenset[str]:
+        return frozenset(cls.types.keys())
+
+    @classmethod
+    def namespace(cls) -> dict[str, RegistryType]:
+        return dict(cls.types)

pytex_builder/__init__.py

@@ -0,0 +1,8 @@
+"""Build tooling for PyTeX: render ``.py``/``.tex`` sources and compile PDFs.
+
+Exposes the ``pytex`` console script via :func:`pytex_builder.build.main`.
+"""
+
+from .build import main
+
+__all__ = ["main"]

pytex_builder/build.py

@@ -0,0 +1,175 @@
+"""``pytex`` command-line entry point.
+
+Renders a ``.tex`` or ``.py`` input to a LaTeX file and, optionally, compiles
+it with tectonic - running ``makeindex`` between passes so ``glossaries`` and
+acronyms resolve.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, cast
+
+from .console import Console
+from .render import get_tex_node
+from .tectonic import BuildError, ensure_tectonic, run_makeindex, run_tectonic
+
+__all__ = ["Config", "main"]
+
+if TYPE_CHECKING:
+    from pytex_hsrtreport.document import HSRTReport
+
+MAX_PASSES = 3
+
+
+@dataclass(frozen=True)
+class Config:
+    input: Path
+    output: Path
+    build: bool
+    build_dir: Path
+    shell_escape: bool
+
+
+def _default_output(inp: Path, build_dir: Path) -> Path:
+    """Default rendered-output path inside the build directory.
+
+    The driver extension is dropped, plus a trailing ``.tex`` if the source is
+    named after its target (the ``name.tex.py`` convention). The result lives in
+    ``build_dir`` so the ``.out.tex`` and its inline assets (fonts, logos,
+    images) stay out of the source tree:
+
+    * ``example.tex.py`` -> ``<build_dir>/example.out.tex``
+    * ``report.py``      -> ``<build_dir>/report.out.tex``
+    * ``paper.tex``      -> ``<build_dir>/paper.out.tex``
+    """
+    base = inp
+    if base.suffix.lower() in {".py", ".tex"}:
+        base = base.with_suffix("")
+    if base.suffix.lower() == ".tex":
+        base = base.with_suffix("")
+    return build_dir / f"{base.name}.out.tex"
+
+
+def _parse_args(argv: list[str]) -> Config:
+    parser = argparse.ArgumentParser(
+        prog="pytex",
+        description="Render PyTeX (.py) or LaTeX (.tex) sources and build PDFs.",
+    )
+    _ = parser.add_argument(
+        "input",
+        type=Path,
+        help=(
+            "input file: a .tex file (wrapped in IncludeTeX) or a .py file"
+            + " exposing a '__pytex__' TeX node"
+        ),
+    )
+    _ = parser.add_argument(
+        "-o",
+        "--output",
+        type=Path,
+        default=None,
+        help="rendered .tex output path (default: <build-dir>/<input>.out.tex)",
+    )
+    _ = parser.add_argument(
+        "-b",
+        "--build",
+        action="store_true",
+        help="compile the rendered .tex to PDF with tectonic",
+    )
+    _ = parser.add_argument(
+        "--build-dir",
+        type=Path,
+        default=Path("build"),
+        help="directory for build artifacts and tectonic output (default: build)",
+    )
+    _ = parser.add_argument(
+        "--no-shell-escape",
+        dest="shell_escape",
+        action="store_false",
+        help="disable shell-escape (on by default; needed for inline images)",
+    )
+    ns = parser.parse_args(argv)
+    inp = cast("Path", ns.input)
+    build_dir = cast("Path", ns.build_dir)
+    return Config(
+        input=inp,
+        output=cast("Path | None", ns.output) or _default_output(inp, build_dir),
+        build=cast("bool", ns.build),
+        build_dir=build_dir,
+        shell_escape=cast("bool", ns.shell_escape),
+    )
+
+
+def _run(cfg: Config, console: Console) -> None:
+    if not cfg.input.exists():
+        raise BuildError(f"input file does not exist: {cfg.input}")
+
+    output = cfg.output
+    build_dir = cfg.build_dir
+
+    console.step(f"Rendering {cfg.input.name}")
+    tex_node = get_tex_node(cfg.input)
+    source = tex_node.rendered
+    output.parent.mkdir(parents=True, exist_ok=True)
+    _ = output.write_text(source)
+    console.detail(f"wrote {output} ({len(source):,} bytes)")
+
+    if not cfg.build:
+        return
+
+    build_dir.mkdir(parents=True, exist_ok=True)
+
+    # Materialise inline assets (fonts, logos, images) alongside the .tex (in
+    # the build dir by default) so the TeX engine can locate them by the
+    # relative paths in the preamble.
+    if hasattr(tex_node, "write_inline_fonts"):
+        cast("HSRTReport", tex_node).write_inline_fonts(str(output.parent))
+    if hasattr(tex_node, "write_inline_logos"):
+        cast("HSRTReport", tex_node).write_inline_logos(str(output.parent))
+    if hasattr(tex_node, "write_inline_images"):
+        cast("HSRTReport", tex_node).write_inline_images(str(output.parent))
+
+    binary = ensure_tectonic(console)
+
+    job = output.stem
+    for pass_no in range(1, MAX_PASSES + 1):
+        console.step(f"Compiling (pass {pass_no})")
+        run_tectonic(
+            binary, output, build_dir, shell_escape=cfg.shell_escape, console=console
+        )
+        # Resolve glossaries after the first pass; rerun only if it changed.
+        if pass_no == 1 and run_makeindex(job, build_dir, console=console):
+            continue
+        break
+
+    pdf = build_dir / f"{job}.pdf"
+    if pdf.exists():
+        console.success(f"Built {pdf}")
+    else:
+        console.warn("tectonic reported success but produced no PDF")
+        console.hint(f"check the log in {build_dir}")
+
+
+def main(argv: list[str] | None = None) -> int:
+    cfg = _parse_args(sys.argv[1:] if argv is None else argv)
+    console = Console()
+    try:
+        _run(cfg, console)
+    except BuildError as exc:
+        head, *rest = str(exc).splitlines() or [""]
+        console.error(head)
+        for line in rest:
+            console.detail(line)
+        return 1
+    except KeyboardInterrupt:
+        console.error("interrupted")
+        return 130
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pytex_builder/console.py

@@ -0,0 +1,77 @@
+"""Minimal, tectonic-style terminal output.
+
+No emojis, no progress bars - just level-tagged lines with restrained color.
+Color is disabled automatically when stderr is not a TTY or ``NO_COLOR`` is set.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import Final, TextIO
+
+__all__ = ["Console"]
+
+
+def _color_enabled(stream: TextIO) -> bool:
+    if os.environ.get("NO_COLOR"):
+        return False
+    if os.environ.get("PYTEX_FORCE_COLOR"):
+        return True
+    return bool(getattr(stream, "isatty", lambda: False)())
+
+
+class _Style:
+    RESET: Final = "\033[0m"
+    BOLD: Final = "\033[1m"
+    DIM: Final = "\033[2m"
+    RED: Final = "\033[31m"
+    GREEN: Final = "\033[32m"
+    YELLOW: Final = "\033[33m"
+    BLUE: Final = "\033[34m"
+    CYAN: Final = "\033[36m"
+
+
+class Console:
+    """Writes level-tagged status lines to ``stderr``."""
+
+    def __init__(self, stream: TextIO | None = None) -> None:
+        self.stream: TextIO = stream or sys.stderr
+        self.color: bool = _color_enabled(self.stream)
+
+    def _paint(self, text: str, *codes: str) -> str:
+        if not self.color or not codes:
+            return text
+        return f"{''.join(codes)}{text}{_Style.RESET}"
+
+    def _emit(self, tag: str, message: str, *codes: str) -> None:
+        prefix = self._paint(tag, _Style.BOLD, *codes)
+        self.stream.write(f"{prefix} {message}\n")
+        self.stream.flush()
+
+    def step(self, message: str) -> None:
+        """A high-level pipeline stage (e.g. 'Rendering', 'Compiling')."""
+        self._emit("==>", message, _Style.GREEN)
+
+    def note(self, message: str) -> None:
+        self._emit("note:", message, _Style.CYAN)
+
+    def warn(self, message: str) -> None:
+        self._emit("warning:", message, _Style.YELLOW)
+
+    def error(self, message: str) -> None:
+        self._emit("error:", message, _Style.RED)
+
+    def hint(self, message: str) -> None:
+        """A follow-up suggestion attached to a preceding warning/error."""
+        bullet = self._paint("    cause:", _Style.DIM)
+        self.stream.write(f"{bullet} {message}\n")
+        self.stream.flush()
+
+    def detail(self, message: str) -> None:
+        """An indented, dimmed continuation line."""
+        self.stream.write(f"{self._paint('    ' + message, _Style.DIM)}\n")
+        self.stream.flush()
+
+    def success(self, message: str) -> None:
+        self._emit("==>", message, _Style.GREEN)

pytex_builder/render.py

@@ -0,0 +1,82 @@
+"""Turn an input file into a rendered LaTeX string.
+
+Two input kinds are supported:
+
+* ``.tex`` - wrapped in :func:`pytex.model.include.IncludeTeX` so ``\\iffalse``
+  ``pytex(...)`` replacements are evaluated, then rendered.
+* ``.py``  - imported as a module; its module-level ``__pytex__`` value is
+  rendered. It must implement the :class:`pytex.interface.tex.TeX` protocol.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from typing import TYPE_CHECKING, cast
+
+from pytex.interface.tex import TeX
+from pytex.model.include import IncludeTeX
+
+from .tectonic import BuildError
+
+__all__ = ["get_tex_node", "render_input"]
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+PYTEX_VAR = "__pytex__"
+
+
+def _render_python(path: Path) -> TeX:
+    spec = importlib.util.spec_from_file_location(path.stem, path)
+    if spec is None or spec.loader is None:
+        raise BuildError(f"could not load Python module from {path}")
+
+    module = importlib.util.module_from_spec(spec)
+    # Let the module import siblings relative to its own directory.
+    sys.path.insert(0, str(path.resolve().parent))
+    try:
+        spec.loader.exec_module(module)
+    except Exception as exc:
+        raise BuildError(f"error while importing {path.name}: {exc}") from exc
+    finally:
+        sys.path.pop(0)
+
+    if not hasattr(module, PYTEX_VAR):
+        raise BuildError(f"{path.name} defines no '{PYTEX_VAR}' variable to render")
+
+    value = cast("object", getattr(module, PYTEX_VAR))
+    if not isinstance(value, TeX):
+        raise BuildError(
+            f"'{PYTEX_VAR}' in {path.name} is {type(value).__name__};"
+            + " expected a TeX node (with a '.rendered' property)"
+        )
+    return value
+
+
+def _render_markdown(path: Path) -> TeX:
+    # Imported lazily so plain .tex/.py builds need neither marko nor hsrt.
+    from pytex.model.document import Document
+    from pytex_markdown import IncludeMarkdown
+
+    return Document(IncludeMarkdown(path))
+
+
+def get_tex_node(path: Path) -> TeX:
+    """Load ``path`` and return the TeX node without rendering."""
+    suffix = path.suffix.lower()
+    if suffix == ".tex":
+        return IncludeTeX(path)
+    if suffix == ".py":
+        return _render_python(path)
+    if suffix in (".md", ".markdown"):
+        return _render_markdown(path)
+    raise BuildError(
+        f"unsupported input type '{suffix or path.name}'; "
+        + "expected .tex, .py or .md"
+    )
+
+
+def render_input(path: Path) -> str:
+    """Render ``path`` to a LaTeX source string."""
+    return get_tex_node(path).rendered