pytex-preprocessor 0.1.0rc1__py3-none-any.whl

pytex/commands/setspace.py

@@ -0,0 +1,38 @@
+from ..helpers.with_package import with_package
+from ..interface.tex import TeX
+from ..model.control_sequence import ControlSequence, Parameter
+from ..model.environment import Environment
+from ..packages import SETSPACE
+from ..registry import Registry
+
+__all__ = ["Doublespacing", "Onehalfspacing", "Setstretch", "Singlespacing", "Spacing"]
+
+
+@Registry.add
+@with_package(SETSPACE)
+def Setstretch(factor: str) -> TeX:
+    return ControlSequence("setstretch", (Parameter(factor),))
+
+
+@Registry.add
+@with_package(SETSPACE)
+def Singlespacing() -> TeX:
+    return ControlSequence("singlespacing", ())
+
+
+@Registry.add
+@with_package(SETSPACE)
+def Onehalfspacing() -> TeX:
+    return ControlSequence("onehalfspacing", ())
+
+
+@Registry.add
+@with_package(SETSPACE)
+def Doublespacing() -> TeX:
+    return ControlSequence("doublespacing", ())
+
+
+@Registry.add
+@with_package(SETSPACE)
+def Spacing(factor: str, body: TeX | str) -> TeX:
+    return Environment("spacing", body, (Parameter(factor),))

pytex/commands/tables.py

@@ -0,0 +1,123 @@
+from ..helpers.with_package import with_package
+from ..interface.tex import TeX
+from ..model.control_sequence import ControlSequence, Parameter
+from ..model.environment import Environment
+from ..packages import BOOKTABS, LONGTABLE, MULTIROW, TABULARX
+from ..registry import Registry
+
+__all__ = [
+    "Arraybackslash",
+    "Arraystretch",
+    "Bottomrule",
+    "Cline",
+    "Cmidrule",
+    "Hline",
+    "Longtable",
+    "Midrule",
+    "Multicolumn",
+    "Multirow",
+    "Newcolumntype",
+    "Tabular",
+    "Tabularx",
+    "Toprule",
+]
+
+
+@Registry.add
+def Tabular(spec: str, body: TeX | str) -> TeX:
+    return Environment("tabular", body, (Parameter(spec),))
+
+
+@Registry.add
+@with_package(TABULARX)
+def Tabularx(width: str, spec: str, body: TeX | str) -> TeX:
+    return Environment("tabularx", body, (Parameter(width), Parameter(spec)))
+
+
+@Registry.add
+@with_package(LONGTABLE)
+def Longtable(spec: str, body: TeX | str) -> TeX:
+    return Environment("longtable", body, (Parameter(spec),))
+
+
+@Registry.add
+def Multicolumn(cols: int, align: str, body: TeX | str) -> TeX:
+    return ControlSequence(
+        "multicolumn",
+        (Parameter(str(cols)), Parameter(align), Parameter(body)),
+    )
+
+
+@Registry.add
+@with_package(MULTIROW)
+def Multirow(rows: int, width: str, body: TeX | str) -> TeX:
+    return ControlSequence(
+        "multirow",
+        (Parameter(str(rows)), Parameter(width), Parameter(body)),
+    )
+
+
+@Registry.add
+def Hline() -> TeX:
+    return ControlSequence("hline", ())
+
+
+@Registry.add
+def Cline(spec: str) -> TeX:
+    return ControlSequence("cline", (Parameter(spec),))
+
+
+@Registry.add
+@with_package(BOOKTABS)
+def Toprule() -> TeX:
+    return ControlSequence("toprule", ())
+
+
+@Registry.add
+@with_package(BOOKTABS)
+def Midrule() -> TeX:
+    return ControlSequence("midrule", ())
+
+
+@Registry.add
+@with_package(BOOKTABS)
+def Bottomrule() -> TeX:
+    return ControlSequence("bottomrule", ())
+
+
+@Registry.add
+@with_package(BOOKTABS)
+def Cmidrule(spec: str, trim: str | None = None) -> TeX:
+    if trim is None:
+        return ControlSequence("cmidrule", (Parameter(spec),))
+    return ControlSequence(
+        "cmidrule",
+        (Parameter(trim, optional=True), Parameter(spec)),
+    )
+
+
+@Registry.add
+def Arraybackslash() -> TeX:
+    return ControlSequence("arraybackslash", ())
+
+
+@Registry.add
+def Arraystretch(factor: str) -> TeX:
+    return ControlSequence("arraystretch", (Parameter(factor),))
+
+
+@Registry.add
+def Newcolumntype(name: str, arity: int | None, spec: str) -> TeX:
+    if arity is None:
+        return ControlSequence(
+            "newcolumntype",
+            (Parameter(name), Parameter(spec)),
+        )
+    return ControlSequence(
+        "newcolumntype",
+        (
+            Parameter(name),
+            Parameter(str(arity), optional=True),
+            Parameter(spec),
+        ),
+    )

