Python runtime asset

Python cell は Pyodide を使う browser worker 内で実行されます。Oxiquill は generation 時に install 済み Pyodide release と lockfile を解決し、manifest が必要とする core file と declared package だけを download して public/oxiquill/pyodide に公開します。

built site はこの local asset を読みます。site の生成・deploy 後、reader が public CDN に接続する必要はありません。

設定

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 の default は false です。packageMirror と downloadCacheDir は string または URL を受け取ります。TypeScript consumer は OxiquillPythonOptions と OxiquillPathOptions を oxiquill/astro から import できます。

Browser の準備

python: { preload: true } を設定すると、page の DOM が準備できた時点で Python の準備を始めます。default は false で、この documentation site では有効にしています。Python cell がない page では Python worker を起動しません。準備対象は最初の Python cell の declared packages だけで、執筆した code は実行しません。button cell は引き続き「実行」を待ち、reactive / autorun cell の visible hydration も維持します。

最初の request の declared packages を Pyodide initialization に渡し、download と runtime startup を重ねます。準備と実行は同じ worker、initialization promise、serial queue を使います。後続 cell の追加 package と source の import discovery は実行前に処理します。UI は「Python を準備中…」と「実行中…」を区別します。準備に失敗しても cell の実行で再試行でき、cancel、timeout、runtime reset は worker と準備状態を一緒に破棄します。

Browser asset は同一 origin から読み込み、/oxiquill/ を含む site base path に従います。CDN、service worker、custom Pyodide distribution、永続 browser cache は追加しません。通常の HTTP cache は利用します。表示 helper は執筆した import が読み込んだ pandas / Matplotlib だけを使います。Matplotlib の非対話 Agg backend と figure の自動回収は維持します。

ローカルでの分析には oxiquill:<phase>:<cell-id> という browser User Timing entry を利用できます。hydration、worker startup、initialization、display support、package loading、import discovery、execution、output rendering を記録し、initialization の ID は python です。各 phase / cell の最新計測だけを保持し、server への送信は行いません。repository の tests/performance/python-startup.mjs は gzip 配信した production build で fresh context、reload、同じ page での再実行を計測します。

検証付き download

各 wheel の filename、release location、expected SHA-256 は install 済み pyodide-lock.json から取得します。mirror setting が変えるのは download base だけで、lockfile hash を弱めたり置き換えたりしません。

download は次の順序で行います。

1. versioned Oxiquill download cache を確認します。
2. cached file を expected SHA-256 で検証します。
3. missing/corrupt で offline mode が無効なら、response を uniquely named temporary file へ stream しながら SHA-256 を incremental に計算します。
4. core file と wheel は同時に最大4件まで処理します。retry は同じ worker slot 内で行い、30秒 timeout と bounded backoff を使って試行は合計3回までです。
5. completed temporary file を検証してから cache name を atomic に claim します。複数の generator が同時に動く場合、loser は partial content で上書きせず verified winner を再利用します。
6. 必要な cache entry をすべて検証した後、artifact を deterministic な順序で resolved public Pyodide directory へ copy します。

hash mismatch は常にその source の fatal error です。failed/interrupted/aborted operation は temporary file を削除します。未検証の partial response を publish/cache せず、必要な cache entry がすべて揃うまで public staging を開始しません。

Cache の動作

default cache layout は .cache/oxiquill/downloads/v1/pyodide/<pyodide-version>/<lock-sha256>/<filename> です。Pyodide version または lockfile byte が変わると新しい namespace を使うため、互換性のない release の file は再利用されません。各 core asset と wheel も利用前に expected SHA-256 で検証されます。

local/CI build 間で cache を保持すると network work を省けます。oxiquill clean は generated .oxiquill、public runtime、build output を削除しますが、downloadCacheDir は意図的に保持します。その後の generation は offline generation を含め、verified cache から public/oxiquill/pyodide を再構築できます。

cache entry が corrupt な場合はその filename の entry を削除するか、online generation を再実行します。Oxiquill は利用前に mismatch を検出し、diagnostic に filename、cache path、expected hash を含めます。

Mirror

default CDN が使えない場合や internal source が必要な場合は Pyodide package mirror を設定します。mirror は同じ release filename を公開する必要があります。integrity の正本は常に install 済み lockfile で、mirror metadata ではありません。

mirror failure は effective URL を示し、DNS/connection、HTTP status、timeout、retry exhaustion、SHA-256 mismatch を区別します。mirror の変更に cell の packages metadata 修正は不要です。

Offline mode

offline generation は package download を一切行いません。必要な core asset と wheel がすべて verified cache に存在しなければなりません。cache miss は missing filename と expected SHA-256 を表示するため、connected machine で正しい cache を作って転送できます。

同じ Oxiquill、Pyodide、manifest、package set で online generation が完了してから offline mode を使ってください。deploy site が copied asset を local 配信するため、browser execution は offline でも利用できます。

Runtime invalidation

Python runtime fingerprint は Pyodide version、lockfile hash、core-asset hash、選択 package の name/version/dependency/file/hash metadata、sorted requested package set を記録します。これらの semantic input が変わると published runtime を再生成します。cache reuse の単位はより細かく、version-and-lock namespace 内の有効な file は requested package subset が変わっても再利用できます。

Declared package

Python の packages は install 済み Pyodide release が vendor する name の non-empty unique list です。unknown name は download 前に reject されます。source import から runtime 内 package を load することもできますが、release build の deterministic preflight/cache のため non-core dependency は明示宣言してください。

metadata は 実行可能セル、復旧方法は トラブルシューティング を参照してください。