Skip to content

Commit 7ae31f8

Browse files
PierreRaybautPierreRaybaut
committed
JupyterLite: Make jupyter-client optional, add IPython extension support
- Move jupyter-client from required dependencies to optional [cli] extra (jupyter-client requires pyzmq which needs native sockets unavailable in WebAssembly) - Add fallback kernel directory detection when jupyter-client is unavailable - Implement IPython extension API (load_ipython_extension/unload_ipython_extension) for loading DataLab namespace via %load_ext datalab_kernel in JupyterLite - Update README and documentation with JupyterLite installation instructions
1 parent 92e701c commit 7ae31f8

6 files changed

Lines changed: 188 additions & 18 deletions

File tree

‎README.md‎

Lines changed: 39 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -93,16 +93,49 @@ Two connection methods are supported:
9393

9494
## Installation
9595

96-
### Standalone usage
96+
### Standalone usage (desktop Jupyter)
9797

9898
```bash
99-
pip install datalab-kernel sigima
99+
pip install datalab-kernel[cli] sigima
100100
python -m datalab_kernel install
101101
jupyter lab
102102
```
103103

104104
Then select **DataLab Kernel** from the kernel list.
105105

106+
### JupyterLite
107+
108+
DataLab-Kernel is compatible with **JupyterLite** (browser-based Jupyter).
109+
In this environment, kernels are bundled at build time, so you load DataLab-Kernel
110+
as an IPython extension instead.
111+
112+
**1. Add to your `environment.yml`:**
113+
114+
```yaml
115+
name: xeus-python-kernel
116+
channels:
117+
- https://repo.mamba.pm/emscripten-forge
118+
- conda-forge
119+
dependencies:
120+
- numpy
121+
- matplotlib
122+
- h5py
123+
- datalab-kernel
124+
- sigima
125+
```
126+
127+
**2. Load the extension in your notebook:**
128+
129+
```python
130+
%load_ext datalab_kernel
131+
```
132+
133+
This injects the DataLab namespace (`workspace`, `plotter`, `sigima`, etc.)
134+
into your environment.
135+
136+
The `[cli]` extra is not needed in JupyterLite since `jupyter-client` depends
137+
on `pyzmq`, which requires native sockets unavailable in WebAssembly.
138+
106139
### Dependencies
107140

108141
DataLab-Kernel uses **xeus-python** as its backend, which provides:
@@ -119,6 +152,10 @@ The kernel requires:
119152
- `sigima>=1.0` - Scientific signal and image processing
120153
- `numpy>=1.22`, `h5py>=3.0`, `matplotlib>=3.5`
121154

155+
Optional dependency (via `[cli]` extra):
156+
157+
- `jupyter-client>=7.0` - For `install`/`uninstall` CLI commands
158+
122159
### With DataLab
123160

124161
When installed alongside DataLab, the kernel is automatically available and can be launched directly from the DataLab interface.

‎datalab_kernel/__init__.py‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,9 @@
3434
__author__ = "DataLab Platform Developers"
3535

3636
from datalab_kernel.plotter import Plotter
37+
38+
# Re-export IPython extension functions for %load_ext datalab_kernel
39+
from datalab_kernel.startup import load_ipython_extension, unload_ipython_extension
3740
from datalab_kernel.workspace import Workspace
3841

3942
# Global instances (initialized when kernel starts)
@@ -48,4 +51,6 @@
4851
"Plotter",
4952
"workspace",
5053
"plotter",
54+
"load_ipython_extension",
55+
"unload_ipython_extension",
5156
]

‎datalab_kernel/install.py‎

Lines changed: 32 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@
1414