pytex/helpers/__init__.py

@@ -0,0 +1,3 @@
+from . import coerce, parenting, sanitize, with_package
+
+__all__ = ["coerce", "parenting", "sanitize", "with_package"]

pytex/helpers/coerce.py

@@ -0,0 +1,13 @@
+from ..interface.tex import TeX
+from ..model.raw import Raw
+from ..registry import Registry
+
+__all__ = ["coerce_tex"]
+
+
+@Registry.add
+def coerce_tex(value: TeX | str) -> TeX:
+    if isinstance(value, TeX):
+        return value
+
+    return Raw(value)

pytex/helpers/parenting.py

@@ -0,0 +1,13 @@
+from contextlib import suppress
+
+from ..interface.tex import TeX
+
+__all__ = ["attach"]
+
+
+def attach(parent: TeX, *children: object) -> None:
+    """Set `_parent` on each TeX child to `parent`. Non-TeX children are skipped."""
+    for child in children:
+        if isinstance(child, TeX):
+            with suppress(AttributeError, TypeError):
+                object.__setattr__(child, "_parent", parent)

pytex/helpers/sanitize.py

@@ -0,0 +1,54 @@
+"""Sanitize untrusted text before it enters a document.
+
+Two independent concerns:
+
+* ``tex``   - escape LaTeX-special characters so the text renders literally
+  (pytex itself does no escaping; raw strings pass straight through).
+* ``pytex`` - disable PyTeX replacement so an embedded
+  ``\\iffalse{pytex(...)}\\fi`` marker is never evaluated. The marker can run
+  arbitrary Python, so this matters for content from outside the program.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Final
+
+from ..model.raw import Raw
+from ..registry import Registry
+
+__all__ = ["Sanitize", "escape_latex"]
+
+if TYPE_CHECKING:
+    from ..interface.tex import TeX
+
+# Build the result char-by-char so braces introduced by a replacement are
+# never themselves re-escaped.
+ESCAPES: Final[dict[str, str]] = {
+    "\\": r"\textbackslash{}",
+    "&": r"\&",
+    "%": r"\%",
+    "$": r"\$",
+    "#": r"\#",
+    "_": r"\_",
+    "{": r"\{",
+    "}": r"\}",
+    "~": r"\textasciitilde{}",
+    "^": r"\textasciicircum{}",
+}
+
+
+def escape_latex(text: str) -> str:
+    """Return ``text`` with LaTeX-special characters escaped."""
+    return "".join(ESCAPES.get(ch, ch) for ch in text)
+
+
+@Registry.add
+def Sanitize(content: str, pytex: bool = True, tex: bool = True) -> TeX:
+    """Wrap ``content`` as a ``TeX`` node, neutralising unsafe input.
+
+    * ``tex=True``   escapes LaTeX-special characters.
+    * ``pytex=True`` prevents any ``\\iffalse{pytex(...)}\\fi`` marker in the
+      content from being evaluated.
+    """
+    text = escape_latex(content) if tex else content
+    return Raw(text, allow_replacements=not pytex)

pytex/helpers/with_package.py

@@ -0,0 +1,61 @@
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from functools import wraps
+from typing import override
+
+from pytex.interface.package import PackageProtocol
+
+from ..interface.tex import TeX
+from ..model.package import Package
+from ..registry import Registry
+from .parenting import attach
+
+__all__ = ["WithPackage", "coerce_package", "with_package"]
+
+
+@Registry.add
+def coerce_package(pkg: Package | str) -> Package:
+    if isinstance(pkg, Package):
+        return pkg
+
+    return Package(pkg)
+
+
+@Registry.add
+@dataclass
+class WithPackage[T: TeX](TeX):
+    child: T
+    package: Package | str
+    _parent: "TeX | None" = field(default=None, init=False, compare=False, repr=False)
+
+    def __post_init__(self) -> None:
+        attach(self, self.child)
+
+    @property
+    @override
+    def rendered(self) -> str:
+        return self.child.rendered
+
+    @property
+    @override
+    def children(self) -> tuple[TeX, ...]:
+        return (self.child,)
+
+    @property
+    @override
+    def requires(self) -> frozenset[PackageProtocol] | None:
+        return frozenset(
+            {coerce_package(self.package)}
+            | (self.child.requires or set[PackageProtocol]())
+        )
+
+
+def with_package[C: Callable[..., TeX]](pkg: Package | str) -> Callable[[C], C]:
+    def decorator(func: C) -> C:
+        @wraps(func)
+        def wrapper(*args: object, **kwargs: object) -> TeX:
+            return WithPackage(func(*args, **kwargs), pkg)
+
+        return wrapper  # pyright: ignore[reportReturnType]
+
+    return decorator

pytex/interface/__init__.py

@@ -0,0 +1,3 @@
+from . import control_sequence, package, tex
+
+__all__ = ["control_sequence", "package", "tex"]

pytex/interface/control_sequence.py

@@ -0,0 +1,29 @@
+from typing import Protocol, runtime_checkable
+
+from ..model.empty import EmptyTeX
+from .tex import TeX
+
+__all__ = ["ControlSequenceProtocol", "ParameterProtocol"]
+
+type ParameterType = TeX | str | dict[str, str]
+
+
+@runtime_checkable
+class ParameterProtocol[T: ParameterType = ParameterType](TeX, Protocol):
+    @property
+    def optional(self) -> bool: ...
+
+    @property
+    def value(self) -> T: ...
+
+
+type Parameters = tuple[ParameterProtocol | EmptyTeX, ...] | None
+
+
+@runtime_checkable
+class ControlSequenceProtocol[P: Parameters](TeX, Protocol):
+    @property
+    def name(self) -> str: ...
+
+    @property
+    def params(self) -> P: ...

pytex/interface/package.py

@@ -0,0 +1,52 @@
+from typing import Protocol, Self, override, runtime_checkable
+
+__all__ = ["PackageProtocol"]
+
+type PackageOption = str | tuple[str, str]
+
+
+@runtime_checkable
+class PackageProtocol(Protocol):
+    @property
+    def name(self) -> str: ...
+
+    @property
+    def after(self) -> frozenset[Self]: ...
+
+    @property
+    def incompatible(self) -> frozenset[Self]: ...
+
+    @property
+    def options(self) -> frozenset[PackageOption]: ...
+
+    @property
+    def rendered(self) -> str:
+        """Render this object to a valid LaTeX-String"""
+        ...
+
+    @property
+    def children(self) -> tuple[Self, ...]:
+        return ()
+
+    @property
+    def requires(self) -> frozenset[Self]:
+        return self.after
+
+    @property
+    def parent(self) -> Self | None:
+        """Parent node in the document tree, or None if root/detached."""
+        return getattr(self, "_parent", None)
+
+    @property
+    def parents(self) -> tuple[Self, ...]:
+        """Chain of ancestors from immediate parent up to root."""
+        out: list[Self] = []
+        cur = self.parent
+        while cur is not None:
+            out.append(cur)
+            cur = cur.parent
+        return tuple(out)
+
+    @override
+    def __str__(self) -> str:
+        return self.rendered

pytex/interface/tex.py

@@ -0,0 +1,41 @@
+from typing import Protocol, override, runtime_checkable
+
+from .package import PackageProtocol
+
+__all__ = ["TeX"]
+
+
+@runtime_checkable
+class TeX(Protocol):
+    @property
+    def rendered(self) -> str:
+        """Render this Node to a valid LaTeX-String"""
+        ...
+
+    @property
+    def children(self) -> tuple["TeX", ...]:
+        """Children of the Node"""
+        return ()
+
+    @property
+    def requires(self) -> frozenset[PackageProtocol] | None:
+        return None
+
+    @property
+    def parent(self) -> "TeX | None":
+        """Parent node in the document tree, or None if root/detached."""
+        return getattr(self, "_parent", None)
+
+    @property
+    def parents(self) -> tuple["TeX", ...]:
+        """Chain of ancestors from immediate parent up to root."""
+        out: list[TeX] = []
+        cur = self.parent
+        while cur is not None:
+            out.append(cur)
+            cur = cur.parent
+        return tuple(out)
+
+    @override
+    def __str__(self) -> str:
+        return self.rendered

pytex/model/__init__.py

@@ -0,0 +1,25 @@
+# pyright: reportUnsupportedDunderAll=false
+"""Model subpackage.
+
+Modules are not eager-imported here to avoid a circular import:
+`pytex/__init__.py` → `pytex.packages` → `pytex.model.package` →
+`pytex.model.__init__` → `pytex.model.math` → `pytex.packages` (still loading).
+
+Import submodules directly: `from pytex.model.math import Frac`.
+"""
+
+__all__ = [
+    "color",
+    "concat",
+    "control_sequence",
+    "document",
+    "document_class",
+    "empty",
+    "environment",
+    "image",
+    "include",
+    "length",
+    "math",
+    "package",
+    "raw",
+]

pytex/model/color.py

@@ -0,0 +1,203 @@
+from dataclasses import dataclass
+from typing import override
+
+from ..interface.package import PackageProtocol
+from ..interface.tex import TeX
+from ..registry import Registry
+
+__all__ = [
+    "Color",
+    "ColorSpec",
+    "collect_colors",
+    "is_known_color_name",
+    "register_named_color",
+]
+
+NAMED_COLORS: set[str] = {
+    "black",
+    "white",
+    "red",
+    "green",
+    "blue",
+    "cyan",
+    "magenta",
+    "yellow",
+    "gray",
+    "lightgray",
+    "darkgray",
+    "orange",
+    "violet",
+    "purple",
+    "brown",
+    "pink",
+    "olive",
+    "lime",
+    "teal",
+}
+
+
+def register_named_color(name: str) -> None:
+    """Whitelist a name so `Color.named(name)` accepts it."""
+    NAMED_COLORS.add(name)
+
+
+def is_known_color_name(name: str) -> bool:
+    return name in NAMED_COLORS
+
+
+@dataclass(frozen=True)
+class ColorSpec:
+    """Frozen colour identity: `model` + `value` for `\\definecolor`."""
+
+    model: str
+    value: str
+
+
+@Registry.add
+class Color(TeX):
+    """Type-safe colour reference.
+
+    Constructors:
+        Color("blue")                 # registered name
+        Color("#FF0000")              # hex
+        Color((255, 0, 0))            # rgb 0..255
+        Color((1.0, 0.0, 0.0))        # rgb 0..1
+        Color.hex("FF0000")
+        Color.rgb255(255, 0, 0)
+        Color.rgb(1.0, 0.0, 0.0)
+        Color.named("blue")
+    """
+
+    name: str
+    spec: ColorSpec | None
+    _parent: "TeX | None"
+
+    def __init__(
+        self,
+        value: "str | tuple[int, int, int] | tuple[float, float, float] | None" = None,
+        *,
+        name: str | None = None,
+        spec: ColorSpec | None = None,
+    ) -> None:
+        if value is not None:
+            resolved_name, resolved_spec = _from_overload(value)
+            self.name = resolved_name
+            self.spec = resolved_spec
+        elif name is not None:
+            self.name = name
+            self.spec = spec
+        else:
+            raise TypeError("Color() requires `value` or `name`")
+        self._parent = None
+
+    @classmethod
+    def hex(cls, value: str, name: str | None = None) -> "Color":
+        clean = value.lstrip("#").upper()
+        if len(clean) != 6 or any(c not in "0123456789ABCDEF" for c in clean):
+            raise ValueError(f"invalid hex colour: {value!r}")
+        return cls(name=name or f"c{clean}", spec=ColorSpec("HTML", clean))
+
+    @classmethod
+    def rgb255(cls, r: int, g: int, b: int, name: str | None = None) -> "Color":
+        for v in (r, g, b):
+            if not 0 <= v <= 255:
+                raise ValueError(f"rgb255 component out of range: {v}")
+        return cls(
+            name=name or f"c{r:03d}{g:03d}{b:03d}",
+            spec=ColorSpec("RGB", f"{r},{g},{b}"),
+        )
+
+    @classmethod
+    def rgb(cls, r: float, g: float, b: float, name: str | None = None) -> "Color":
+        for v in (r, g, b):
+            if not 0.0 <= float(v) <= 1.0:
+                raise ValueError(f"rgb component out of range [0,1]: {v}")
+        return cls(
+            name=name or f"crgb{int(r * 255):03d}{int(g * 255):03d}{int(b * 255):03d}",
+            spec=ColorSpec("rgb", f"{r},{g},{b}"),
+        )
+
+    @classmethod
+    def named(cls, name: str) -> "Color":
+        if not is_known_color_name(name):
+            raise ValueError(
+                f"unknown colour name {name!r}; register via register_named_color"
+            )
+        return cls(name=name, spec=None)
+
+    def tint(self, percent: int) -> "Color":
+        """xcolor tint: `<self>!<percent>` (e.g. `blue!20`)."""
+        return Color(name=f"{self.name}!{percent}", spec=None)
+
+    def mix(self, other: "Color", percent: int = 50) -> "Color":
+        return Color(
+            name=f"{self.name}!{percent}!{other.name}",
+            spec=None,
+        )
+
+    def __or__(self, other: "Color") -> "Color":
+        return self.mix(other)
+
+    @override
+    def __eq__(self, other: object) -> bool:
+        return (
+            isinstance(other, Color)
+            and self.name == other.name
+            and self.spec == other.spec
+        )
+
+    @override
+    def __hash__(self) -> int:
+        return hash((self.name, self.spec))
+
+    @override
+    def __repr__(self) -> str:
+        return f"Color(name={self.name!r}, spec={self.spec!r})"
+
+    @property
+    @override
+    def rendered(self) -> str:
+        return self.name
+
+    @property
+    @override
+    def requires(self) -> frozenset[PackageProtocol]:
+        from ..packages import XCOLOR
+
+        return frozenset({XCOLOR})
+
+
+def _from_overload(
+    value: "str | tuple[int, int, int] | tuple[float, float, float]",
+) -> tuple[str, ColorSpec | None]:
+    if isinstance(value, str):
+        if value.startswith("#"):
+            c = Color.hex(value)
+            return c.name, c.spec
+        if not is_known_color_name(value):
+            raise ValueError(f"unknown colour name {value!r}")
+        return value, None
+    if len(value) == 3:
+        if all(type(v) is int for v in value):
+            r, g, b = value
+            c = Color.rgb255(int(r), int(g), int(b))
+            return c.name, c.spec
+        if all(isinstance(v, float) for v in value):
+            r, g, b = value
+            c = Color.rgb(float(r), float(g), float(b))
+            return c.name, c.spec
+    raise TypeError(f"cannot construct Color from {value!r}")
+
+
+def collect_colors(root: TeX) -> tuple[Color, ...]:
+    """Walk a TeX tree, return all unique `Color` instances with a `spec`."""
+    seen: dict[str, Color] = {}
+
+    def walk(node: TeX) -> None:
+        if isinstance(node, Color) and node.spec is not None and node.name not in seen:
+            seen[node.name] = node
+        for child in node.children or ():
+            walk(child)
+
+    walk(root)
+    return tuple(seen.values())

pytex/model/concat.py

@@ -0,0 +1,31 @@
+from dataclasses import dataclass
+from typing import Final, override
+
+from ..helpers.coerce import coerce_tex
+from ..helpers.parenting import attach
+from ..interface.tex import TeX
+from ..registry import Registry
+
+__all__ = ["Concat"]
+
+
+@Registry.add
+@dataclass(frozen=True, init=False)
+class Concat(TeX):
+    elements: Final[tuple[TeX]]
+
+    def __init__(self, *elements: TeX | str) -> None:
+        coerced = tuple(coerce_tex(e) for e in elements)
+        object.__setattr__(self, "elements", coerced)
+        object.__setattr__(self, "_parent", None)
+        attach(self, *coerced)
+
+    @property
+    @override
+    def children(self) -> tuple[TeX, ...]:
+        return self.elements
+
+    @property
+    @override
+    def rendered(self) -> str:
+        return "".join(str(e) for e in self.elements)