pytex-preprocessor 0.1.0__py3-none-any.whl

pytex/model/control_sequence.py

@@ -0,0 +1,72 @@
+from dataclasses import dataclass, field
+from typing import Final, override
+
+from ..helpers.parenting import attach
+from ..interface.control_sequence import Parameters, ParameterType
+from ..interface.package import PackageProtocol
+from ..interface.tex import TeX
+from ..registry import Registry
+from .raw import Raw
+
+__all__ = ["ControlSequence", "Parameter"]
+
+
+@Registry.add
+@dataclass(frozen=True, slots=True)
+class Parameter[T: ParameterType = ParameterType](TeX):
+    value: Final[T]
+    optional: Final[bool] = False
+    _parent: "TeX | None" = field(default=None, init=False, compare=False, repr=False)
+
+    def __post_init__(self) -> None:
+        attach(self, self.value)
+
+    @property
+    def _braces(self) -> tuple[str, str]:
+        return ("[", "]") if self.optional else ("{", "}")
+
+    @property
+    @override
+    def children(self) -> tuple[TeX]:
+        if isinstance(self.value, dict):
+            return tuple[TeX]()
+
+        return (self.value if isinstance(self.value, TeX) else Raw(self.value),)
+
+    @property
+    @override
+    def rendered(self) -> str:
+        """Render this Node to a valid LaTeX-String"""
+
+        content: str | TeX = ""
+
+        if isinstance(self.value, (TeX, str)):
+            content = self.value
+        else:
+            content = ",".join(f"{key}={value}" for key, value in self.value.items())
+
+        return f"{self._braces[0]}{content}{self._braces[1]}"
+
+
+@Registry.add
+@dataclass(frozen=True, slots=True)
+class ControlSequence[P: Parameters](TeX):
+    name: Final[str]
+    params: Final[P]
+    required_packages: frozenset[PackageProtocol] = field(default_factory=frozenset)
+    _parent: "TeX | None" = field(default=None, init=False, compare=False, repr=False)
+
+    def __post_init__(self) -> None:
+        if self.params is not None:
+            attach(self, *self.params)
+
+    @property
+    @override
+    def requires(self) -> frozenset[PackageProtocol]:
+        return self.required_packages
+
+    @property
+    @override
+    def rendered(self) -> str:
+        body = "".join(p.rendered for p in (self.params or ()))
+        return f"\\{self.name}{body}"

pytex/model/document.py

