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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytex-preprocessor
-Version: 0.3.0
+Version: 0.4.0
 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.0}/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.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pytex-preprocessor"
-version = "0.3.0"
+version = "0.4.0"
 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.0}/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.4.0/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.0}/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.0}/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.0
 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.0}/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