marimo ノートブック用 WASM 互換性チェッカー

marimo ノートブックが WebAssembly (WASM) 環境（marimo プレイグラウンド、コミュニティクラウド、またはエクスポートされた WASM HTML）で実行できるかどうかを確認します。

手順

1. ノートブックを読み込む

対象のノートブックファイルを読み込みます。ユーザーが指定しない場合は、どのノートブックをチェックするのか尋ねてください。

2. 依存関係を抽出する

ノートブックが依存している全パッケージを、両方のソースから収集します：

• PEP 723 メタデータ — トップの # /// script ブロック：

  # /// script
  # dependencies = [
  #     "marimo",
  #     "torch>=2.0.0",
  # ]
  # ///
  

• Import ステートメント — すべてのセルから import foo と from foo import bar をスキャンします。このテーブルを使用してインポート名を PyPI ディストリビューション名にマップします：

  インポート名	ディストリビューション名
  sklearn	scikit-learn
  skimage	scikit-image
  cv2	opencv-python
  PIL	Pillow
  bs4	beautifulsoup4
  yaml	pyyaml
  dateutil	python-dateutil
  attr / attrs	attrs
  gi	PyGObject
  serial	pyserial
  usb	pyusb
  wx	wxPython

  ほとんどの他のパッケージについては、インポート名がディストリビューション名と一致します。

3. 各パッケージを Pyodide に対してチェックする

各依存関係について、WASM で実行できるかどうかを判定します：

1. Python 標準ライブラリに含まれているか？ ほとんどの stdlib モジュールは動作しますが、これらは動作しません：

   • multiprocessing — ブラウザサンドボックスではプロセス生成ができない
   • subprocess — 同じ理由
   • threading — エミュレートされている。実際の並列処理なし（警告。厳密な失敗ではない）
   • sqlite3 — 代わりに apsw を使用（Pyodide で利用可能）
   • pdb — サポートされていない
   • tkinter — ブラウザに GUI ツールキットなし
   • readline — ブラウザにターミナルなし

2. Pyodide 組み込みパッケージか？ 完全なリストは pyodide-packages.md を参照してください。これらはそのまま動作します。

3. 純粋な Python パッケージか？ .py ファイルのみを含むパッケージ（コンパイルされた C/Rust 拡張機能がない）は、実行時に micropip 経由でインストールでき、動作します。確認するには：PyPI で py3-none-any.whl ホイールを探します（例：https://pypi.org/project/<package>/#files にアクセス）。プラットフォーム固有のホイール（例：cp312-cp312-manylinux）のみの場合、パッケージはネイティブ拡張機能を持ち、動作しない可能性が高い。

   動作する一般的な純粋 Python パッケージ（Pyodide 組み込みではないが micropip 経由でインストール可能）：

   • plotly, seaborn, humanize, pendulum, arrow, tabulate
   • dataclasses-json, marshmallow, cattrs, pydantic (組み込み)
   • httpx (組み込み), tenacity, backoff, wrapt (組み込み)

4. Pyodide 用にビルドされていない C/ネイティブ拡張機能があるか？ これらは動作しません。一般的な原因：

   • torch / pytorch
   • tensorflow
   • jax / jaxlib
   • psycopg2 （純粋 Python モードの psycopg を提案）
   • mysqlclient （pymysql を提案）
   • uvloop
   • grpcio
   • psutil

4. WASM 非互換パターンをチェックする

WASM で動作しないパターンについてノートブックコードをスキャンします：

パターン	失敗の理由	提案
subprocess.run(...), os.system(...), os.popen(...)	ブラウザではプロセス生成ができない	削除するか非 WASM チェックの背後に配置
multiprocessing.Pool(...), ProcessPoolExecutor	プロセスフォーク不可	シングルスレッドアプローチを使用
threading.Thread(...), ThreadPoolExecutor	エミュレートされたスレッド。実際の並列処理なし	警告のみ。動作しますが高速化なし。I/O に asyncio を使用
open("/absolute/path/..."), ハードコードされたローカルファイルパス	リアルファイルシステムなし。メモリ内ファイルシステムのみ	URL 経由でデータをフェッチ（httpx, urllib）またはノートブックに埋め込み
sqlite3.connect(...)	stdlib sqlite3 利用不可	apsw または duckdb を使用
pdb.set_trace(), breakpoint()	WASM にデバッガなし	ブレークポイントを削除
環境変数の読み取り（os.environ[...], os.getenv(...)）	ブラウザで利用可能な環境変数なし	ユーザー入力に mo.ui.text を使用するかデフォルトをハードコード
Path.home(), Path.cwd() （リアルファイル期待）	仮想ファイルシステムのみ	URL または埋め込みデータを使用
大規模データセットロード（>100 MB）	総メモリ上限 2 GB	より小さいサンプルまたはリモート API を使用

5. PEP 723 メタデータをチェックする

WASM ノートブックは、ノートブック起動時に自動的にインストールされるように、PEP 723 # /// script ブロックにすべての依存関係をリストする必要があります。次の問題をチェックします：

• メタデータ不足： ノートブックに # /// script ブロックがない場合、推奨する警告を発行します。依存関係をリストすることで、WASM でノートブックが起動するときに自動インストールされます。これがないと、ユーザーはインポートエラーを見ることがあります。
• パッケージ不足： パッケージがインポートされているが依存関係にリストされていない場合、追加を提案する警告を発行します。 注：PEP 723 メタデータのバージョンピンと下限はそのまま使用できます。marimo は WASM で実行する場合、バージョン制約をストリップします。

6. レポートを作成する

以下のセクションを含む、明確で実行可能なレポートを出力します：

互換性：PASS / FAIL / WARN

これらの判定を使用します：

• PASS — すべてのパッケージとパターンが WASM 互換
• WARN — おそらく互換。ただしいくつかのパッケージを純粋 Python として確認できない（ユーザーが確認できるようにリストアップ）
• FAIL — 1 つ以上のパッケージまたはパターンが確実に非互換

パッケージレポート — 列：Package、Status (OK / WARN / FAIL)、Notes のテーブル

例：

パッケージ	ステータス	注釈
marimo	OK	WASM ランタイムで利用可能
numpy	OK	Pyodide 組み込み
pandas	OK	Pyodide 組み込み
torch	FAIL	WASM ビルドなし。ネイティブ C++/CUDA 拡張機能が必要
my-niche-lib	WARN	Pyodide に含まれていない。純粋 Python であることを確認

コード問題 — 見つかった各問題のあるコードパターンをリストアップ。セルまたは行とともに修正案を提示。

推奨事項 — ノートブックが失敗する場合、具体的な修正を提案：

• 非互換パッケージを WASM フレンドリーな代替品に置き換え
• 非互換コードパターンを書き直し
• 重い計算をホストされた API に移動して結果をフェッチすることを提案

追加コンテキスト

• WASM ノートブックはブラウザで Pyodide 経由で実行
• メモリは 2 GB に制限
• ネットワークリクエストは動作しますが、CORS 互換エンドポイントが必要な場合あり
• Chrome は WASM パフォーマンスが最良。Firefox、Edge、Safari も対応
• micropip は実行時に PyPI から任意の純粋 Python ホイールをインストール可能
• 完全な Pyodide 組み込みパッケージリストについては、pyodide-packages.md を参照