pytex-preprocessor 0.3.0__tar.gz → 0.4.1__tar.gz

{pytex_preprocessor-0.3.0 → pytex_preprocessor-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytex-preprocessor
-Version: 0.3.0
+Version: 0.4.1
 Summary: Type-safe LaTeX document generation with Python
 Author-email: Frederik Beimgraben <frederik@beimgraben.net>
 Requires-Python: >=3.13
@@ -28,6 +28,20 @@ uses.
 
 ## Install
 
+### Prebuilt binary
+
+Each release attaches standalone `pytex` binaries (Linux/macOS/Windows) — no
+Python or `pip` needed. Download one from the
+[Releases](https://github.com/frederikbeimgraben/PyTeX-Preprocessor/releases)
+page, make it executable, and run it. The binary bundles its own interpreter
+plus common data packages (numpy, pandas, openpyxl/calamine for spreadsheets,
+Pillow, PyYAML), so documents can `import` those without installing anything;
+see [`packaging/`](packaging/). It is built on Python 3.14, so documents may use
+`tex(t"...")` even on machines without 3.14. (`--build` still needs `tectonic`,
+which pytex downloads on first use.)
+
+### From PyPI
+
 To use the `pytex` command anywhere, install it as an isolated tool with
 [pipx](https://pipx.pypa.io/):
 
@@ -82,6 +96,22 @@ pytex example.tex.py --build  # render + compile -> build/example.out.pdf
 
 Bare strings are coerced to text nodes and LaTeX-escaped.
 
+### Template strings (Python 3.14+)
+
+On Python 3.14, `pytex.tex` accepts a [PEP 750](https://peps.python.org/pep-0750/)
+template string and builds a `TeX` tree from it. Static parts are literal LaTeX;
+interpolations are LaTeX-escaped when they are plain values and spliced as-is
+when they are `TeX` nodes (nested template strings and lists are handled too):
+
+```py
+from pytex import tex
+
+name = "Q&A: 50%"
+body = tex(t"{Bold('Heading')} — {name}")   # node spliced; name -> "Q\&A: 50\%"
+```
+
+`tex` is only exported on 3.14+; the rest of the library runs on 3.13.
+
 ## The `pytex` command
 
 The input file is dispatched by extension:

{pytex_preprocessor-0.3.0 → pytex_preprocessor-0.4.1}/README.md

@@ -14,6 +14,20 @@ uses.
 
 ## Install
 
+### Prebuilt binary
+
+Each release attaches standalone `pytex` binaries (Linux/macOS/Windows) — no
+Python or `pip` needed. Download one from the
+[Releases](https://github.com/frederikbeimgraben/PyTeX-Preprocessor/releases)
+page, make it executable, and run it. The binary bundles its own interpreter
+plus common data packages (numpy, pandas, openpyxl/calamine for spreadsheets,
+Pillow, PyYAML), so documents can `import` those without installing anything;
+see [`packaging/`](packaging/). It is built on Python 3.14, so documents may use
+`tex(t"...")` even on machines without 3.14. (`--build` still needs `tectonic`,
+which pytex downloads on first use.)
+
+### From PyPI
+
 To use the `pytex` command anywhere, install it as an isolated tool with
 [pipx](https://pipx.pypa.io/):
 
@@ -68,6 +82,22 @@ pytex example.tex.py --build  # render + compile -> build/example.out.pdf
 
 Bare strings are coerced to text nodes and LaTeX-escaped.
 
+### Template strings (Python 3.14+)
+
+On Python 3.14, `pytex.tex` accepts a [PEP 750](https://peps.python.org/pep-0750/)
+template string and builds a `TeX` tree from it. Static parts are literal LaTeX;
+interpolations are LaTeX-escaped when they are plain values and spliced as-is
+when they are `TeX` nodes (nested template strings and lists are handled too):
+
+```py
+from pytex import tex
+
+name = "Q&A: 50%"
+body = tex(t"{Bold('Heading')} — {name}")   # node spliced; name -> "Q\&A: 50\%"
+```
+
+`tex` is only exported on 3.14+; the rest of the library runs on 3.13.
+
 ## The `pytex` command
 
 The input file is dispatched by extension:

{pytex_preprocessor-0.3.0 → pytex_preprocessor-0.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pytex-preprocessor"
-version = "0.3.0"
+version = "0.4.1"
 authors = [
   { name="Frederik Beimgraben", email="frederik@beimgraben.net" },
 ]
@@ -37,6 +37,9 @@ addopts = "--import-mode=importlib"
 line-length = 88
 target-version = "py313"
 src = ["src", "tests"]
+# Uses Python 3.14 t-string syntax; the py313 target cannot parse it. Excluded
+# from lint/format (it is exercised by pytest on 3.14).
+extend-exclude = ["tests/pytex/test_template.py"]
 
 [tool.ruff.lint]
 select = [

{pytex_preprocessor-0.3.0 → pytex_preprocessor-0.4.1}/src/pytex/__init__.py

@@ -1,3 +1,5 @@
+import sys
+
 from . import packages
 from .commands import (
     biblatex,
@@ -87,3 +89,10 @@ __all__ = [
     "tables",
     "with_package",
 ]
+
+# `tex(t"...")` needs PEP 750 template strings (Python 3.14+). Exposed only
+# there; the rest of the library stays importable on 3.13.
+if sys.version_info >= (3, 14):
+    from .template import tex as tex  # pyright: ignore[reportUnreachable]
+
+    __all__.append("tex")

{pytex_preprocessor-0.3.0 → pytex_preprocessor-0.4.1}/src/pytex/model/math.py

@@ -67,11 +67,46 @@ __all__ = [
 ]
 
 
+def _restrip(raw: Raw, how: str) -> Raw:
+    content = raw.content.lstrip() if how == "l" else raw.content.rstrip()
+    return Raw(content, raw.namespace, raw.allow_replacements)
+
+
+def _is_blank(node: TeX | str) -> bool:
+    return isinstance(node, Raw) and node.content.strip() == ""
+
+
+def _trim(body: TeX | str) -> TeX | str:
+    """Strip whitespace just inside the math delimiters.
+
+    TeX math mode ignores leading/trailing spaces and newlines, so this is
+    render-equivalent; it also avoids a blank line (`\\par`) sneaking inside the
+    delimiters, which is a hard LaTeX error. Only the outer boundary is touched
+    (interior whitespace can be significant, e.g. in `\\text{}` or alignments).
+    """
+    if isinstance(body, str):
+        return body.strip()
+    if isinstance(body, Raw):
+        return Raw(body.content.strip(), body.namespace, body.allow_replacements)
+    if isinstance(body, Concat):
+        elements = list(body.elements)
+        while elements and _is_blank(elements[0]):
+            elements.pop(0)
+        while elements and _is_blank(elements[-1]):
+            elements.pop()
+        if elements and isinstance(elements[0], Raw):
+            elements[0] = _restrip(elements[0], "l")
+        if elements and isinstance(elements[-1], Raw):
+            elements[-1] = _restrip(elements[-1], "r")
+        return Concat(*elements)
+    return body
+
+
 @Registry.add
 def Math(body: TeX | str) -> TeX:
     return Concat(
         ControlSequence("(", ()),
-        body,
+        _trim(body),
         ControlSequence(")", ()),
     )
 
@@ -79,14 +114,14 @@ def Math(body: TeX | str) -> TeX:
 @Registry.add
 def InlineMath(body: TeX | str) -> TeX:
     """Dollar-delimited inline math: ``$body$``."""
-    return Concat(Raw("$"), body, Raw("$"))
+    return Concat(Raw("$"), _trim(body), Raw("$"))
 
 
 @Registry.add
 def DisplayMath(body: TeX | str) -> TeX:
     return Concat(
         ControlSequence("[", ()),
-        body,
+        _trim(body),
         ControlSequence("]", ()),
     )
 

pytex_preprocessor-0.4.1/src/pytex/template.py

@@ -0,0 +1,90 @@
+r"""`tex(t"...")` — build a `TeX` tree from a template string (PEP 750).
+
+Requires Python 3.14 (the ``t"..."`` syntax and :mod:`string.templatelib`).
+This module is import-safe on older versions — it contains no t-string literals
+and guards the runtime import — but :func:`tex` can only be called with a real
+``Template``, which cannot exist before 3.14. ``pytex`` only re-exports it on
+3.14+.
+
+The rendering model mirrors the escape boundary a LaTeX document needs:
+
+* static template parts are literal LaTeX (author-written, trusted);
+* interpolations are escaped when they are plain values, spliced as-is when
+  they are `TeX` nodes, and recursed when they are nested template strings or
+  iterables of the above.
+
+    name = "Q&A: 50%"
+    tex(t"{Bold('Heading')} - {name}")   # node spliced; name -> "Q\&A: 50\%"
+"""
+
+# `string.templatelib` has no type stub before 3.14, so a type-checker running
+# on an older Python cannot type the `Template` import; silence that noise for
+# this module only (its logic is exercised on 3.14 in CI / the docker test).
+# pyright: reportMissingImports=false, reportUnknownVariableType=false
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast
+
+from .helpers.sanitize import escape_latex
+from .interface.tex import TeX
+from .model.concat import Concat
+from .model.empty import Empty
+from .model.raw import Raw
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from typing import Protocol
+
+    class _Interpolation(Protocol):
+        @property
+        def value(self) -> object: ...
+        @property
+        def conversion(self) -> str | None: ...
+        @property
+        def format_spec(self) -> str: ...
+
+    class _Template(Protocol):
+        def __iter__(self) -> Iterator[str | _Interpolation]: ...
+
+
+# Real `Template` class at runtime (3.14+) for the nested-template check; an
+# empty tuple on older versions makes the isinstance test always False.
+try:
+    from string.templatelib import Template
+
+    _template_classes = (Template,)
+except ImportError:  # Python < 3.14
+    _template_classes = ()
+
+_TEMPLATE_TYPES: tuple[type, ...] = _template_classes
+
+__all__ = ["tex"]
+
+_CONVERSIONS = {"r": repr, "s": str, "a": ascii}
+
+
+def tex(template: _Template) -> TeX:
+    """Render a t-string into a `TeX` tree (see the module docstring)."""
+    parts: list[TeX] = []
+    for item in template:
+        if isinstance(item, str):
+            parts.append(Raw(item))  # literal LaTeX
+        else:
+            parts.append(_coerce(item.value, item.conversion, item.format_spec))
+    return Concat(*parts)
+
+
+def _coerce(value: object, conversion: str | None = None, spec: object = "") -> TeX:
+    if value is None:
+        return Empty
+    if isinstance(value, TeX):
+        return value
+    if isinstance(value, _TEMPLATE_TYPES):
+        return tex(cast("_Template", value))
+    if isinstance(value, (list, tuple)):
+        items = cast("tuple[object, ...] | list[object]", value)
+        return Concat(*(_coerce(item) for item in items))
+    if conversion in _CONVERSIONS:
+        value = _CONVERSIONS[conversion](value)
+    text = format(value, spec if isinstance(spec, str) else "")
+    return Raw(escape_latex(text))

{pytex_preprocessor-0.3.0 → pytex_preprocessor-0.4.1}/src/pytex_analyze/optimize.py

@@ -130,10 +130,24 @@ def _native(raw: Raw) -> TeX:
     return raw
 
 
+_MATH_OPEN = re.compile(r"(\\[\[(])\s+")
+_MATH_CLOSE = re.compile(r"\s+(\\[\])])")
+
+
+def _strip_math_ws(text: str) -> str:
+    r"""Drop whitespace just inside ``\[..\]`` and ``\(..\)``.
+
+    TeX math mode ignores it, so two strings that differ only there render the
+    same — this lets the tokenizer accept a `DisplayMath`/`Math` candidate
+    (which trims that whitespace) as equivalent to the original.
+    """
+    return _MATH_CLOSE.sub(r"\1", _MATH_OPEN.sub(r"\1", text))
+
+
 def _tokenize(raw: Raw) -> TeX | None:
     """Split a `Raw` into literal text and the native nodes for the constructs
-    in `_TOKEN`. Returns `None` when nothing matches or the result would not
-    render identically."""
+    in `_TOKEN`. Returns `None` when nothing matches or the result would change
+    the rendered output (math-delimiter whitespace aside — TeX ignores that)."""
     content = raw.content
     namespace = pytex_namespace(raw.namespace or {})
     parts: list[TeX] = []
@@ -148,7 +162,11 @@ def _tokenize(raw: Raw) -> TeX | None:
     if cursor < len(content):
         parts.append(Raw(content[cursor:], allow_replacements=False))
     candidate = Concat(*(_optimize(part) for part in parts))
-    return candidate if candidate.rendered == raw.rendered else None
+    rendered = candidate.rendered
+    target = raw.rendered
+    if rendered == target or _strip_math_ws(rendered) == _strip_math_ws(target):
+        return candidate
+    return None
 
 
 def _token_node(

{pytex_preprocessor-0.3.0 → pytex_preprocessor-0.4.1}/src/pytex_builder/build.py

@@ -12,6 +12,7 @@ import json
 import re
 import sys
 from dataclasses import dataclass
+from importlib.metadata import PackageNotFoundError, version
 from pathlib import Path
 from typing import TYPE_CHECKING, cast
 
@@ -76,11 +77,21 @@ def _slug(name: str) -> str:
     return name or "document"
 
 
+def _version() -> str:
+    try:
+        return version("pytex-preprocessor")
+    except PackageNotFoundError:
+        return "unknown"
+
+
 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(
+        "--version", action="version", version=f"pytex {_version()}"
+    )
     _ = parser.add_argument(
         "input",
         type=Path,

{pytex_preprocessor-0.3.0 → pytex_preprocessor-0.4.1}/src/pytex_preprocessor.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytex-preprocessor
-Version: 0.3.0
+Version: 0.4.1
 Summary: Type-safe LaTeX document generation with Python
 Author-email: Frederik Beimgraben <frederik@beimgraben.net>
 Requires-Python: >=3.13
@@ -28,6 +28,20 @@ uses.
 
 ## Install
 
+### Prebuilt binary
+
+Each release attaches standalone `pytex` binaries (Linux/macOS/Windows) — no
+Python or `pip` needed. Download one from the
+[Releases](https://github.com/frederikbeimgraben/PyTeX-Preprocessor/releases)
+page, make it executable, and run it. The binary bundles its own interpreter
+plus common data packages (numpy, pandas, openpyxl/calamine for spreadsheets,
+Pillow, PyYAML), so documents can `import` those without installing anything;
+see [`packaging/`](packaging/). It is built on Python 3.14, so documents may use
+`tex(t"...")` even on machines without 3.14. (`--build` still needs `tectonic`,
+which pytex downloads on first use.)
+
+### From PyPI
+
 To use the `pytex` command anywhere, install it as an isolated tool with
 [pipx](https://pipx.pypa.io/):
 
@@ -82,6 +96,22 @@ pytex example.tex.py --build  # render + compile -> build/example.out.pdf
 
 Bare strings are coerced to text nodes and LaTeX-escaped.
 
+### Template strings (Python 3.14+)
+
+On Python 3.14, `pytex.tex` accepts a [PEP 750](https://peps.python.org/pep-0750/)
+template string and builds a `TeX` tree from it. Static parts are literal LaTeX;
+interpolations are LaTeX-escaped when they are plain values and spliced as-is
+when they are `TeX` nodes (nested template strings and lists are handled too):
+
+```py
+from pytex import tex
+
+name = "Q&A: 50%"
+body = tex(t"{Bold('Heading')} — {name}")   # node spliced; name -> "Q\&A: 50\%"
+```
+
+`tex` is only exported on 3.14+; the rest of the library runs on 3.13.
+
 ## The `pytex` command
 
 The input file is dispatched by extension:

{pytex_preprocessor-0.3.0 → pytex_preprocessor-0.4.1}/src/pytex_preprocessor.egg-info/SOURCES.txt

@@ -3,6 +3,7 @@ pyproject.toml
 src/pytex/__init__.py
 src/pytex/packages.py
 src/pytex/registry.py
+src/pytex/template.py
 src/pytex/commands/__init__.py
 src/pytex/commands/biblatex.py
 src/pytex/commands/builtin.py