@@ -0,0 +1,120 @@
+from dataclasses import dataclass, field
+from typing import override
+
+from ..helpers.coerce import coerce_tex
+from ..helpers.parenting import attach
+from ..interface.package import PackageOption, PackageProtocol
+from ..interface.tex import TeX
+from ..registry import Registry
+from .concat import Concat
+from .document_class import DocumentClass
+from .empty import Empty
+from .environment import Environment
+from .image import IncludeImage, collect_inline_images, filecontents_b64_block
+from .raw import Raw
+
+__all__ = ["Document"]
+
+
+@Registry.add
+@dataclass
+class Document(TeX):
+    body: TeX | str
+    document_class: str = "article"
+    document_class_options: set[PackageOption] = field(default_factory=set)
+    preamble: TeX | str = Empty
+    extra_packages: frozenset[PackageProtocol] = field(default_factory=frozenset)
+    _parent: "TeX | None" = field(default=None, init=False, compare=False, repr=False)
+
+    def __post_init__(self) -> None:
+        attach(self, self.body, self.preamble)
+
+    @property
+    def packages(self) -> frozenset[PackageProtocol]:
+        def get_packages(obj: TeX, found: set[PackageProtocol]) -> None:
+            found |= {
+                after
+                for pkg in (obj.requires or set[PackageProtocol]())
+                for after in pkg.after | {pkg}
+            }
+
+            for child in obj.children or ():
+                get_packages(child, found)
+
+        found = set[PackageProtocol]()
+
+        get_packages(coerce_tex(self.body), found)
+        get_packages(coerce_tex(self.preamble), found)
+
+        return frozenset(found | self.extra_packages)
+
+    def ordered_packages(self) -> tuple[PackageProtocol, ...]:
+        """Packages sorted so each is emitted after its `after` dependencies.
+
+        A frozenset has no stable order, but some packages must be loaded in a
+        fixed sequence (e.g. `cleveref` after `hyperref`). Resolve that with a
+        depth-first topological sort, breaking ties by name for reproducibility.
+        """
+        packages = self.packages
+        by_name = {p.name: p for p in packages}
+        state: dict[str, bool] = {}  # name -> finished?
+        out: list[PackageProtocol] = []
+
+        def visit(pkg: PackageProtocol) -> None:
+            if state.get(pkg.name) is not None:
+                return  # finished, or currently visiting (cycle guard)
+            state[pkg.name] = False
+            for dep in sorted(pkg.after or (), key=lambda d: d.name):
+                present = by_name.get(dep.name)
+                if present is not None:
+                    visit(present)
+            state[pkg.name] = True
+            out.append(pkg)
+
+        for pkg in sorted(packages, key=lambda p: p.name):
+            visit(pkg)
+        return tuple(out)
+
+    @property
+    def inline_images(self) -> tuple[IncludeImage, ...]:
+        images: dict[str, IncludeImage] = {}
+        for root in (self.body, self.preamble):
+            for img in collect_inline_images(coerce_tex(root)):
+                key = img.resolved_path.as_posix()
+                images.setdefault(key, img)
+        return tuple(images.values())
+
+    def write_inline_images(self, target_dir: str = ".") -> tuple[str, ...]:
+        """Materialise inline images to disk relative to `target_dir`. Returns paths."""
+        from pathlib import Path
+
+        written: list[str] = []
+        base = Path(target_dir)
+        for img in self.inline_images:
+            img.ensure_converted()
+            resolved = img.resolved_path
+            rel = Path(*resolved.parts[1:]) if resolved.is_absolute() else resolved
+            dest = base / rel
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            dest.write_bytes(img.read_bytes())
+            written.append(dest.as_posix())
+        return tuple(written)
+
+    @property
+    def inline_image_block(self) -> TeX:
+        """`\\begin{filecontents*}` for each inline image, in tree order."""
+        images = self.inline_images
+        if not images:
+            return Empty
+        return Concat(*(Raw(filecontents_b64_block(img)) for img in images))
+
+    @property
+    @override
+    def rendered(self) -> str:
+        return Concat(
+            DocumentClass(self.document_class, self.document_class_options),
+            *self.ordered_packages(),
+            self.inline_image_block,
+            self.preamble,
+            Environment("document", self.body),
+        ).rendered

pytex/model/document_class.py

@@ -0,0 +1,29 @@
+from pytex.model.empty import Empty
+
+from ..interface.package import PackageOption
+from ..interface.tex import TeX
+from ..registry import Registry
+from .control_sequence import ControlSequence, Parameter
+from .raw import Raw
+
+__all__ = ["DocumentClass"]
+
+
+def _render_options(options: set[PackageOption] | frozenset[PackageOption]) -> str:
+    return ",".join(
+        item if isinstance(item, str) else f"{item[0]}={item[1]}" for item in options
+    )
+
+
+@Registry.add
+def DocumentClass(
+    name: str,
+    options: set[PackageOption] | frozenset[PackageOption] | None = None,
+) -> TeX:
+    options = options or set()
+    rendered = _render_options(options)
+    opt_param = Parameter(Raw(rendered), optional=True) if rendered else Empty
+    return ControlSequence(
+        "documentclass",
+        (opt_param, Parameter(name)),
+    )

pytex/model/empty.py

@@ -0,0 +1,19 @@
+from typing import override
+
+from ..interface.tex import TeX
+from ..registry import Registry
+
+__all__ = ["EmptyTeX"]
+
+
+@Registry.add
+class EmptyTeX(TeX):
+    _parent: "TeX | None" = None
+
+    @property
+    @override
+    def rendered(self) -> str:
+        return ""
+
+
+Empty = EmptyTeX()

pytex/model/environment.py

