[0.7.x] Add pyodide-lock.json customization with optional pyodide-lock and uv dependencies

.github/workflows/test.yml

@@ -86,6 +86,14 @@ jobs:
       matrix:
         os: [ubuntu, windows, macos]
         python-version: ['3.10', '3.14']
+        test-extra: ['test', 'test,lock']
+        include:
+          - test-extra: test
+            use-dist: sdist
+            pytest-args: --cov-fail-under=69
+          - test-extra: test,lock
+            use-dist: wheel
+            pytest-args: --cov-fail-under=94
 
     steps:
       - name: Install Python
@@ -106,15 +114,9 @@ jobs:
           sudo rm -rf $(which node)
           sudo rm -rf $(which node)
 
-      - name: Install Built Package (wheel)
-        if: matrix.python-version == '3.14'
+      - name: Install Built Package (${{ matrix.use-dist }})
         run: |-
-          python -m pip install -v -r dist/requirements-wheel.txt
-
-      - name: Install Built Package (sdist)
-        if: matrix.python-version == '3.10'
-        run: |-
-          python -m pip install -v -r dist/requirements-sdist.txt
+          python -m pip install -v -r dist/requirements-${{ matrix.use-dist }}.txt
 
       - name: Make temp dir
         run: |-
@@ -153,22 +155,22 @@ jobs:
 
       - name: Install test deps
         run: |-
-          python -m pip install jupyterlite-pyodide-kernel[test] jupyterlite-core[lab] --upgrade-strategy only-if-needed
+          python -m pip install jupyterlite-pyodide-kernel[${{ matrix.test-extra }}] jupyterlite-core[lab] --upgrade-strategy only-if-needed
 
       - name: Check extension
         run: |-
           jupyter labextension list
           jupyter labextension list 2>&1 | grep -ie "@jupyterlite/pyodide-kernel.*OK"
 
       - name: Run the tests
-        run: pytest
+        run: pytest ${{ matrix.pytest-args }}
 
       - name: Upload reports
         if: always()
         uses: actions/upload-artifact@v7
         with:
           name: |-
-            jupyterlite-pyodide-kernel-pytest-${{ github.run_number }}-${{ matrix.os }}-${{ matrix.python-version}}
+            jupyterlite-pyodide-kernel-pytest-${{ github.run_number }}-${{ matrix.os }}-${{ matrix.python-version}}-${{ case(matrix.test-extra == 'test', 'min', 'full') }}
           path: build/reports
           if-no-files-found: error
 

.gitignore

@@ -2,6 +2,7 @@
 lib/
 node_modules/
 .eslintcache
+.prettiercache
 *.egg-info/
 .ipynb_checkpoints
 *.tsbuildinfo

.readthedocs.yml

@@ -23,6 +23,7 @@ python:
       extra_requirements:
         - dev
         - docs
+        - lock
 
 sphinx:
   builder: html

README.md

@@ -13,9 +13,36 @@
   https://readthedocs.org/projects/jupyterlite-pyodide-kernel/badge/?version=latest
 [docs]: https://jupyterlite-pyodide-kernel.readthedocs.io/en/latest/?badge=latest
 
-## Requirements
+## Install
+
+To install the Pyodide kernel labextension and the CLI addons for `jupyter lite`, run:
+
+```bash
+pip install jupyterlite-pyodide-kernel
+```
+
+or with `conda`, `mamba`, `micromamba`, etc.
+
+```bash
+conda install -c conda-forge jupyterlite-pyodide-kernel
+```
 
-- `python >=3.10`
+> For more options see the [development install](#development-install) or [contributing
+> guide][contrib].
+
+### Optional Features
+
+#### Lock
+
+Install the `[lock]` extra for compatible versions of [`pyodide-lock`][pyodide-lock] and
+[`uv`][uv], needed to add local or PyPI packages and their import name and dependency
+information to the Pyodide lockfile:
+
+- from PyPI: `jupyterlite-pyodide-kernel[lock]`
+- from `conda-forge`: `jupyterlite-pyodide-kernel-with-lock`
+
+[pyodide-lock]: https://pypi.org/project/pyodide-lock
+[uv]: https://pypi.org/project/uv
 
 ### Compatibility
 
@@ -37,64 +64,97 @@ yet work in a full, `jupyter_server`-hosted client such as JupyterLab or Noteboo
 
 #### With Pyodide
 
