Skip to content

Python Runtime Assets

Python cells execute in a browser worker using Pyodide. Oxiquill resolves the installed Pyodide release and lockfile during generation, downloads only the core files and declared packages that the manifest requires, and publishes them under public/oxiquill/pyodide.

The built site loads those local assets. A reader does not need access to a public CDN after the site has been generated and deployed.

import { defineOxiquillConfig } from 'oxiquill/astro';
export default defineOxiquillConfig({
python: {
offline: process.env.OXIQUILL_OFFLINE === '1',
packageMirror: 'https://packages.example/pyodide/'
},
paths: {
downloadCacheDir: '.cache/oxiquill/downloads/v1'
}
});

offline defaults to false. packageMirror and downloadCacheDir accept either a string or URL. TypeScript consumers can import OxiquillPythonOptions and OxiquillPathOptions from oxiquill/astro.

Set python: { preload: true } to prepare Python as soon as the page DOM is ready. The default is false; this documentation site enables it. Pages without Python cells do not start a Python worker. Preparation uses only the first Python cell’s declared packages and does not execute authored code. Button cells still wait for Run, and reactive and autorun cells retain their visible hydration behavior.

The first request passes its declared packages into Pyodide initialization so their downloads overlap runtime startup. Preparation and execution share one worker, one initialization promise, and a serial queue. Later cells load additional declared packages and discover imports before execution. The UI distinguishes Preparing Python… from Running. A failed preparation can be retried by running a cell; cancellation, timeout, and runtime reset clear the worker and preparation state together.

Browser assets remain on the site’s origin and respect its base path, including /oxiquill/. This option adds no CDN dependency, service worker, custom Pyodide distribution, or persistent browser cache. Normal HTTP caching still applies. Display helpers use pandas and Matplotlib only when authored imports have loaded them; Matplotlib keeps the noninteractive Agg backend and automatic figure collection.

For local profiling, browser User Timing entries named oxiquill:<phase>:<cell-id> record hydration, worker startup, initialization, display support, package loading, import discovery, execution, and output rendering. Initialization entries use python as their ID. Entries retain the latest measurement per phase and cell and are never sent to a server. The repository’s tests/performance/python-startup.mjs measures fresh contexts, reloads, and repeated runs against a gzip-served production build.

For each wheel, Oxiquill takes the filename, release location, and expected SHA-256 from the installed pyodide-lock.json. A configured mirror changes only the download base; it never weakens or replaces the lockfile hash.

Downloads use this sequence:

  1. Check the versioned Oxiquill download cache.
  2. Verify a cached file against its expected SHA-256 before use.
  3. If it is missing or corrupt and offline mode is disabled, stream the response to a uniquely named temporary file while incrementally calculating SHA-256.
  4. Process at most four core files and wheels concurrently. Retries remain inside the same worker slot, use a 30-second timeout, and make no more than three total attempts with bounded backoff.
  5. Verify the completed temporary file, then atomically claim its cache name. Concurrent generators reuse the verified winner instead of overwriting it with partial content.
  6. After every required cache entry is verified, copy artifacts into the resolved public Pyodide directory in deterministic order.

A hash mismatch is always fatal for that source. A failed, interrupted, or aborted operation removes its temporary files. Oxiquill never publishes or caches an unverified partial response, and public staging does not begin until every required cache entry is ready.

The default cache layout is .cache/oxiquill/downloads/v1/pyodide/<pyodide-version>/<lock-sha256>/<filename>. A Pyodide version or lockfile-byte change selects a new namespace, so files from incompatible releases are not reused. Every core asset and wheel is also checked against its expected SHA-256 before use.

Preserve the cache between local or CI builds to avoid repeat network work. oxiquill clean removes generated .oxiquill, public runtime, and build output but deliberately preserves downloadCacheDir. A later generation, including offline generation, can reconstruct public/oxiquill/pyodide from the verified cache.

If a cache entry is corrupt, remove that named entry or run online generation again; Oxiquill detects the mismatch before use. Cache diagnostics include the filename, cache path, and expected hash.

Configure a Pyodide package mirror when the default CDN is unavailable or policy requires an internal source. The mirror must expose the same release filenames. Integrity always comes from the installed lockfile, not from mirror metadata.

Mirror failures report the effective URL and distinguish DNS/connection failures, HTTP status failures, timeout, retry exhaustion, and SHA-256 mismatch. Switching mirrors does not require changing authored packages metadata.

Offline generation performs no package download. Every required core asset and wheel must already be present in the verified cache. A miss fails with the missing filename and expected SHA-256 so the cache can be populated on a connected machine and transferred without guesswork.