@@ -0,0 +1,30 @@
+from ..interface.control_sequence import Parameters
+from ..interface.tex import TeX
+from ..registry import Registry
+from .concat import Concat
+from .control_sequence import ControlSequence, Parameter
+from .raw import Raw
+
+__all__ = ["Begin", "End", "Environment"]
+
+
+@Registry.add
+def Begin(name: str, params: Parameters = None) -> TeX:
+    return ControlSequence(
+        "begin",
+        (Parameter(Raw(name)), *(params or ())),
+    )
+
+
+@Registry.add
+def End(name: str) -> TeX:
+    return ControlSequence("end", (Parameter(Raw(name)),))
+
+
+@Registry.add
+def Environment(name: str, body: TeX | str, params: Parameters = None) -> TeX:
+    return Concat(
+        Begin(name, params),
+        body,
+        End(name),
+    )

pytex/model/image.py

@@ -0,0 +1,137 @@
+import base64
+import hashlib
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Final, override
+
+from ..helpers.parenting import attach
+from ..interface.package import PackageProtocol
+from ..interface.tex import TeX
+from ..registry import Registry
+
+__all__ = ["IncludeImage", "collect_inline_images", "filecontents_b64_block"]
+
+PDF_COMPAT = {".pdf", ".png", ".jpg", ".jpeg", ".eps"}
+
+
+def _convert_to_pdf(src: Path, dst: Path) -> None:
+    """SVG → PDF via inkscape. Raises FileNotFoundError if inkscape absent."""
+    if src.suffix.lower() != ".svg":
+        raise ValueError(f"only SVG conversion supported, got {src.suffix}")
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    subprocess.run(
+        ["inkscape", str(src), "--export-type=pdf", f"--export-filename={dst}"],
+        check=True,
+        capture_output=True,
+    )
+
+
+@Registry.add
+@dataclass
+class IncludeImage(TeX):
+    """`\\includegraphics{path}` with optional base64 baking.
+
+    - Accepts any image format. SVG is converted to PDF via `inkscape` lazily
+      (only when bytes are accessed and `inline_base64=True`).
+    - When `inline_base64=True`, `Document` collects the node and emits a
+      `\\begin{filecontents*}[overwrite,nosearch]{<resolved>.b64}` block at the
+      document start containing the raw base64. A build helper can decode them
+      to disk before the TeX run. The `\\includegraphics` line stays unchanged.
+    """
+
+    path: Final[str | Path]
+    inline_base64: Final[bool] = False
+    width: Final[str | None] = None
+    height: Final[str | None] = None
+    scale: Final[str | None] = None
+    keepaspectratio: Final[bool] = False
+    _parent: "TeX | None" = field(default=None, init=False, compare=False, repr=False)
+
+    @property
+    def source_path(self) -> Path:
+        return Path(self.path)
+
+    @property
+    def resolved_path(self) -> Path:
+        """Path that `\\includegraphics` references. SVG → PDF in build/."""
+        src = self.source_path
+        if src.suffix.lower() in PDF_COMPAT:
+            return src
+        if src.suffix.lower() == ".svg":
+            digest = hashlib.sha1(src.resolve().as_posix().encode()).hexdigest()[:10]
+            return Path("build") / f"{src.stem}-{digest}.pdf"
+        raise ValueError(f"unsupported image extension: {src.suffix}")
+
+    def ensure_converted(self) -> None:
+        """Run SVG→PDF conversion if needed. Idempotent."""
+        if self.source_path.suffix.lower() == ".svg":
+            target = self.resolved_path
+            if not target.exists():
+                _convert_to_pdf(self.source_path, target)
+
+    def read_bytes(self) -> bytes:
+        """Return the bytes of the resolved (TeX-compatible) image."""
+        self.ensure_converted()
+        return self.resolved_path.read_bytes()
+
+    def base64_payload(self) -> str:
+        return base64.b64encode(self.read_bytes()).decode("ascii")
+
+    @property
+    @override
+    def rendered(self) -> str:
+        opts: list[str] = []
+        if self.width is not None:
+            opts.append(f"width={self.width}")
+        if self.height is not None:
+            opts.append(f"height={self.height}")
+        if self.scale is not None:
+            opts.append(f"scale={self.scale}")
+        if self.keepaspectratio:
+            opts.append("keepaspectratio")
+        opt_str = f"[{','.join(opts)}]" if opts else ""
+        return f"\\includegraphics{opt_str}{{{self.resolved_path.as_posix()}}}"
+
+    @property
+    @override
+    def requires(self) -> frozenset[PackageProtocol]:
+        from ..packages import GRAPHICX
+
+        return frozenset({GRAPHICX})
+
+
+def collect_inline_images(root: TeX) -> tuple[IncludeImage, ...]:
+    """Walk a TeX tree, return all IncludeImage nodes with `inline_base64=True`."""
+    seen: dict[str, IncludeImage] = {}
+
+    def walk(node: TeX) -> None:
+        if isinstance(node, IncludeImage) and node.inline_base64:
+            key = node.resolved_path.as_posix()
+            if key not in seen:
+                seen[key] = node
+        for child in node.children or ():
+            walk(child)
+
+    walk(root)
+    return tuple(seen.values())
+
+
+def filecontents_b64_block(image: IncludeImage) -> str:
+    """`\\begin{filecontents*}[overwrite,nosearch]{<resolved>.b64}<base64>\\end{filecontents*}`."""
+    target = image.resolved_path.as_posix() + ".b64"
+    payload = image.base64_payload()
+    chunks = [payload[i : i + 76] for i in range(0, len(payload), 76)]
+    body = "\n".join(chunks)
+    # Trailing newline is required: LaTeX ignores anything after
+    # \end{filecontents*} on the same line, so without it the next token
+    # (another block, or the preamble) would be silently dropped.
+    return (
+        f"\\begin{{filecontents*}}[overwrite,nosearch]{{{target}}}\n"
+        f"{body}\n"
+        "\\end{filecontents*}\n"
+    )
+
+
+# Avoid unused-import warning
+_ = attach

