pytex-preprocessor 0.1.0__py3-none-any.whl

pytex_hsrtreport/document.py

@@ -0,0 +1,307 @@
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Final, override
+
+from pytex.commands.colors import Definecolor
+from pytex.commands.fontspec import Setmainfont, Setsansfont
+from pytex.commands.geometry import Geometry
+from pytex.helpers.coerce import coerce_tex
+from pytex.interface.package import PackageProtocol
+from pytex.interface.tex import TeX
+from pytex.model.color import Color, collect_colors
+from pytex.model.concat import Concat
+from pytex.model.document_class import DocumentClass
+from pytex.model.empty import Empty
+from pytex.model.environment import Environment
+from pytex.model.raw import Raw
+from pytex.packages import (
+    ARRAY,
+    BABEL,
+    BIBLATEX,
+    CLEVEREF,
+    CSQUOTES,
+    ETOOLBOX,
+    FONTAWESOME,
+    GEOMETRY,
+    GLOSSARIES,
+    GRAPHICX,
+    HYPERREF,
+    LISTINGS,
+    LMODERN,
+    LONGTABLE,
+    MDFRAMED,
+    NEEDSPACE,
+    PGF,
+    PGFFOR,
+    RAGGED2E,
+    SCRLAYER_SCRPAGE,
+    SETSPACE,
+    TIKZ,
+    XCOLOR,
+)
+from pytex.registry import Registry
+from pytex_koma.document import KomaDocument
+
+from .cleveref_names import GermanCrefNames
+from .colors import HSRTColors
+from .fonts import HSRTFontSetup
+from .glossary import AcrShortcut, HSRTGlossarySetup
+from .hyperref_config import (
+    HSRT_CITE_COLOR,
+    HSRT_LINK_COLOR,
+    HSRT_URL_COLOR,
+    HSRTHyperref,
+)
+from .listings import HSRTListingStyles
+from .logos import DefaultLogos, footer_logo_hook
+from .pagesetup import HSRTPageSetup
+from .titlepage import TitlePage, TitlePageDataLine
+from .variants import Variant, default_logo_names
+
+__all__ = ["HSRTReport"]
+
+BASE_PACKAGES: Final[frozenset[PackageProtocol]] = frozenset(
+    {
+        LMODERN,
+        GEOMETRY,
+        GRAPHICX,
+        XCOLOR,
+        TIKZ,
+        PGF,
+        PGFFOR,
+        LISTINGS,
+        HYPERREF,
+        CLEVEREF,
+        BIBLATEX,
+        CSQUOTES,
+        GLOSSARIES,
+        MDFRAMED,
+        FONTAWESOME,
+        SCRLAYER_SCRPAGE,
+        ETOOLBOX,
+        SETSPACE,
+        RAGGED2E,
+        ARRAY,
+        LONGTABLE,
+        NEEDSPACE,
+        BABEL,
+    }
+)
+
+DEFAULT_GEOMETRY: Final[dict[str, str]] = {
+    "a4paper": "",
+    "top": "2cm",
+    "bottom": "2cm",
+    "left": "2cm",
+    "right": "2cm",
+}
+
+# Back-matter print commands. \printglossary/\printbibliography emit their own
+# \chapter* heading (and page break), so no manual \clearpage precedes them.
+BACKMATTER_HEADER = r"\newpage\appendix\backmatter\HSRTBackMattertrue"
+GLOSSARY_PRINT = r"\renewcommand*{\entryname}{Wort}\printglossary"
+ACRONYM_PRINT = r"\renewcommand*{\entryname}{Abkürzung}\printglossary[type=\acronymtype,title=Abkürzungen]"  # noqa: E501
+BIBLIOGRAPHY_PRINT = r"\clearpage\chapter*{Literaturverzeichnis}\label{chap:bibliography}\printbibliography[heading=none,title={}]"  # noqa: E501
+
+
+def _emit(dest: Path, data: bytes) -> str:
+    """Write `data` to `dest` (creating parent dirs) and return its posix path."""
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    dest.write_bytes(data)
+    return dest.as_posix()
+
+
+@Registry.add
+@dataclass
+class HSRTReport(KomaDocument):
+    """HSRT report: scrbook + KomaDocument + auto preamble + colour-collector."""
+
+    document_class: str = "scrbook"
+
+    variant: Variant = Variant.INF
+    show_toc: bool = True
+    show_titlepage: bool = True
+    show_glossary: bool = False
+    show_acronyms: bool = False
+    show_bibliography: bool = False
+    show_footer_logos: bool = False
+
+    title: TeX | str | None = None
+    author: TeX | str | None = None
+    abstract: TeX | str | None = None
+    keywords: TeX | str | None = None
+    data_lines: tuple[TitlePageDataLine, ...] = ()
+
+    inline_logos: bool = True
+    inline_fonts: bool = True
+    main_font: str | None = None
+    sans_font: str | None = None
+    geometry_options: dict[str, str] = field(
+        default_factory=lambda: dict(DEFAULT_GEOMETRY)
+    )
+    user_preamble: TeX | str = Empty
+
+    def __post_init__(self) -> None:
+        super().__post_init__()
+        if self.document_class != "scrbook":
+            raise ValueError(
+                "HSRTReport requires document_class='scrbook', "
+                + f"got {self.document_class!r}"
+            )
+        self.extra_packages: frozenset[PackageProtocol] = (
+            frozenset(self.extra_packages) | BASE_PACKAGES
+        )
+        self.preamble: TeX | str = self._build_preamble()
+
+    def discovered_colors(self) -> tuple[Color, ...]:
+        """Walk body + preamble, return every `Color` instance needing `\\definecolor`.
+
+        Also includes HSRT hyperref colours (stored as Python data inside the
+        hypersetup options dict, so unreachable via the tree walk).
+        """
+        seen: dict[str, Color] = {}
+        for c in (HSRT_CITE_COLOR, HSRT_LINK_COLOR, HSRT_URL_COLOR):
+            seen.setdefault(c.name, c)
+        for root in (self.body, self.user_preamble):
+            for color in collect_colors(coerce_tex(root)):
+                seen.setdefault(color.name, color)
+        return tuple(seen.values())
+
+    def _color_definitions(self) -> TeX:
+        return Concat(
+            *(
+                Definecolor(c.name, c.spec.model, c.spec.value)
+                for c in self.discovered_colors()
+                if c.spec is not None
+            )
+        )
+
+    def _build_preamble(self) -> TeX:
+        return Concat(*self._preamble_parts())
+
+    def _preamble_parts(self) -> Iterator[TeX | str]:
+        yield Raw(r"\KOMAoptions{open=any,twoside=false}")
+        yield Geometry(self.geometry_options)
+        yield HSRTColors()
+        yield self._color_definitions()
+        yield HSRTHyperref()
+        yield GermanCrefNames()
+        if self.show_glossary or self.show_acronyms:
+            yield HSRTGlossarySetup()
+        yield HSRTListingStyles()
+        yield AcrShortcut()
+        # Page setup first — provides \providecommand{\blenderfont} fallback
+        # that HSRTFontSetup's \renewcommand{\blenderfont} requires.
+        yield HSRTPageSetup()
+        # The skyline is drawn on every page; footer logos only when requested.
+        logo_names = default_logo_names(self.variant) if self.show_footer_logos else ()
+        yield Raw(footer_logo_hook(logo_names), allow_replacements=False)
+        if self.inline_fonts:
+            yield HSRTFontSetup()
+        if self.main_font is not None:
+            yield Setmainfont(self.main_font)
+        if self.sans_font is not None:
+            yield Setsansfont(self.sans_font)
+        # \title / \author for running headers
+        if self.title is not None:
+            yield Raw(f"\\title{{{coerce_tex(self.title).rendered}}}")
+        if self.author is not None:
+            yield Raw(f"\\author{{{coerce_tex(self.author).rendered}}}")
+        if self.user_preamble is not Empty:
+            yield self.user_preamble
+
+    def _build_full_body(self) -> TeX:
+        """Wrap user body with front/main/back matter, ToC, glossary, bibliography."""
+        return Concat(*self._body_parts())
+
+    def _body_parts(self) -> Iterator[TeX | str]:
+        # -- Front matter --
+        yield Raw(r"\frontmatter")
+        if self.show_titlepage and self.title is not None:
+            yield TitlePage(
+                title=self.title,
+                abstract=self.abstract or "",
+                keywords=self.keywords or "",
+                data_lines=self.data_lines,
+                logo_names=default_logo_names(self.variant),
+            )
+        if self.show_toc:
+            yield Raw(r"\newpage\tableofcontents")
+
+        # -- Main matter --
+        yield Raw(r"\mainmatter")
+        yield coerce_tex(self.body)
+
+        # -- Back matter --
+        # The header is only emitted when there is actual back-matter content:
+        # \backmatter calls hyperref's \bookmarksetup which fires \@ in vertical
+        # mode and crashes, so skip it entirely when there is nothing to show.
+        if self.show_glossary or self.show_acronyms or self.show_bibliography:
+            yield Raw(BACKMATTER_HEADER)
+        if self.show_glossary:
+            yield Raw(GLOSSARY_PRINT)
+        if self.show_acronyms:
+            yield Raw(ACRONYM_PRINT)
+        if self.show_bibliography:
+            yield Raw(BIBLIOGRAPHY_PRINT)
+
+    def write_inline_fonts(self, target_dir: str = ".") -> tuple[str, ...]:
+        """Write bundled font TTF files to ``<target_dir>/fonts/`` for compilation.
+
+        Call this before the TeX run so fontspec can resolve the font paths
+        embedded in the preamble by `HSRTFontSetup`.
+        """
+        if not self.inline_fonts:
+            return ()
+        from .fonts import FONT_OUTPUT_DIR, all_font_paths, rel
+
+        base = Path(target_dir)
+        return tuple(
+            _emit(base / FONT_OUTPUT_DIR / rel(font_path), font_path.read_bytes())
+            for font_path in all_font_paths()
+        )
+
+    def write_inline_logos(self, target_dir: str = ".") -> tuple[str, ...]:
+        """Write the logos used by the tikz overlays to ``<target_dir>/logos/``.
+
+        The titlepage overlay and footer hook reference logos by relative path
+        (``logos/<file>``); this materialises those files next to the .tex so
+        tectonic can read them without tripping its absolute-path restrictions.
+        SVG sources are converted to PDF via `IncludeImage`.
+        """
+        from pytex.model.image import IncludeImage
+
+        from .logos import LOGO_OUTPUT_DIR, logo_output_name, logo_path
+
+        # Titlepage overlay + footer hook use the variant defaults; the footer
+        # skyline is emitted on every page regardless of show_footer_logos.
+        names = sorted(set(default_logo_names(self.variant)) | {"Skyline"})
+        base = Path(target_dir)
+        return tuple(
+            # IncludeImage.read_bytes converts svg -> pdf on the fly.
+            _emit(
+                base / LOGO_OUTPUT_DIR / logo_output_name(name),
+                IncludeImage(path=logo_path(name), inline_base64=False).read_bytes(),
+            )
+            for name in names
+        )
+
+    def default_logos(self) -> TeX:
+        return DefaultLogos(self.variant, inline_base64=self.inline_logos)
+
+    @property
+    @override
+    def rendered(self) -> str:
+        return Concat(
+            DocumentClass(self.document_class, self.document_class_options),
+            # hyperfootnotes is only honoured as a hyperref load option, so it
+            # must be queued before \usepackage{hyperref}. The HSRT footnote
+            # setup never places hyperref's Hfootnote destination, so leaving
+            # footnote-mark links enabled produces dangling links.
+            Raw(r"\PassOptionsToPackage{hyperfootnotes=false}{hyperref}"),
+            *self.ordered_packages(),
+            self.inline_image_block,
+            self.preamble,
+            Environment("document", self._build_full_body()),
+        ).rendered