1515
import argparse
1616
import json
17+
import os
1718
import shutil
1819
import sys
1920
from pathlib import Path
@@ -99,20 +100,37 @@ def get_kernel_dir(user: bool = True) -> Path:
99100
Returns:
100101
Path to kernel directory
101102
"""
102-
# Delayed import to avoid dependency at module load time
103-
# pylint: disable=import-outside-toplevel
104-
from jupyter_client.kernelspec import KernelSpecManager
105-
106-
ksm = KernelSpecManager()
107-
108-
if user:
109-
# User kernels directory
110-
data_dir = Path(ksm.user_kernel_dir)
111-
else:
112-
# System kernels directory (first one in path)
113-
data_dir = Path(ksm.kernel_dirs[0]) if ksm.kernel_dirs else None
114-
if data_dir is None:
115-
raise RuntimeError("Could not find system kernel directory")
103+
try:
104+
# Delayed import to avoid dependency at module load time
105+
# pylint: disable=import-outside-toplevel
106+
from jupyter_client.kernelspec import KernelSpecManager
107+
108+
ksm = KernelSpecManager()
109+
110+
if user:
111+
# User kernels directory
112+
data_dir = Path(ksm.user_kernel_dir)
113+
else:
114+
# System kernels directory (first one in path)
115+
data_dir = Path(ksm.kernel_dirs[0]) if ksm.kernel_dirs else None
116+
if data_dir is None:
117+
raise RuntimeError("Could not find system kernel directory")
118+
except ImportError:
119+
# Fallback when jupyter_client is not installed (e.g., JupyterLite)
120+
# Use standard Jupyter data directories
121+
if user:
122+
# Standard user kernel location
123+
if os.name == "nt":
124+
data_dir = Path.home() / "AppData" / "Roaming" / "jupyter" / "kernels"
125+
else:
126+
data_dir = Path.home() / ".local" / "share" / "jupyter" / "kernels"
127+
else:
128+
# Standard system kernel location
129+
if os.name == "nt":
130+
data_dir = Path(os.environ.get("PROGRAMDATA", "C:/ProgramData"))
131+
data_dir = data_dir / "jupyter" / "kernels"
132+
else:
133+
data_dir = Path("/usr/local/share/jupyter/kernels")
116134

117135
return data_dir / KERNEL_NAME
118136

‎datalab_kernel/startup.py‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,63 @@ def run_startup():
8787
raise
8888

8989

90+
# =============================================================================
91+
# IPython Extension API
92+
# =============================================================================
93+
# These functions allow datalab_kernel to be loaded as an IPython extension,
94+
# which is the recommended way to use it in JupyterLite environments.
95+
#
96+
# Usage in IPython/Jupyter:
97+
# %load_ext datalab_kernel
98+
#
99+
# Or configure auto-loading in ipython_config.py:
100+
# c.InteractiveShellApp.extensions = ['datalab_kernel']
101+
# =============================================================================
102+
103+
104+
def load_ipython_extension(ipython):
105+
"""Load the DataLab kernel extension.
106+
107+
This function is called by IPython when the extension is loaded via:
108+
%load_ext datalab_kernel
109+
110+
It injects the DataLab namespace (workspace, plotter, sigima, etc.)
111+
into the user's interactive environment.
112+
113+
This is the recommended way to use DataLab-Kernel in JupyterLite,
114+
where the traditional kernel installation mechanism doesn't apply.
115+
116+
Args:
117+
ipython: The active IPython shell instance.
118+
"""
119+
namespace = setup_namespace()
120+
ipython.user_ns.update(namespace)
121+
logger.info("DataLab extension loaded successfully")
122+
123+
124+
def unload_ipython_extension(ipython):
125+
"""Unload the DataLab kernel extension.
126+
127+
This function is called by IPython when the extension is unloaded.
128+
It removes the DataLab namespace from the user's environment.
129+
130+
Args:
131+
ipython: The active IPython shell instance.
132+
"""
133+
# List of names we injected
134+
names_to_remove = [
135+
"workspace",
136+
"plotter",
137+
"np",
138+
"sigima",
139+
"create_signal",
140+
"create_image",
141+
]
142+
for name in names_to_remove:
143+
ipython.user_ns.pop(name, None)
144+
logger.info("DataLab extension unloaded")
145+
146+
90147
# When this module is imported as a startup script, run the startup
91148
if __name__ == "__main__":
92149
run_startup()

‎doc/user_guide/installation.rst‎

Lines changed: 52 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,10 +24,16 @@ Installing DataLab-Kernel from PyPI:
2424

2525
.. code-block:: console
2626
27-
$ pip install datalab-kernel
27+
$ pip install datalab-kernel[cli]
2828
2929
This will install the kernel and all required dependencies including Sigima.
3030

31+
.. note::
32+
33+
The ``[cli]`` extra installs ``jupyter-client``, which is required for
34+
the ``install``/``uninstall`` CLI commands. See :ref:`install_jupyterlite`
35+
for environments where this is not needed.
36+
3137
Installing the Jupyter Kernel
3238
-----------------------------
3339

@@ -40,6 +46,51 @@ After installing the package, register the kernel with Jupyter:
4046
This makes the "DataLab" kernel available in Jupyter Notebook, JupyterLab,
4147
and VS Code.
4248

49+
.. _install_jupyterlite:
50+
51+
JupyterLite (browser-based)
52+
---------------------------
53+
54+
DataLab-Kernel is compatible with **JupyterLite**, a browser-based Jupyter
55+
environment running on WebAssembly.
56+
57+
In JupyterLite, kernels are bundled at build time and the ``install``/``uninstall``
58+
commands are not used. Instead, you load DataLab-Kernel as an IPython extension.
59+
60+
**Step 1: Add to your JupyterLite environment**
61+
62+
Create or edit your ``environment.yml``:
63+
64+
.. code-block:: yaml
65+
66+
name: xeus-python-kernel
67+
channels:
68+
- https://repo.mamba.pm/emscripten-forge
69+
- conda-forge
70+
dependencies:
71+
- numpy
72+
- matplotlib
73+
- h5py
74+
- datalab-kernel
75+
- sigima
76+
77+
**Step 2: Load the extension in your notebook**
78+
79+
In the first cell of your notebook, load the extension:
80+
81+
.. code-block:: python
82+
83+
%load_ext datalab_kernel
84+
85+
This injects the DataLab namespace (``workspace``, ``plotter``, ``sigima``, etc.)
86+
into your environment, just like the native kernel does.
87+
88+
**Why no ``[cli]`` extra?**
89+
90+
The ``[cli]`` extra includes ``jupyter-client``, which depends on ``pyzmq`` (ZeroMQ).
91+
Since ZeroMQ requires native sockets unavailable in WebAssembly environments,
92+
this dependency is not needed in JupyterLite.
93+
4394
Optional: DataLab Integration
4495
-----------------------------
4596

‎pyproject.toml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,6 @@ requires-python = ">=3.9"
2828
dependencies = [
2929
"xeus-python>=0.17.0",
3030
"xeus-python-shell>=0.6.0",
31-
"jupyter-client>=7.0",
3231
"numpy>=1.22",
3332
"httpx>=0.25.0",
3433
"h5py>=3.0",
@@ -38,6 +37,9 @@ dependencies = [
3837
dynamic = ["version"]
3938

4039
[project.optional-dependencies]
40+
cli = [
41+
"jupyter-client>=7.0", # Only needed for install/uninstall CLI commands
42+
]
4143
dev = [
4244
"pytest>=7.0",
4345
"pytest-cov>=4.0",

0 commit comments

Comments
 (0)