-| `jupyterlite-pyodide-kernel` | `pyodide` | `python` | `emscripten` |
-| :--------------------------: | :-------: | :------: | :----------: |
-|      `>=0.1.0,<=0.1.1`       | `0.23.*`  | `3.10.*` |   `3.1.29`   |
-|      `>=0.1.2,<=0.2.1`       | `0.24.*`  | `3.10.*` |   `3.1.45`   |
-|      `>=0.2.2,<=0.2.3`       | `0.25.*`  | `3.11.*` |   `3.1.46`   |
-|      `>=0.3.*,<=0.4.0`       | `0.25.*`  | `3.11.*` |   `3.1.46`   |
-|      `>=0.4.*,<=0.4.6`       | `0.26.*`  | `3.12.*` |   `3.1.58`   |
-|      `>=0.4.7,<=0.5.0`       | `0.27.*`  | `3.12.*` |   `3.1.58`   |
-|      `>=0.5.0,<=0.6.0`       | `0.27.*`  | `3.12.*` |   `3.1.58`   |
-|      `>=0.6.0,<=0.7.0`       | `0.27.*`  | `3.12.*` |   `3.1.58`   |
-|      `>=0.7.0,<=0.8.0`       | `0.29.*`  | `3.13.*` |   `4.0.9`    |
+| `jupyterlite-pyodide-kernel` | `pyodide` | `python` | `emscripten` | `pyodide-lock` |    `uv`    |
+| :--------------------------: | :-------: | :------: | :----------: | :------------: | :--------: |
+|      `>=0.1.0,<=0.1.1`       | `0.23.*`  | `3.10.*` |   `3.1.29`   |                |            |
+|      `>=0.1.2,<=0.2.1`       | `0.24.*`  | `3.10.*` |   `3.1.45`   |                |            |
+|      `>=0.2.2,<=0.2.3`       | `0.25.*`  | `3.11.*` |   `3.1.46`   |                |            |
+|      `>=0.3.*,<=0.4.0`       | `0.25.*`  | `3.11.*` |   `3.1.46`   |                |            |
+|      `>=0.4.*,<=0.4.6`       | `0.26.*`  | `3.12.*` |   `3.1.58`   |                |            |
+|      `>=0.4.7,<=0.5.0`       | `0.27.*`  | `3.12.*` |   `3.1.58`   |                |            |
+|      `>=0.5.0,<=0.6.0`       | `0.27.*`  | `3.12.*` |   `3.1.58`   |                |            |
+|      `>=0.6.0,<=0.7.0`       | `0.27.*`  | `3.12.*` |   `3.1.58`   |                |            |
+|      `>=0.7.0,<=0.8.0`       | `0.29.*`  | `3.13.*` |   `4.0.9`    | `>=0.1.2,<0.2` | `>=0.9.27` |
 
-Note that the Emscripten version is strict down to the bugfix version.
+> **Note**: the Emscripten version is strict down to the patch version.
 
-## Install
+## Usage
 
-To install the Pyodide kernel labextension and the CLI addons for `jupyter lite`, run:
+Once installed, building a JupyterLite site will include a kernel which uses the full
+Pyodide CDN distribution:
 
 ```bash
-pip install jupyterlite-pyodide-kernel
+jupyter lite build
 ```
 
-or with `conda`, `mamba`, `micromamba`, etc.
+The build configuration of the Pyodide distribution, the kernel, and package import
+behavior can be configured in `jupyter_lite_config.json`. Some features can be
+configured with CLI aliases and flags. See the full current list by running:
 
 ```bash
-conda install -c conda-forge jupyterlite-pyodide-kernel
+jupyter lite --help
 ```
 
-> For more options see the [development install](#development-install) or [contributing
-> guide][contrib].
+This should show something like the following:
 
-## Usage
-
-Build a JupyterLite site:
+<details><summary>... for configuring the Pyodide distribution</summary>
 
 ```bash
-jupyter lite build
+  --pyodide=<Unicode>
+      Local path or URL of a pyodide distribution tarball
+      Default: ''
+      Equivalent to: [--PyodideAddon.pyodide_url]
 ```
 
-Some new CLI options are also available:
+</details>
 
-```bash
-jupyter lite --help
-```
-
-This should show something like this:
+<details><summary>... adding extra wheels, installable at runtime with <code>%pip</code></summary>
 
 ```bash
   --piplite-wheels=<typedtuple-item-1>...
       Local paths or URLs of piplite-compatible wheels to copy and index
       Default: ()
       Equivalent to: [--PipliteAddon.piplite_urls]
-  --pyodide=<Unicode>
-      Local path or URL of a pyodide distribution tarball
-      Default: ''
-      Equivalent to: [--PyodideAddon.pyodide_url]
 ```
 