pytex_hsrtreport/fonts.py

@@ -0,0 +1,66 @@
+from importlib.resources import files
+from pathlib import Path
+from typing import Final
+
+from pytex.commands.fontspec import Newfontfamily, Setmainfont, Setsansfont
+from pytex.interface.tex import TeX
+from pytex.model.concat import Concat
+from pytex.model.raw import Raw
+from pytex.registry import Registry
+
+FONT_DIR: Final[Path] = Path(str(files("pytex_hsrtreport").joinpath("assets/fonts")))
+
+# Output dir for the bundled TTFs, relative to the .tex file. `HSRTReport`'s
+# `write_inline_fonts` copies the real font files here; fontspec's Path= option
+# (see `_font_opts`) loads them from <this>/<subfamily>/.
+FONT_OUTPUT_DIR: Final[str] = "fonts"
+
+
+def all_font_paths() -> tuple[Path, ...]:
+    """Return all bundled TTF paths, sorted for reproducible output."""
+    return tuple(sorted(FONT_DIR.rglob("*.ttf")))
+
+
+def rel(font_path: Path) -> str:
+    """Path of a font file relative to `FONT_DIR`."""
+    return font_path.relative_to(FONT_DIR).as_posix()
+
+
+def _font_opts(subfamily: str, upright: str, italic: str) -> dict[str, str]:
+    return {
+        "Path": f"{FONT_OUTPUT_DIR}/{subfamily}/",
+        "Extension": ".ttf",
+        "UprightFont": upright,
+        "BoldFont": "*-Bold",
+        "ItalicFont": italic,
+        "BoldItalicFont": "*-BoldItalic",
+    }
+
+
+@Registry.add
+def HSRTFontSetup() -> TeX:
+    """fontspec setup for bundled DIN (main) and Blender (sans) fonts.
+
+    Mirrors ``Config/Fonts.tex`` from the original template.  The font files
+    are expected at ``fonts/DIN/`` and ``fonts/Blender/`` relative to the
+    output ``.tex`` file, which is where ``HSRTReport.write_inline_fonts``
+    copies the bundled TTFs before the TeX run.
+    """
+    blender_opts = _font_opts("Blender", "*-Medium", "*-MediumItalic")
+    din_opts = _font_opts("DIN", "*-Regular", "*-Italic")
+    return Concat(
+        Newfontfamily("\\BlenderFont", "Blender", options=blender_opts),
+        Newfontfamily("\\DINFont", "DIN", options=din_opts),
+        Raw(r"\renewcommand{\blenderfont}{\BlenderFont}"),
+        Raw(r"\renewcommand{\dinfont}{\DINFont}"),
+        Setsansfont("Blender", options=blender_opts),
+        Setmainfont("DIN", options=din_opts),
+    )
+
+
+__all__ = [
+    "FONT_OUTPUT_DIR",
+    "HSRTFontSetup",
+    "all_font_paths",
+    "rel",
+]

