feature/pyodide package cache

[VsevolodX]

• feat: add IndexedDB-based wheel cache storage layer for Pyodide
• refactor: guard Pyodide HTTP utilities for non-WASM environment safety
• fix: align token store IndexedDB version with packages wheel cache
• feat: integrate persistent wheel caching into Pyodide packages installation

Summary by CodeRabbit

• New Features

  • Added persistent browser caching for Pyodide package wheels, reducing repeated downloads after kernel restarts.
  • Added options to enable or disable caching and force package reinstallation.
  • Added automatic detection of package changes to skip unnecessary installations.
  • Added support for clearing cached package data during forced reinstalls.

• Bug Fixes

  • Improved compatibility when Pyodide-specific networking features are unavailable.
  • Added safer handling for package reinstalls and cached package retrieval.

[coderabbitai]

Caution

Review failed

Failed to post review comments.

GitHub was unavailable or timed out while CodeRabbit was posting the review. Please request a new review later if the pull request still needs one. This happened while posting 2 inline comments. Use @coderabbitai full review to retry the review.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 99cbe24e-13c5-47c3-b536-c997d22d3a65

📥 Commits

Reviewing files that changed from the base of the PR and between 6a6518d and 58d69ff.

📒 Files selected for processing (5)

• src/py/mat3ra/notebooks_utils/packages.py
• src/py/mat3ra/notebooks_utils/pyodide/api/token_store.py
• src/py/mat3ra/notebooks_utils/pyodide/io.py
• src/py/mat3ra/notebooks_utils/pyodide/packages/install.py
• src/py/mat3ra/notebooks_utils/pyodide/packages/wheel_cache.py

🧰 Additional context used

🧠 Learnings (1)

📚 Learning: 2026-07-14T00:30:42.344Z

Learnt from: VsevolodX
Repo: mat3ra/api-examples PR: 345
File: other/materials_designer/workflows/zero_point_energy.ipynb:579-581
Timestamp: 2026-07-14T00:30:42.344Z
Learning: When reviewing `mat3ra/notebooks_utils` code, note that functions decorated with `interruptible_polling_loop()` (from `src/py/mat3ra/notebooks_utils/pyodide/runtime.py`) intentionally accept and process a `poll_interval` keyword argument that is stripped from the call before the wrapped function executes. Therefore, it’s valid for callers to pass `poll_interval=...` even if the wrapped function’s own signature doesn’t include `poll_interval`; don’t flag those calls as mismatched/invalid kwargs (as long as the decorator is used).

Applied to files:

• src/py/mat3ra/notebooks_utils/pyodide/api/token_store.py
• src/py/mat3ra/notebooks_utils/packages.py
• src/py/mat3ra/notebooks_utils/pyodide/packages/wheel_cache.py
• src/py/mat3ra/notebooks_utils/pyodide/io.py
• src/py/mat3ra/notebooks_utils/pyodide/packages/install.py

🪛 ast-grep (0.44.1)

src/py/mat3ra/notebooks_utils/pyodide/packages/wheel_cache.py

[info] 120-120: use jsonify instead of json.dumps for JSON output
Context: json.dumps(manifest)
Note: [CWE-116] Improper Encoding or Escaping of Output.

(use-jsonify)

src/py/mat3ra/notebooks_utils/pyodide/packages/install.py

[warning] 27-27: Do not make http calls without encryption
Context: "http://"
Note: [CWE-319] Cleartext Transmission of Sensitive Information.

(requests-http)

---

[info] 30-30: Do not hardcode temporary file or directory names
Context: "/tmp/wheel_cache"
Note: [CWE-377] Insecure Temporary File.

(hardcoded-tmp-file)

---

[info] 306-306: use jsonify instead of json.dumps for JSON output
Context: json.dumps(packages)
Note: [CWE-116] Improper Encoding or Escaping of Output.

(use-jsonify)

🪛 Ruff (0.15.21)

src/py/mat3ra/notebooks_utils/pyodide/packages/install.py

[error] 31-31: Probable insecure usage of temporary file or directory: "/tmp/wheel_cache"

(S108)

---

[warning] 277-277: Do not catch blind exception: Exception

(BLE001)

📝 Walkthrough

Walkthrough

Pyodide package installation now supports persistent IndexedDB wheel caching, requirement-hash tracking, forced reinstalls, and cache toggling. IndexedDB schema version 2 adds wheel stores, while the public installer forwards the new controls.

Changes

Pyodide wheel caching

Layer / File(s)	Summary
IndexedDB cache storage src/py/mat3ra/notebooks_utils/pyodide/api/token_store.py, src/py/mat3ra/notebooks_utils/pyodide/packages/wheel_cache.py	IndexedDB version 2 creates manifest and wheel-data stores. The cache module reads and writes manifests and wheel bytes and can clear cached data.
Cache-aware package installation src/py/mat3ra/notebooks_utils/pyodide/packages/install.py	Remote wheels use cache-first installation through EMFS, while requirement hashes determine whether package installation is skipped or rerun.
Public installation controls src/py/mat3ra/notebooks_utils/packages.py, src/py/mat3ra/notebooks_utils/pyodide/io.py	force and use_cache are exposed by install_packages, and pyfetch is initialized at module scope with an import fallback.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant NotebookInstaller
  participant PyodideInstaller
  participant IndexedDB
  participant micropip
  NotebookInstaller->>PyodideInstaller: install_packages_pyodide(force, use_cache)
  PyodideInstaller->>IndexedDB: Read manifest and cached wheel
  IndexedDB-->>PyodideInstaller: Cached data or cache miss
  PyodideInstaller->>micropip: Install cached or downloaded wheel
  PyodideInstaller->>IndexedDB: Store wheel and requirement hash

Loading

Possibly related PRs

• mat3ra/api-examples#327: Modifies the same Pyodide package installer flow with cache and reinstall controls.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and accurately reflects the main change: adding a Pyodide package cache.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/pyodide-package-cache

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}