typst-pyexec 0.0.0__py3-none-any.whl

typst_pyexec/__init__.py

@@ -0,0 +1,6 @@
+"""typst_pyexec — reactive Python execution engine for Typst documents."""
+
+__version__ = "0.1.1"
+__all__ = ["Builder"]
+
+from typst_pyexec.builder import Builder

typst_pyexec/builder.py

@@ -0,0 +1,218 @@
+"""High-level build orchestrator.
+
+Ties together parsing, DAG analysis, scheduling, execution,
+rendering, and document injection.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import subprocess
+import time
+from pathlib import Path
+
+from typst_pyexec.core.cache import CacheStore
+from typst_pyexec.core.dag import DependencyGraph
+from typst_pyexec.core.executor import Executor
+from typst_pyexec.core.kernel import KernelManager
+from typst_pyexec.core.parser import Cell, Parser
+from typst_pyexec.core.renderer import Renderer
+from typst_pyexec.core.scheduler import Scheduler
+from typst_pyexec.utils.hashing import sha256_text
+
+logger = logging.getLogger(__name__)
+
+
+class Builder:
+    """Orchestrates the full build pipeline for a single Typst document.
+
+    Parameters
+    ----------
+    source:
+        Path to the ``.typ`` source file.
+    output_dir:
+        Directory in which to write the intermediate ``.typst_pyexec.typ``
+        file and the ``.typst_pyexec/`` state directory.  Defaults to the
+        directory of *source*.
+    use_cache:
+        Whether to use the disk-based execution cache.
+    n_jobs:
+        Number of parallel workers passed to ``joblib``.
+    compiler:
+        Name / path of the ``typst`` compiler binary.
+    """
+
+    def __init__(
+        self,
+        source: Path,
+        output_dir: Path | None = None,
+        use_cache: bool = True,
+        n_jobs: int = -1,
+        compiler: str = "typst",
+    ) -> None:
+        self.source = source.resolve()
+        self.output_dir = (output_dir or self.source.parent).resolve()
+        self.use_cache = use_cache
+        self.n_jobs = n_jobs
+        self.compiler = compiler
+
+        self._state_dir = self.output_dir / ".typst_pyexec"
+        self._figures_dir = self._state_dir / "figures"
+        self._state_dir.mkdir(parents=True, exist_ok=True)
+        self._figures_dir.mkdir(parents=True, exist_ok=True)
+
+        self._intermediate = self.output_dir / (self.source.stem + ".typst_pyexec.typ")
+
+        self._cache = CacheStore(self._state_dir / "cache")
+        self._kernel = KernelManager(self._state_dir)
+        self._renderer = Renderer(self._figures_dir, self._state_dir)
+
+        self._parser = Parser()
+        self._dag = DependencyGraph()
+        self._scheduler = Scheduler()
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def build(self) -> None:
+        """Run a single build pass."""
+        t0 = time.perf_counter()
+        logger.info("Building %s", self.source)
+
+        previous_cwd = Path.cwd()
+        os.chdir(self.source.parent)
+        try:
+            source_text = self.source.read_text(encoding="utf-8")
+            cells = self._parser.parse(source_text)
+
+            if not cells:
+                logger.info("No Python cells found — copying source verbatim.")
+                self._intermediate.write_text(source_text, encoding="utf-8")
+                self._compile()
+                return
+
+            self._dag.build(cells)
+            groups = self._scheduler.schedule(self._dag)
+
+            executor = Executor(
+                kernel=self._kernel,
+                cache=self._cache if self.use_cache else None,
+                figures_dir=self._figures_dir,
+                working_dir=self.source.parent,
+                n_jobs=self.n_jobs,
+            )
+
+            changed_ids = self._detect_changed_cells(cells)
+            refresh_ids = {
+                c.cell_id
+                for c in cells
+                if _as_bool(c.metadata.get("refresh"), False)
+                and _as_bool(c.metadata.get("execute"), True)
+            }
+            # Regular changes cascade through DAG; refresh-only cells re-run
+            # without cascading to downstream dependents.
+            cells_to_run = self._dag.affected(changed_ids) | refresh_ids
+            logger.info("%d/%d cells need execution", len(cells_to_run), len(cells))
+
+            results = executor.run(cells, groups, cells_to_run, dag=self._dag)
+
+            # Render and inject
+            output_text = self._renderer.inject(source_text, cells, results)
+            self._intermediate.write_text(output_text, encoding="utf-8")
+
+            # Persist notebook
+            self._renderer.sync_notebook(cells, results, self._state_dir / "notebook.ipynb")
+
+            elapsed = (time.perf_counter() - t0) * 1000
+            logger.info("Build finished in %.1f ms", elapsed)
+
+            self._compile()
+        finally:
+            os.chdir(previous_cwd)
+
+    def watch(self) -> None:
+        """Watch the source file and rebuild on every change."""
+        from watchdog.events import FileModifiedEvent, FileSystemEventHandler
+        from watchdog.observers import Observer
+
+        logger.info("Watching %s  (Ctrl-C to stop)", self.source)
+
+        # Initial build
+        try:
+            self.build()
+        except Exception as exc:
+            logger.error("Initial build failed: %s", exc)
+
+        class _Handler(FileSystemEventHandler):
+            def __init__(self, builder: Builder) -> None:
+                self._builder = builder
+
+            def on_modified(self, event: FileModifiedEvent) -> None:  # type: ignore[override]
+                event_path = Path(os.fsdecode(event.src_path)).resolve()
+                if event_path == self._builder.source:
+                    logger.info("Change detected — rebuilding…")
+                    try:
+                        self._builder.build()
+                    except Exception as exc:
+                        logger.error("Rebuild failed: %s", exc)
+
+        observer = Observer()
+        observer.schedule(_Handler(self), str(self.source.parent), recursive=False)
+        observer.start()
+        try:
+            while True:
+                time.sleep(0.5)
+        except KeyboardInterrupt:
+            logger.info("Stopping watcher…")
+        finally:
+            observer.stop()
+            observer.join()
+            self._kernel.shutdown()
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _detect_changed_cells(self, cells: list[Cell]) -> set[str]:
+        """Return IDs of cells whose source hash is not present in cache."""
+        changed: set[str] = set()
+        for cell in cells:
+            if not _as_bool(cell.metadata.get("execute"), True):
+                continue
+            h = sha256_text(cell.source)
+            cached = self._cache.load_by_hash(h)
+            if cached is None:
+                changed.add(cell.cell_id)
+        return changed
+
+    def _compile(self) -> None:
+        """Invoke the Typst compiler on the intermediate document."""
+        cmd = [self.compiler, "compile", str(self._intermediate)]
+        logger.info("Running: %s", " ".join(cmd))
+        try:
+            result = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                timeout=120,
+            )
+            if result.returncode != 0:
+                logger.error(
+                    "Typst compiler error:\n%s", result.stderr or result.stdout
+                )
+            else:
+                logger.info("Compilation successful.")
+        except FileNotFoundError:
+            logger.warning(
+                "Compiler %r not found — skipping compilation step.", self.compiler
+            )
+        except subprocess.TimeoutExpired:
+            logger.error("Typst compiler timed out.")
+
+
+def _as_bool(value: str | None, default: bool) -> bool:
+    if value is None:
+        return default
+    return value.strip().lower() in {"1", "true", "yes", "on"}

typst_pyexec/cli.py

@@ -0,0 +1,114 @@
+"""CLI entry point for typst_pyexec."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+from pathlib import Path
+
+from typst_pyexec.builder import Builder
+from typst_pyexec.utils.logging import configure_logging
+
+
+def _build_command(args: argparse.Namespace) -> None:
+    builder = Builder(
+        source=Path(args.file),
+        output_dir=Path(args.output_dir) if args.output_dir else None,
+        use_cache=not args.no_cache,
+        n_jobs=args.jobs,
+        compiler=args.compiler,
+    )
+    builder.build()
+
+
+def _watch_command(args: argparse.Namespace) -> None:
+    builder = Builder(
+        source=Path(args.file),
+        output_dir=Path(args.output_dir) if args.output_dir else None,
+        use_cache=not args.no_cache,
+        n_jobs=args.jobs,
+        compiler=args.compiler,
+    )
+    builder.watch()
+
+
+def _clean_command(args: argparse.Namespace) -> None:
+    import shutil
+
+    cache_dir = Path(".typst_pyexec")
+    if cache_dir.exists():
+        shutil.rmtree(cache_dir)
+        print(f"Removed {cache_dir}")
+    else:
+        print(f"{cache_dir} not found — nothing to clean.")
+
+
+def _make_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="typst_pyexec",
+        description="Reactive Python execution engine for Typst documents.",
+    )
+    parser.add_argument(
+        "--log-level",
+        default="INFO",
+        choices=["DEBUG", "INFO", "WARNING", "ERROR"],
+        help="Logging verbosity (default: INFO)",
+    )
+
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    # --- build ---
+    build_p = sub.add_parser("build", help="Build document once and exit.")
+    build_p.add_argument("file", help="Path to .typ source file")
+    _add_common_args(build_p)
+    build_p.set_defaults(func=_build_command)
+
+    # --- watch ---
+    watch_p = sub.add_parser("watch", help="Watch for changes and rebuild.")
+    watch_p.add_argument("file", help="Path to .typ source file")
+    _add_common_args(watch_p)
+    watch_p.set_defaults(func=_watch_command)
+
+    # --- clean ---
+    clean_p = sub.add_parser("clean", help="Remove .typst_pyexec/ cache directory.")
+    clean_p.set_defaults(func=_clean_command)
+
+    return parser
+
+
+def _add_common_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument(
+        "--output-dir",
+        default=None,
+        help="Override output directory (default: same as source file)",
+    )
+    p.add_argument(
+        "--no-cache",
+        action="store_true",
+        default=False,
+        help="Disable execution cache",
+    )
+    p.add_argument(
+        "--jobs",
+        type=int,
+        default=-1,
+        help="Number of parallel workers (-1 = all CPUs, default: -1)",
+    )
+    p.add_argument(
+        "--compiler",
+        default="typst",
+        help="Typst compiler command (default: typst)",
+    )
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Entry point for the ``typst_pyexec`` CLI."""
+    parser = _make_parser()
+    args = parser.parse_args(argv)
+    configure_logging(getattr(logging, args.log_level))
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main(sys.argv[1:])

typst_pyexec/core/__init__.py

@@ -0,0 +1 @@
+# typst_pyexec/core/__init__.py

typst_pyexec/core/cache.py

@@ -0,0 +1,110 @@
+"""Disk-based execution cache keyed by SHA-256 of cell source."""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+
+from typst_pyexec.utils.hashing import sha256_text
+
+logger = logging.getLogger(__name__)
+
+_CACHE_SCHEMA_VERSION = 2
+
+
+class CacheStore:
+    """Persistent JSON cache stored under *cache_dir*.
+
+    Each entry is a file named ``<sha256>.json`` and contains the
+    execution result for the cell with that source hash.
+
+    Parameters
+    ----------
+    cache_dir:
+        Directory in which cache files are stored.  Created on demand.
+    """
+
+    def __init__(self, cache_dir: Path) -> None:
+        self._dir = cache_dir
+        self._dir.mkdir(parents=True, exist_ok=True)
+
+    # ------------------------------------------------------------------
+    # Core API
+    # ------------------------------------------------------------------
+
+    def load(self, cell_id: str) -> dict | None:
+        """Return cached entry for *cell_id*, or ``None`` if not found.
+
+        The cache entry is matched by *cell_id* via a lookup file that
+        maps cell IDs to their most-recent hash.
+        """
+        lookup = self._lookup_file(cell_id)
+        if not lookup.exists():
+            return None
+        try:
+            ref = json.loads(lookup.read_text(encoding="utf-8"))
+            h = ref.get("hash")
+            entry_file = self._entry_file(h)
+            if entry_file.exists():
+                return json.loads(entry_file.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError) as exc:
+            logger.debug("Cache miss for %s: %s", cell_id, exc)
+        return None
+
+    def load_by_hash(self, source_hash: str) -> dict | None:
+        """Return cached entry by *source_hash*, or ``None``."""
+        entry_file = self._entry_file(source_hash)
+        if not entry_file.exists():
+            return None
+        try:
+            return json.loads(entry_file.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            return None
+
+    def save(self, cell_id: str, source: str, result: dict) -> None:
+        """Persist *result* for *cell_id* with *source*'s hash as key."""
+        h = sha256_text(source)
+        entry: dict = {
+            "schema_version": _CACHE_SCHEMA_VERSION,
+            "hash": h,
+            "cell_id": cell_id,
+            "stdout": result.get("stdout", ""),
+            "stderr": result.get("stderr", ""),
+            "display_data": result.get("display_data", []),
+            "figures": result.get("figures", []),
+            "figure_metadata": result.get("figure_metadata", []),
+            "error": result.get("error"),
+            "status": result.get("status", "ok"),
+        }
+        entry_file = self._entry_file(h)
+        entry_file.write_text(json.dumps(entry, indent=2), encoding="utf-8")
+
+        # Update the lookup file
+        lookup = self._lookup_file(cell_id)
+        lookup.write_text(json.dumps({"hash": h}), encoding="utf-8")
+
+        logger.debug("Cached cell %s (hash=%s…)", cell_id, h[:8])
+
+    def invalidate(self, cell_id: str) -> None:
+        """Remove the lookup entry for *cell_id* (does not delete the data file)."""
+        lookup = self._lookup_file(cell_id)
+        if lookup.exists():
+            lookup.unlink()
+
+    def clear(self) -> None:
+        """Delete all cache files."""
+        for f in self._dir.iterdir():
+            f.unlink(missing_ok=True)
+        logger.info("Cache cleared.")
+
+    # ------------------------------------------------------------------
+    # Paths
+    # ------------------------------------------------------------------
+
+    def _entry_file(self, source_hash: str) -> Path:
+        return self._dir / f"{source_hash}.json"
+
+    def _lookup_file(self, cell_id: str) -> Path:
+        safe = cell_id.replace("/", "_").replace("\\", "_")
+        return self._dir / f"_id_{safe}.json"