pytex_hsrtreport/glossary.py

@@ -0,0 +1,61 @@
+from pytex.commands.glossaries import (
+    Glsenablehyper,
+    Makeglossaries,
+    Setglossarystyle,
+)
+from pytex.interface.tex import TeX
+from pytex.model.concat import Concat
+from pytex.model.raw import Raw
+from pytex.registry import Registry
+
+__all__ = ["AcrShortcut", "HSRTGlossarySetup"]
+
+# Custom L/C/R column types used by the manualfixedwidth glossary style. Each
+# fixes a horizontal alignment while still allowing manual \newline breaks.
+COLUMN_TYPES = (
+    r"\newcolumntype{L}[1]{>{\raggedright\let\newline\\\arraybackslash\hspace{0pt}}p{#1}}"
+    + r"\newcolumntype{C}[1]{>{\centering\let\newline\\\arraybackslash\hspace{0pt}}p{#1}}"
+    + r"\newcolumntype{R}[1]{>{\raggedleft\let\newline\\\arraybackslash\hspace{0pt}}p{#1}}"
+)
+
+# A three-column glossary style with fixed widths (30%/58%/10% of \textwidth).
+GLOSSARY_STYLE = (
+    r"\newglossarystyle{manualfixedwidth}{"
+    + r"\setglossarystyle{long3colheader}"
+    + r"\renewenvironment{theglossary}{\begin{longtable}{@{}"
+    + r"L{\dimexpr0.30\textwidth-\tabcolsep\relax}"
+    + r" p{\dimexpr0.58\textwidth-\tabcolsep\relax}"
+    + r" L{\dimexpr0.10\textwidth-\tabcolsep\relax}@{}}}{\end{longtable}}"
+    + r"\renewcommand*{\glsgroupskip}{}"
+    + r"\renewcommand{\arraystretch}{1.1}}"
+)
+
+# German column/section labels for the glossary and acronym lists.
+GLOSSARY_LABELS = (
+    r"\renewcommand*{\entryname}{Wort/Abkürzung}"
+    + r"\renewcommand*{\descriptionname}{Bedeutung}"
+    + r"\renewcommand*{\pagelistname}{Seite(n)}"
+    + r"\renewcommand{\acronymname}{Abkürzungsverzeichnis}"
+)
+
+
+@Registry.add
+def HSRTGlossarySetup() -> TeX:
+    """Standard HSRT glossary setup.
+
+    makeglossaries, manualfixedwidth style, German labels.
+    """
+    return Concat(
+        Makeglossaries(),
+        Raw(COLUMN_TYPES),
+        Raw(GLOSSARY_STYLE),
+        Setglossarystyle("manualfixedwidth"),
+        Glsenablehyper(),
+        Raw(GLOSSARY_LABELS),
+    )
+
+
+@Registry.add
+def AcrShortcut() -> TeX:
+    """Shortcut: `\\acr` aliases `\\acrshort`."""
+    return Raw(r"\newcommand{\acr}{\acrshort}")