pytex/model/include.py

@@ -0,0 +1,21 @@
+from os import PathLike
+from pathlib import Path
+
+from ..registry import Registry
+from .raw import Raw
+
+__all__ = ["IncludeTeX"]
+
+
+@Registry.add
+def IncludeTeX(
+    path: str | PathLike[str],
+    namespace: dict[str, object] | None = None,
+    allow_replacements: bool = True,
+) -> Raw:
+    content = Path(path).read_text()
+    return Raw(
+        content,
+        namespace=namespace,
+        allow_replacements=allow_replacements,
+    )

pytex/model/length.py

@@ -0,0 +1,54 @@
+from dataclasses import dataclass
+from typing import Final, override
+
+from ..interface.tex import TeX
+from ..registry import Registry
+
+__all__ = ["Length"]
+
+
+def _expr(value: "Length | int | float | str") -> str:
+    if isinstance(value, Length):
+        return value.expr
+    return str(value)
+
+
+@Registry.add
+@dataclass(frozen=True)
+class Length(TeX):
+    """LaTeX length expression. Arithmetic uses the calc package syntax.
+
+    Combine via Python operators: `Linewidth() - "0.5cm"`, `0.5 * Textwidth()`.
+    Pass to anything that takes a length spec (Vspace, Setlength, Minipage width).
+    """
+
+    expr: Final[str]
+
+    @property
+    @override
+    def rendered(self) -> str:
+        return self.expr
+
+    def __add__(self, other: "Length | int | float | str") -> "Length":
+        return Length(f"{self.expr}+{_expr(other)}")
+
+    def __radd__(self, other: "Length | int | float | str") -> "Length":
+        return Length(f"{_expr(other)}+{self.expr}")
+
+    def __sub__(self, other: "Length | int | float | str") -> "Length":
+        return Length(f"{self.expr}-{_expr(other)}")
+
+    def __rsub__(self, other: "Length | int | float | str") -> "Length":
+        return Length(f"{_expr(other)}-{self.expr}")
+
+    def __mul__(self, factor: int | float) -> "Length":
+        return Length(f"{factor}{self.expr}")
+
+    def __rmul__(self, factor: int | float) -> "Length":
+        return Length(f"{factor}{self.expr}")
+
+    def __truediv__(self, divisor: int | float) -> "Length":
+        return Length(f"{self.expr}/{divisor}")
+
+    def __neg__(self) -> "Length":
+        return Length(f"-{self.expr}")