Use offline mode only after an online generation has completed for the same Oxiquill, Pyodide, manifest, and package set. Browser execution remains offline-capable because the deployed site serves the copied assets locally.

The Python runtime fingerprint records the Pyodide version, lockfile hash, core-asset hashes, selected package name/version/dependency/file/hash metadata, and the sorted requested package set. Changing any of these semantic inputs regenerates the published runtime. Cache reuse is narrower: its version-and-lock namespace can reuse any still-valid file even when the requested package subset changes.

Python packages must be a non-empty, unique list of names vendored by the installed Pyodide release. Generation rejects unknown names before downloading. Imports discovered from source may load packages already present in the published runtime, but release builds should declare non-core dependencies explicitly for deterministic preflight and caching.

See Interactive Cells for metadata and Troubleshooting for recovery steps.

python.additionalPackages extends the built-in allowlist with packages from the installed Pyodide lock. Each entry pins the notice to that package’s exact version and supplies complete license text files, relative to the workspace root:

python: {
additionalPackages: {
sympy: {
version: '1.14.0',
license: 'BSD-3-Clause AND MIT',
licenseFiles: ['legal/sympy-LICENSES.txt']
},
mpmath: {
version: '1.4.1',
license: 'BSD-3-Clause',
licenseFiles: ['legal/mpmath-LICENSES.txt']
}
}
}

A cell can then declare packages: [sympy]. Generation resolves mpmath from the lock and verifies both notices. Supply notices for every additional dependency; existing bundled notices cover built-in dependencies. Copy complete notices from the verified distribution, including bundled components. Unknown packages, version mismatches, missing or empty notice files, and hash mismatches fail generation.

Allowing a package does not distribute it. Only declared packages and their dependencies are copied. For Pyodide 314.0.7, the verified SymPy and mpmath wheels add 4,616,552 bytes together. Their names, versions, hashes, and notice contents participate in runtime invalidation. Development watches notice changes and reloads Python configuration changes. The same package set is used for imports, preload, mirrors, offline generation, and the final third-party report. Arbitrary PyPI URLs and runtime network fallback are not supported.

display_table reads at most 10,001 rows and 101 values per row to detect truncation, retaining at most 10,000 rows and 100 columns. This also applies to generators. DataFrame index columns count toward the column limit. Discarded columns are not converted.

The table reports a total only when it is known. A truncated iterator shows total unknown, and CSV downloads contain only retained rows. If iteration raises an exception, completed rows remain available alongside a conversion diagnostic.

Every Python execution starts with fresh display state. Matplotlib figures are closed after execution, including failures, so a failed cell cannot contribute figures to a later cell.

When execution raises an exception, bounded print, display, and figure output is shown under Output from the failed execution. A previous successful result remains separate. Starting another execution clears the failure diagnostics. Output recovery is best effort: collecting a figure must not replace the original error, and terminating or timing out a worker cannot recover output it has not sent.

Enable python: { experimentalSetup: true } to reuse a page-local Python cell as setup. The default is disabled. A setup reference must name one Python cell without inputs; chained references execute in dependency order. Missing references, references outside the page, and cycles fail generation.

Python + Pyodide

Common data preparation

Cell actions
from math import sqrt

samples = [sqrt(value) for value in range(1, 101)]
print("Setup completed")

Run the cell to show its output.

Python + Pyodide

Mean from reproducible setup

Cell actions
Cell inputs
print(f"Mean: {scale * sum(samples) / len(samples):.6f}")

Run the cell to show its output.

Python + Pyodide

Range from reproducible setup

Cell actions
print(f"Range: {min(samples):.1f} to {max(samples):.1f}")

Run the cell to show its output.

Each execution creates new globals, executes setup, injects the reader’s inputs, and executes the body. Reader inputs override setup bindings with the same names. Setup runs again after retries, resets, and worker replacement; execution order does not supply state. Its declared packages are included in the consumer cell’s manifest and preload set. The total request timeout is the sum of the setup and body timeouts.

Successful setup logs, displays, return values, and figures are discarded. A failing setup stops the body and exposes only that failed stage’s bounded diagnostics. Running the setup cell directly still displays its own output. Reader edits remain local drafts and do not change another cell’s authored setup.

This experiment removes duplicated preparation source; it does not reuse results from a previous cell. Modules still share the worker’s interpreter, so setup must explicitly initialize state it relies on. The repository includes a warm-run timing comparison in tests/performance/python-setup.mjs; the feature remains opt-in while its cost is evaluated.