pytex_hsrtreport/hyperref_config.py

@@ -0,0 +1,49 @@
+from typing import Final
+
+from pytex.interface.tex import TeX
+from pytex.model.color import Color
+from pytex.model.control_sequence import ControlSequence, Parameter
+from pytex.model.raw import Raw
+from pytex.registry import Registry
+
+__all__ = ["HSRTHyperref"]
+
+type HyperOption = bool | int | str | TeX
+
+HSRT_CITE_COLOR: Final[Color] = Color.rgb(0.286, 0.427, 0.537, name="hsrtcite")
+HSRT_LINK_COLOR: Final[Color] = Color.rgb(0.161, 0.310, 0.427, name="hsrtlink")
+HSRT_URL_COLOR: Final[Color] = Color.rgb(0.071, 0.212, 0.322, name="hsrturl")
+
+
+HSRT_HYPER_OPTIONS: Final[dict[str, HyperOption]] = {
+    "pdfpagemode": "UseOutlines",
+    "bookmarksopen": True,
+    "bookmarksopenlevel": 0,
+    # plainpages=false + hypertexnames=true gives roman frontmatter pages their
+    # own named anchors (page.i, ...) so glossary/index \hyperpage links to
+    # those pages resolve instead of dangling against absolute arabic anchors.
+    "plainpages": False,
+    "hypertexnames": True,
+    "colorlinks": True,
+    "citecolor": HSRT_CITE_COLOR,
+    "linkcolor": HSRT_LINK_COLOR,
+    "urlcolor": HSRT_URL_COLOR,
+    "pdfstartview": "FitV",
+    "unicode": True,
+    "breaklinks": True,
+}
+
+
+def _format(value: HyperOption) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, TeX):
+        return value.rendered
+    return str(value)
+
+
+@Registry.add
+def HSRTHyperref() -> TeX:
+    """Hypersetup using `HSRT_HYPER_OPTIONS` (structured Python, not a TeX blob)."""
+    body = ",".join(f"{k}={_format(v)}" for k, v in HSRT_HYPER_OPTIONS.items())
+    return ControlSequence("hypersetup", (Parameter(Raw(body)),))