+</details>
+
+<details><summary>.... patching the Pyodide lockfile for automatically imported packages</summary>
+
+```bash
+--pyodide-lock
+    Use pyodide-lock and uv to customize pyodide-lock.json
+    Equivalent to: [--PyodideAddon.lock_enabled=True]
+--pyodide-lock-url=<Unicode>
+    URL of a remote pyodide-lock.json
+    Default: 'https://cdn.jsdelivr.net/pyodide/v0.29.3/full/pyodide-lock.json'
+    Equivalent to: [--PyodideAddon.lock_url]
+--pyodide-lock-wheels=<typedtuple-item-1>...
+    paths to local wheels or folders to include in pyodide-lock.json
+    Default: ()
+    Equivalent to: [--PyodideAddon.lock_wheels]
+--pyodide-lock-constraints=<typedtuple-item-1>...
+    PEP-508 specs for Python packages to use only if required in pyodide-
+    lock.json
+    Default: ()
+    Equivalent to: [--PyodideAddon.lock_constraints]
+--pyodide-lock-specs=<typedtuple-item-1>...
+    PEP-508 specs for Python packages to include in pyodide-lock.json
+    Default: ()
+    Equivalent to: [--PyodideAddon.lock_specs]
+--pyodide-lock-excludes=<typedtuple-item-1>...
+    extra Python package names to exclude from pyodide-lock.json
+    Default: ()
+    Equivalent to: [--PyodideAddon.lock_extra_excludes]
+--pyodide-lock-prefetch=<typedtuple-item-1>...
+    extra Python package names from pyodide-lock.json to prefetch while
+    initializing Pyodide
+    Default: ()
+    Equivalent to: [--PyodideAddon.lock_extra_prefetch]
+```
+
+</details>
+
 ## Learn more
 
 ⚠️ The documentation for advanced configuration is available from the main JupyterLite

examples/intro.ipynb

@@ -61,7 +61,6 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "%pip install ipywidgets\n",
     "from ipywidgets import *\n",
     "\n",
     "slider = FloatSlider(description=\"$x$\")\n",
@@ -87,7 +86,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.7"
+   "version": "3.13.2"
   }
  },
  "nbformat": 4,

examples/jupyter-lite.json

@@ -1,14 +1,6 @@
 {
   "jupyter-lite-schema-version": 0,
   "jupyter-config-data": {
-    "appName": "JupyterLite Pyodide Kernel",
-    "litePluginSettings": {
-      "@jupyterlite/pyodide-kernel-extension:kernel": {
-        "loadPyodideOptions": {
-          "packages": ["matplotlib", "micropip", "numpy", "sqlite3", "ssl"],
-          "lockFileURL": "https://cdn.jsdelivr.net/pyodide/v0.29.3/full/pyodide-lock.json?from-lite-config=1"
-        }
-      }
-    }
+    "appName": "JupyterLite Pyodide Kernel"
   }
 }

examples/jupyter_lite_config.json

@@ -4,9 +4,23 @@
     "output_dir": "../build/docs-app",
     "ignore_sys_prefix": ["federated_extensions"],
     "federated_extensions": [
-      "https://files.pythonhosted.org/packages/65/f6/659ca44182c86f57977e946047c339c717745fda9f43b7ac47f274e86553/jupyterlab_widgets-3.0.11-py3-none-any.whl",
+      "https://pypi.org/packages/py3/j/jupyterlab-widgets/jupyterlab_widgets-3.0.15-py3-none-any.whl",
       "../jupyterlite_pyodide_kernel/labextension"
     ],
-    "cache_dir": "../build/.lite-cache"
+    "cache_dir": "../build/.lite_cache"
+  },
+  "PyodideAddon": {
+    "lock_enabled": true,
+    "lock_specs": [
+      "IPython >=9.11.0",
+      "ipywidgets",
+      "jedi >=0.18.2",
+      "matplotlib-inline >=0.1.6",
+      "pygments >=2.14.0"
+    ],
+    "lock_extra_prefetch": ["ipywidgets"],
+    "lock_compile_options": {
+      "preserve_url_prefixes": ["https://"]
+    }
   }
 }

jupyterlite_pyodide_kernel/addons/_base.py

@@ -6,6 +6,8 @@
     https://github.com/jupyterlite/jupyterlite/issues/996
 """
 
+from __future__ import annotations
+
 import json
 from pathlib import Path
 from typing import Generator, Dict, Any
@@ -17,15 +19,31 @@
     JUPYTERLITE_METADATA,
     JUPYTER_CONFIG_DATA,
     LITE_PLUGIN_SETTINGS,
+    ALL_JSON,
     JSON_FMT,
+    LAB_EXTENSIONS,
 )
 
-from ..constants import PYODIDE_KERNEL_PLUGIN_ID
+from ..constants import PYODIDE_KERNEL_PLUGIN_ID, PYPI_WHEELS, PYODIDE_KERNEL_NPM_NAME
 
 __all__ = ["_BaseAddon"]
 
 
 class _BaseAddon(BaseAddon):
+    @property
+    def output_piplite_index(self) -> Path:
+        return self.manager.output_dir / PYPI_WHEELS / ALL_JSON
+
+    @property
+    def output_extensions(self):
+        """where labextensions will go in the output folder"""
+        return self.manager.output_dir / LAB_EXTENSIONS
+
+    @property
+    def output_kernel_extension(self):
+        """the location of the Pyodide kernel labextension static assets"""
+        return self.output_extensions / PYODIDE_KERNEL_NPM_NAME
+
     def get_pyodide_settings(self, config_path: Path):
         """Get the settings for the client-side Pyodide kernel."""
         return self.get_lite_plugin_settings(config_path, PYODIDE_KERNEL_PLUGIN_ID)