denosaurs 0.1.0__tar.gz

denosaurs-0.1.0/.github/workflows/benchmarks.yml

@@ -0,0 +1,32 @@
+name: Benchmarks
+
+# Informational only -- reports numbers in the log/summary, never fails the build.
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  benchmarks:
+    # macos-latest: the Linux cdylib build currently fails to link V8 (rust-lld
+    # TLS relocation vs -shared, tracked separately, pre-existing/unrelated to
+    # benchmarking) -- same failure as the v0.1.0 Linux wheel build.
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: astral-sh/setup-uv@v7
+
+      - name: Rust benchmarks (Criterion)
+        run: cargo bench --features bench | tee -a "$GITHUB_STEP_SUMMARY"
+
+      - name: Build release extension
+        run: |
+          uv sync --group all
+          uv run maturin develop --uv --release
+
+      - name: Python benchmarks (pytest-benchmark)
+        run: uv run pytest benches_py/ --benchmark-only | tee -a "$GITHUB_STEP_SUMMARY"

denosaurs-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,53 @@
+name: Documentation
+
+on:
+  # push:
+  #   branches:
+  #     - main
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.x"
+
+      - uses: astral-sh/setup-uv@v7
+
+      - name: Install dependencies
+        run: uv sync --no-install-project --group docs
+
+      - name: Build documentation
+        run: source .venv/bin/activate && mkdocs build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: ./site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

denosaurs-0.1.0/.github/workflows/workflow.yaml

@@ -0,0 +1,90 @@
+name: Publish to PyPI
+
+# Runs only when a GitHub Release is published -- never on every push.
+# Actually publishing requires PyPI Trusted Publishing to be configured for
+# this exact repo + workflow on the PyPI project page first (see README).
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  linux:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        target: [x86_64]
+    steps:
+      - uses: actions/checkout@v5
+      - name: Build manylinux wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          args: --release --out dist --find-interpreter
+          # v8 >=150.1 (pulled in via deno_core >=0.409, see Cargo.toml) needs
+          # glibc's memfd_create (glibc >=2.27), which manylinux2014's glibc
+          # 2.17 lacks ("auto" resolved to manylinux2014 and the resulting
+          # wheel failed to import: "undefined symbol: memfd_create").
+          # manylinux_2_28 ships glibc 2.28.
+          manylinux: 2_28
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-linux-${{ matrix.target }}
+          path: dist
+
+  macos:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: PyO3/maturin-action@v1
+        with:
+          args: --release --out dist --find-interpreter
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-macos
+          path: dist
+
+  windows:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: PyO3/maturin-action@v1
+        with:
+          args: --release --out dist --find-interpreter
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-windows
+          path: dist
+
+  sdist:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-sdist
+          path: dist
+
+  publish:
+    name: Publish to PyPI (Trusted Publishing)
+    needs: [linux, macos, windows, sdist]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/denosaurs
+    permissions:
+      id-token: write  # required for PyPI Trusted Publishing (OIDC) -- no API token secret needed
+    steps:
+      - uses: actions/download-artifact@v6
+        with:
+          pattern: wheels-*
+          path: dist
+          merge-multiple: true
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

denosaurs-0.1.0/.gitignore

@@ -0,0 +1,72 @@
+/target
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+.pytest_cache/
+*.py[cod]
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+.venv/
+env/
+bin/
+build/
+develop-eggs/
+dist/
+eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+include/
+man/
+venv/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+pip-selfcheck.json
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.cache
+nosetests.xml
+coverage.xml
+
+# Translations
+*.mo
+
+# Mr Developer
+.mr.developer.cfg
+.project
+.pydevproject
+
+# Rope
+.ropeproject
+
+# Django stuff:
+*.log
+*.pot
+
+.DS_Store
+
+# Sphinx documentation
+docs/_build/
+
+# PyCharm
+.idea/
+
+# VSCode
+.vscode/
+
+# Pyenv
+.python-version

denosaurs-0.1.0/BENCHMARKS.md

@@ -0,0 +1,68 @@
+# Benchmarks
+
+Two suites: Rust-level (Criterion, `benches/`, bypasses the Python API) and
+Python-level (pytest-benchmark, `benches_py/`, the real user-facing surface).
+Both run in CI on every push/PR (`.github/workflows/benchmarks.yml`),
+informational only -- they report numbers, they don't gate merges.
+
+Numbers below are one real measured run, not simulated. They are
+environment-dependent -- re-run locally before trusting them for a regression
+decision on different hardware.
+
+## Measurement environment
+
+- Apple M2, 8 cores, 16 GB RAM, macOS 25.5.0 (Darwin), arm64
+- Rust 1.93.1, `cargo bench --features bench` (release/`bench` profile)
+- Python 3.14.3, `pytest-benchmark` 5.3.0, `maturin develop --release`
+
+## Rust (Criterion, `cargo bench --features bench`)
+
+| Benchmark | Time |
+|---|---|
+| `isolate_creation_and_close` | 2.52 ms |
+| `simple_eval_throughput` (`1 + 41`) | 4.20 µs |
+| `host_callback_op_dispatch` (real Python callable via `register_op`) | 13.14 µs |
+| `termination_handle/is_terminated_check` | 0.92 ns |
+| `termination_handle/terminate_round_trip` (idle runtime) | 87.16 µs |
+
+`is_terminated()` is a single atomic load -- effectively free to poll. The
+206x-larger `terminate_round_trip` number is the cost of the full path:
+requesting termination, calling `v8::IsolateHandle::terminate_execution()`,
+and waiting for the runtime thread to acknowledge shutdown.
+
+## Python (`pytest-benchmark`, `pytest benches_py/ --benchmark-only`)
+
+| Benchmark | Mean |
+|---|---|
+| `test_cold_start` (new `Runtime()` + one eval) | 2.82 ms |
+| `test_steady_state_100_evals` (100 sequential evals, warm runtime) | 363.25 µs total (~3.63 µs/eval) |
+| `test_steady_state_1000_evals` (1000 sequential evals, warm runtime) | 3.46 ms total (~3.46 µs/eval) |
+| `test_host_callback_round_trip` (`bind_function` + call from JS) | 13.98 µs |
+| `test_normal_completing_eval_baseline` | 3.77 µs |
+| `test_watchdog_termination_overhead` | 59.62 ms |
+
+Per-eval cost at the Python layer (~3.5-3.8 µs) matches the Rust-level
+`simple_eval_throughput` number closely -- the Python binding adds negligible
+overhead over the raw `RuntimeHandle`.
+
+### Watchdog-termination proof, timed precisely
+
+`test_watchdog_termination_overhead` runs the exact scenario in
+`tests/test_termination_handle.py`: a runaway `while(true){}` eval, killed
+from a separate watchdog thread via `TerminationHandle.terminate()`, but with
+the watchdog's sleep shortened to 50 ms (20 rounds) so the suite stays fast.
+Measured mean: 59.62 ms. Subtracting the artificial 50 ms delay leaves
+**~9.6 ms** of real overhead for the cross-thread termination path itself
+(watchdog wakes up, calls into V8's isolate handle from a foreign thread,
+the runtime thread unwinds and returns control to Python) -- consistent with
+the Rust-level `terminate_round_trip` number once you add Python's own
+call/exception overhead on top.
+
+## Reproducing
+
+```bash
+cargo bench --features bench
+uv sync --group all
+uv run maturin develop --uv --release
+uv run pytest benches_py/ --benchmark-only
+```