pytex_hsrtreport/listings.py

@@ -0,0 +1,90 @@
+from typing import Final
+
+from pytex.commands.colors import SelectColor
+from pytex.commands.font import (
+    Bfseries,
+    Footnotesize,
+    Scriptsize,
+    Ttfamily,
+)
+from pytex.commands.listings import Lstdefinestyle, Lstset
+from pytex.interface.tex import TeX
+from pytex.model.concat import Concat
+from pytex.registry import Registry
+
+__all__ = ["HSRTListingStyles", "style_options"]
+
+
+def _font(*parts: TeX) -> TeX:
+    return Concat(*parts)
+
+
+HSRT_LISTING_BASE: Final[dict[str, TeX | str]] = {
+    "basicstyle": _font(Footnotesize(), Ttfamily()),
+    "breaklines": "true",
+    "numbers": "left",
+    "frame": "single",
+    "float": "H",
+}
+
+
+HSRT_LISTING_STYLES: Final[dict[str, dict[str, TeX | str]]] = {
+    "htmlCode": {
+        "language": "html",
+        "basicstyle": _font(Scriptsize(), Ttfamily()),
+        "keywordstyle": _font(SelectColor("blue"), Bfseries(), Ttfamily()),
+        "commentstyle": _font(SelectColor("gray"), Ttfamily()),
+        "escapechar": "|",
+    },
+    "phpCode": {
+        "language": "php",
+        "morekeywords": "{php}",
+        "basicstyle": _font(Footnotesize(), Ttfamily()),
+        "keywordstyle": _font(SelectColor("blue"), Bfseries(), Ttfamily()),
+        "commentstyle": _font(SelectColor("gray"), Ttfamily()),
+        "escapechar": "|",
+    },
+    "jsCode": {
+        "language": "javascript",
+        "basicstyle": _font(Scriptsize(), Ttfamily()),
+        "keywordstyle": _font(SelectColor("blue"), Bfseries(), Ttfamily()),
+        "commentstyle": _font(SelectColor("gray"), Ttfamily()),
+        "escapechar": "|",
+    },
+    "shellCodeNOPASSWD": {
+        "language": "sh",
+        "deletekeywords": "{for,kill,cat}",
+        "morekeywords": "{sudo}",
+        "basicstyle": _font(Scriptsize(), Ttfamily()),
+        "keywordstyle": _font(SelectColor("blue"), Bfseries(), Ttfamily()),
+        "commentstyle": _font(SelectColor("gray"), Ttfamily()),
+        "escapechar": "|",
+        "numbers": "none",
+    },
+    "shellCode": {
+        "language": "sh",
+        "morekeywords": "{sudo,chmod,chown,cp,su,rm,python}",
+        "basicstyle": _font(Scriptsize(), Ttfamily()),
+        "keywordstyle": _font(SelectColor("blue"), Bfseries(), Ttfamily()),
+        "commentstyle": _font(SelectColor("gray"), Ttfamily()),
+        "escapechar": "|",
+    },
+    "URL": {
+        "basicstyle": _font(Footnotesize(), Ttfamily()),
+        "commentstyle": _font(SelectColor("gray"), Ttfamily()),
+        "escapechar": "|",
+        "numbers": "none",
+    },
+}
+
+
+@Registry.add
+def HSRTListingStyles() -> TeX:
+    return Concat(
+        Lstset(HSRT_LISTING_BASE),
+        *(Lstdefinestyle(name, opts) for name, opts in HSRT_LISTING_STYLES.items()),
+    )
+
+
+def style_options(name: str) -> dict[str, TeX | str]:
+    return dict(HSRT_LISTING_STYLES[name])