typst-pyexec 0.0.0__tar.gz

typst_pyexec-0.0.0/.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - "**"
+  pull_request:
+
+jobs:
+  test-and-quality:
+    name: ${{ matrix.os }} / py${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Ruff lint
+        run: uv run ruff check .
+
+      - name: Black auto-format
+        run: uv run black typst_pyexec tests
+
+      - name: Black format check
+        run: uv run black --check typst_pyexec tests
+
+      - name: Mypy
+        run: uv run mypy typst_pyexec
+
+      - name: Pytest
+        env:
+          typst_pyexec_SKIP_KERNEL_TESTS: "1"
+        run: uv run pytest --cov=typst_pyexec --cov-report=term-missing --cov-report=xml
+
+      - name: Upload coverage XML
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11'
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-xml
+          path: coverage.xml

typst_pyexec-0.0.0/.github/workflows/release.yml

@@ -0,0 +1,50 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: update version
+        run: uv version "${GITHUB_REF_NAME#v}"
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*
+
+  publish:
+    runs-on: ubuntu-latest
+    needs: build
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

typst_pyexec-0.0.0/.gitignore

@@ -0,0 +1,9 @@
+*__pycache__
+*.typst_pyexec*
+*.venv
+*.pytest_cache
+*.mypy*
+*.ruff*
+*dist
+*coverage*
+*report

typst_pyexec-0.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michel Jean Joseph Donnet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

typst_pyexec-0.0.0/PKG-INFO

@@ -0,0 +1,235 @@
+Metadata-Version: 2.4
+Name: typst_pyexec
+Version: 0.0.0
+Summary: Reactive Python execution engine for Typst documents
+Author: typst_pyexec contributors
+License: MIT
+License-File: LICENSE
+Keywords: jupyter,notebook,python,reactive,typst
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Text Processing :: Markup
+Requires-Python: >=3.10
+Requires-Dist: black>=24.0
+Requires-Dist: ipykernel>=6.0
+Requires-Dist: joblib>=1.3
+Requires-Dist: jupyter-client>=8.0
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: nbformat>=5.9
+Requires-Dist: pandas>=2.0
+Requires-Dist: watchdog>=3.0
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.1; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# typst_pyexec
+
+typst_pyexec is a reactive Python execution engine for Typst documents.
+
+It executes Python fences inside `.typ` files, captures outputs (stdout, figures, tables), and injects rendered Typst markup into an intermediate file (`*.typst_pyexec.typ`) that can be compiled directly.
+
+## Core Capabilities
+
+- Reactive dependency graph based on Python AST analysis
+- Incremental execution with source-hash cache
+- Persistent Jupyter kernel between builds
+- Automatic cold-kernel hydration for dependency prerequisites
+- Matplotlib figure export to SVG with PNG fallback
+- Subfigure reconstruction via `figure(grid(...))`
+- DataFrame HTML rendering to Typst `#table(...)`
+- Watch mode with automatic rebuilds
+
+## Installation
+
+```bash
+pip install typst_pyexec
+```
+
+For development:
+
+```bash
+uv sync --extra dev
+```
+
+## CLI Usage
+
+Build once:
+
+```bash
+typst_pyexec build document.typ
+```
+
+Watch and rebuild on save:
+
+```bash
+typst_pyexec watch document.typ
+```
+
+Clean local state directory:
+
+```bash
+typst_pyexec clean
+```
+
+Common options:
+
+- `--output-dir <dir>`: write intermediate/state outputs to a custom folder
+- `--no-cache`: disable cache lookups and force execution
+- `--jobs <n>`: reserved for future multi-kernel scheduling (`-1` default)
+- `--compiler <cmd>`: Typst compiler binary name/path (default `typst`)
+
+## Block Options (`%|`)
+
+Place options at the top of a Python fence:
+
+````typst
+```python
+%| echo: false
+%| raw: true
+%| figure: true
+print("hello")
+```
+````
+
+Supported options:
+
+- `execute` (default `true`): skip execution when `false`
+- `refresh` (default `false`): force this cell to run every build
+- `echo` (default `true`): show or hide source code
+- `raw` (default `true`): show or hide textual runtime output (`stdout`, traceback, `text/plain` display bundles)
+- `figure` (default `true`): show or hide rendered figures
+- `caption`: explicit figure caption override
+- `label`: Typst label for cross-references
+- `keep-subplots` (default `false`): preserve multi-axis plot as one image
+- `img-*`: passthrough kwargs for Typst `image(...)`
+- `fig-*`: passthrough kwargs for Typst `figure(...)`
+- `grid-*`: passthrough kwargs for Typst `grid(...)`
+
+Behavior notes:
+
+- `cell_id` is internal and generated automatically.
+- Option-only edits do not invalidate cache because cache keys are based on Python source.
+- To re-run on option updates, set `refresh: true`.
+
+## Figure and Caption Behavior
+
+- For single-axis plots, title text is promoted into Typst caption when `caption` is not set.
+- For subplot grids, each axis title becomes child caption; suptitle becomes outer caption.
+- Title text is removed from exported images after promotion to captions.
+- If SVG export fails and PNG is emitted, renderer auto-resolves PNG paths in final Typst output.
+
+## How It Works
+
+1. Parse Python fences from Typst source
+2. Build def/use DAG from AST
+3. Compute changed cells from source-hash cache
+4. Execute required cells in topological groups
+5. Capture stdout, display bundles, and figure artifacts
+6. Render Typst fragments per cell
+7. Inject into `document.typst_pyexec.typ`
+8. Compile with Typst compiler
+
+## Local State
+
+typst_pyexec writes runtime state into `.typst_pyexec/`:
+
+- `kernel_connection.json`: reconnect data for persistent kernel
+- `cache/`: JSON entries keyed by SHA-256 of cell source
+- `figures/`: SVG/PNG artifacts
+- `notebook.ipynb`: synchronized notebook representation
+
+## Development Quality Gates
+
+Run checks locally:
+
+```bash
+uv run ruff check .
+uv run black --check typst_pyexec tests
+uv run mypy typst_pyexec
+uv run pytest
+```
+
+## CI/CD (GitHub Actions)
+
+- `CI`: matrix on Ubuntu and Windows, Python 3.10-3.12, with lint + format + type-check + tests + coverage artifact
+- `Release`: tag-driven (`v*.*.*`) build and publish workflow for PyPI using trusted publishing
+
+Workflows are in:
+
+- `.github/workflows/ci.yml`
+- `.github/workflows/release.yml`
+
+## Publish to PyPI
+
+typst_pyexec is already configured for trusted publishing through GitHub Actions.
+
+Release steps:
+
+1. Bump version in `pyproject.toml` and `typst_pyexec/__init__.py`.
+2. Commit and push to main.
+3. Create and push a version tag:
+
+```bash
+git tag v0.1.1
+git push origin v0.1.1
+```
+
+4. GitHub Actions runs `.github/workflows/release.yml` and publishes to PyPI.
+
+Pre-tag checklist:
+
+1. `python -m pytest -q` is green.
+2. `python -m build` succeeds.
+3. `python -m twine check dist/*` passes.
+4. Version matches in `pyproject.toml` and `typst_pyexec/__init__.py`.
+5. Git tag matches that version (`vX.Y.Z`).
+
+Local preflight checks before tagging:
+
+```bash
+python -m build
+python -m twine check dist/*
+```
+
+If you prefer token-based manual publishing:
+
+```bash
+python -m twine upload dist/*
+```
+
+## Use in Other Repositories
+
+After publishing, install as a normal dependency.
+
+With pip:
+
+```bash
+pip install typst_pyexec
+```
+
+With uv (project dependency):
+
+```bash
+uv add typst_pyexec
+```
+
+With uvx (run CLI without adding dependency):
+
+```bash
+uvx typst_pyexec build document.typ
+```
+
+## License
+
+MIT

typst_pyexec-0.0.0/README.md

@@ -0,0 +1,200 @@
+# typst_pyexec
+
+typst_pyexec is a reactive Python execution engine for Typst documents.
+
+It executes Python fences inside `.typ` files, captures outputs (stdout, figures, tables), and injects rendered Typst markup into an intermediate file (`*.typst_pyexec.typ`) that can be compiled directly.
+
+## Core Capabilities
+
+- Reactive dependency graph based on Python AST analysis
+- Incremental execution with source-hash cache
+- Persistent Jupyter kernel between builds
+- Automatic cold-kernel hydration for dependency prerequisites
+- Matplotlib figure export to SVG with PNG fallback
+- Subfigure reconstruction via `figure(grid(...))`
+- DataFrame HTML rendering to Typst `#table(...)`
+- Watch mode with automatic rebuilds
+
+## Installation
+
+```bash
+pip install typst_pyexec
+```
+
+For development:
+
+```bash
+uv sync --extra dev
+```
+
+## CLI Usage
+
+Build once:
+
+```bash
+typst_pyexec build document.typ
+```
+
+Watch and rebuild on save:
+
+```bash
+typst_pyexec watch document.typ
+```
+
+Clean local state directory:
+
+```bash
+typst_pyexec clean
+```
+
+Common options:
+
+- `--output-dir <dir>`: write intermediate/state outputs to a custom folder
+- `--no-cache`: disable cache lookups and force execution
+- `--jobs <n>`: reserved for future multi-kernel scheduling (`-1` default)
+- `--compiler <cmd>`: Typst compiler binary name/path (default `typst`)
+
+## Block Options (`%|`)
+
+Place options at the top of a Python fence:
+
+````typst
+```python
+%| echo: false
+%| raw: true
+%| figure: true
+print("hello")
+```
+````
+
+Supported options:
+
+- `execute` (default `true`): skip execution when `false`
+- `refresh` (default `false`): force this cell to run every build
+- `echo` (default `true`): show or hide source code
+- `raw` (default `true`): show or hide textual runtime output (`stdout`, traceback, `text/plain` display bundles)
+- `figure` (default `true`): show or hide rendered figures
+- `caption`: explicit figure caption override
+- `label`: Typst label for cross-references
+- `keep-subplots` (default `false`): preserve multi-axis plot as one image
+- `img-*`: passthrough kwargs for Typst `image(...)`
+- `fig-*`: passthrough kwargs for Typst `figure(...)`
+- `grid-*`: passthrough kwargs for Typst `grid(...)`
+
+Behavior notes:
+
+- `cell_id` is internal and generated automatically.
+- Option-only edits do not invalidate cache because cache keys are based on Python source.
+- To re-run on option updates, set `refresh: true`.
+
+## Figure and Caption Behavior
+
+- For single-axis plots, title text is promoted into Typst caption when `caption` is not set.
+- For subplot grids, each axis title becomes child caption; suptitle becomes outer caption.
+- Title text is removed from exported images after promotion to captions.
+- If SVG export fails and PNG is emitted, renderer auto-resolves PNG paths in final Typst output.
+
+## How It Works
+
+1. Parse Python fences from Typst source
+2. Build def/use DAG from AST
+3. Compute changed cells from source-hash cache
+4. Execute required cells in topological groups
+5. Capture stdout, display bundles, and figure artifacts
+6. Render Typst fragments per cell
+7. Inject into `document.typst_pyexec.typ`
+8. Compile with Typst compiler
+
+## Local State
+
+typst_pyexec writes runtime state into `.typst_pyexec/`:
+
+- `kernel_connection.json`: reconnect data for persistent kernel
+- `cache/`: JSON entries keyed by SHA-256 of cell source
+- `figures/`: SVG/PNG artifacts
+- `notebook.ipynb`: synchronized notebook representation
+
+## Development Quality Gates
+
+Run checks locally:
+
+```bash
+uv run ruff check .
+uv run black --check typst_pyexec tests
+uv run mypy typst_pyexec
+uv run pytest
+```
+
+## CI/CD (GitHub Actions)
+
+- `CI`: matrix on Ubuntu and Windows, Python 3.10-3.12, with lint + format + type-check + tests + coverage artifact
+- `Release`: tag-driven (`v*.*.*`) build and publish workflow for PyPI using trusted publishing
+
+Workflows are in:
+
+- `.github/workflows/ci.yml`
+- `.github/workflows/release.yml`
+
+## Publish to PyPI
+
+typst_pyexec is already configured for trusted publishing through GitHub Actions.
+
+Release steps:
+
+1. Bump version in `pyproject.toml` and `typst_pyexec/__init__.py`.
+2. Commit and push to main.
+3. Create and push a version tag:
+
+```bash
+git tag v0.1.1
+git push origin v0.1.1
+```
+
+4. GitHub Actions runs `.github/workflows/release.yml` and publishes to PyPI.
+
+Pre-tag checklist:
+
+1. `python -m pytest -q` is green.
+2. `python -m build` succeeds.
+3. `python -m twine check dist/*` passes.
+4. Version matches in `pyproject.toml` and `typst_pyexec/__init__.py`.
+5. Git tag matches that version (`vX.Y.Z`).
+
+Local preflight checks before tagging:
+
+```bash
+python -m build
+python -m twine check dist/*
+```
+
+If you prefer token-based manual publishing:
+
+```bash
+python -m twine upload dist/*
+```
+
+## Use in Other Repositories
+
+After publishing, install as a normal dependency.
+
+With pip:
+
+```bash
+pip install typst_pyexec
+```
+
+With uv (project dependency):
+
+```bash
+uv add typst_pyexec
+```
+
+With uvx (run CLI without adding dependency):
+
+```bash
+uvx typst_pyexec build document.typ
+```
+
+## License
+
+MIT

typst_pyexec-0.0.0/examples/demo.typ

@@ -0,0 +1,102 @@
+= typst_pyexec Example — Python Output, Plots and Tables
+
+#set document(title: "typst_pyexec Demo", author: "typst_pyexec")
+#set page(numbering: "1")
+
+== Scalar and array output
+
+```python
+import numpy as np
+import pandas as pd
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+print("Libraries loaded.")
+```
+
+```python
+arr = np.arange(10)
+print(arr)
+```
+
+== Reactive dependency demo
+
+If you change `cell_scalar` below, only `cell_derived` will re-execute.
+`cell_array` (no dependency on `x`) stays cached.
+
+```python
+x = 7
+print(f"x = {x}")
+```
+
+```python
+y = x ** 2
+print(f"y = x**2 = {y}")
+```
+
+== Simple plot
+
+```python
+%| label: fig-trig
+fig, ax = plt.subplots()
+t = np.linspace(0, 2 * np.pi, 200)
+ax.plot(t, np.sin(t), label="sin(t)")
+ax.plot(t, np.cos(t), label="cos(t)")
+ax.legend()
+ax.set_title("Trigonometric functions")
+plt.show()
+```
+
+== Multi-panel figure (subfigures)
+
+```python
+%| img-width: 100%
+%| label: fig-multipanel
+fig, axes = plt.subplots(1, 2, figsize=(8, 3))
+axes[0].plot([1, 2, 3], [1, 4, 8])
+axes[0].set_title("Quadratic")
+axes[1].bar(["A", "B", "C"], [3, 1, 4])
+axes[1].set_title("Bar chart")
+plt.tight_layout()
+plt.show()
+```
+
+== Pandas DataFrame table
+
+```python
+df = pd.DataFrame({
+    "Name": ["Alice", "Bo", "Carol"],
+    "Score": [95, 87, 92],
+    "Grade": ["A", "B+", "A-"],
+})
+df
+```
+
+== Adding a new cell — no recomputation of previous cells
+
+The cell below is independent of all prior cells.  If you add it
+to an existing document, typst_pyexec will execute only *this* cell because
+all previous cells are served from the SHA-256 cache.
+
+```python
+msg = "I was added later and ran independently!"
+print(msg)
+print("Coucou")
+```
+
+```python
+test = np.arange(5)
+print("Coucou")
+print(test)
+```
+
+```python
+%| label: test
+plt.figure()
+plt.title("Gnyajaja")
+plt.plot(np.arange(6), np.arange(6))
+plt.show()
+```
+
+Here is some coucou in @test and in @fig-multipanel-a
+The code is amazing because the rebuild is very fast

typst_pyexec-0.0.0/examples/persistent_kernel.typ

@@ -0,0 +1,42 @@
+= Persistent Kernel Demo
+
+Imports defined in an earlier cell are available in all later cells
+because the Jupyter kernel's namespace is preserved across builds.
+
+```python
+import numpy as np
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+print("numpy version:", np.__version__)
+```
+
+```python
+# np is already in the kernel namespace from the `imports` cell.
+result = np.sqrt(np.array([1, 4, 9, 16, 25]))
+print("Square roots:", result)
+```
+
+```python
+%| caption: Matplotlib reuses imported namespace
+x = np.linspace(0, 10, 300)
+plt.plot(x, np.exp(-0.3 * x) * np.sin(x))
+plt.title("Damped oscillation")
+plt.xlabel("t")
+plt.ylabel("f(t)")
+plt.show()
+```
+
+== Adding a new cell later
+
+If you add the cell below *after* an initial build, typst_pyexec will:
+
+1. Detect that the new cell is not in the cache.
+2. Execute only the new cell (imports cell is cached — kernel already has `np`).
+3. Re-use the live kernel namespace so `np` is available immediately.
+
+```python
+# This cell was added in a second build but imports still work.
+arr = np.random.default_rng(0).integers(0, 100, size=5)
+print("Random integers:", arr)
+```