Metadata-Version: 2.4
Name: datalab-kernel
Version: 0.2.8
Summary: A standalone Xeus-Python-based Jupyter kernel for DataLab with optional live synchronization
Author-email: DataLab Platform Developers <p.raybaut@codra.fr>
License: BSD-3-Clause
Project-URL: Homepage, https://github.com/DataLab-Platform/DataLab-Kernel
Project-URL: Documentation, https://datalab-kernel.readthedocs.io/
Project-URL: Repository, https://github.com/DataLab-Platform/DataLab-Kernel.git
Project-URL: Issues, https://github.com/DataLab-Platform/DataLab-Kernel/issues
Keywords: jupyter,kernel,datalab,scientific,data processing,xeus
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Jupyter
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: xeus-python>=0.17.0
Requires-Dist: xeus-python-shell>=0.6.0
Requires-Dist: numpy>=1.22
Requires-Dist: httpx>=0.25.0
Requires-Dist: h5py>=3.0
Requires-Dist: matplotlib>=3.5
Requires-Dist: sigima>=1.0
Provides-Extra: cli
Requires-Dist: jupyter-client>=7.0; extra == "cli"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Provides-Extra: doc
Requires-Dist: sphinx>=7.0; extra == "doc"
Requires-Dist: pydata-sphinx-theme>=0.14; extra == "doc"
Requires-Dist: myst-nb>=1.0; extra == "doc"
Requires-Dist: sphinx-design>=0.5; extra == "doc"
Requires-Dist: sphinx-copybutton>=0.5; extra == "doc"
Provides-Extra: datalab
Requires-Dist: datalab-platform>=1.1; extra == "datalab"
Dynamic: license-file

# DataLab-Kernel

[![license](https://img.shields.io/pypi/l/datalab-kernel.svg)](./LICENSE)
[![pypi version](https://img.shields.io/pypi/v/datalab-kernel.svg)](https://pypi.org/project/datalab-kernel/)
[![PyPI status](https://img.shields.io/pypi/status/datalab-kernel.svg)](https://github.com/DataLab-Platform/DataLab-Kernel)
[![PyPI pyversions](https://img.shields.io/pypi/pyversions/datalab-kernel.svg)](https://pypi.org/project/datalab-kernel/)

**A standalone [Xeus-Python](https://github.com/jupyter-xeus/xeus-python)-based Jupyter kernel providing seamless, reproducible access to DataLab workspaces, with optional live synchronization to the DataLab GUI.**

---

## Overview

**DataLab-Kernel** is a custom Jupyter kernel designed to bridge **DataLab** and the **Jupyter** ecosystem. It is built on top of [**Xeus-Python**](https://github.com/jupyter-xeus/xeus-python), a lightweight and efficient Python kernel for Jupyter that offers improved performance, native debugger support, and excellent Qt event loop integration.

Thanks to Xeus-Python's architecture, DataLab-Kernel runs seamlessly in both:

- **Native Jupyter environments** (JupyterLab, Jupyter Notebook, VS Code)
- **[JupyterLite](https://jupyterlite.readthedocs.io/)** (browser-based Jupyter, no server required)

This enables scientists and engineers to:

- run reproducible analyses in Jupyter notebooks,
- interact transparently with DataLab’s internal workspace when DataLab is running,
- share notebooks that can be replayed **with or without DataLab**,
- combine narrative, code, and results without sacrificing interactive visualization.

DataLab-Kernel is **not** a replacement for DataLab’s GUI.
It is a **complementary execution layer** that turns DataLab into a hybrid scientific platform:
**GUI-driven when needed, notebook-driven when appropriate.**

---

## Try it Online

**Experience DataLab-Kernel instantly in your browser** — no installation required!

[![Try it online](https://img.shields.io/badge/Try_it-online-blue?logo=jupyter)](https://notebook.link/github/DataLab-Platform/DataLab-Kernel/tree/main/notebooks/?path=/notebooks/datalab_kernel_quickstart.ipynb)

Click the badge above to open the quickstart notebook in a live JupyterLite environment powered by [**notebook.link**](https://notebook.link/). This service, developed by [**QuantStack**](https://quantstack.net/), enables sharing and running Jupyter notebooks directly in the browser with zero setup.

Simply run the cells to explore:

- Loading the DataLab-Kernel extension
- Accessing workspace objects
- Visualizing images inline
- Processing data with Sigima

---

## Key Features

- **Single, stable user API**
  - `workspace` for data access and persistence
  - `plotter` for visualization
  - `sigima` for scientific processing

- **Two execution modes, one notebook**
  - **Live mode**: automatic synchronization with a running DataLab instance
  - **Standalone mode**: notebook-only execution, fully reproducible

- **Reproducibility by design**
  - Analyses can be saved and reloaded using `.h5` files
  - Notebooks run unchanged across environments

- **Performance-aware**
  - Optimized data handling when DataLab is attached
  - No unnecessary serialization for large datasets

- **Decoupled architecture**
  - Installable independently of DataLab
  - DataLab is a privileged host, not a requirement

---

## Typical Usage

```python
img = workspace.get("i042")
filtered = sigima.proc.image.butterworth(img, cut_off=0.2)
workspace.add("filtered_i042", filtered)
plotter.plot("filtered_i042")
```

Depending on the execution context:

- the result appears inline in the notebook,
- and, if DataLab is running, it also appears automatically in the DataLab GUI,
  with views and metadata kept in sync.

---

## Execution Modes

### Live Mode (DataLab-attached)

- DataLab launches a Jupyter server and starts `kernel-datalab`.
- The kernel detects DataLab at runtime.
- Workspace operations and visualizations are synchronized with the GUI.

Two connection methods are supported:

- **Auto-discovery** (recommended): DataLab-Kernel automatically finds running DataLab instances
  via a connection file written by DataLab, or by probing the well-known port (18080)
- **XML-RPC** (legacy): Automatic connection when DataLab is running with remote control enabled

**No environment variables or manual configuration needed** — just start DataLab with
the Web API enabled and load the kernel extension.

### Standalone Mode (Notebook-only)

- The kernel is used like any standard Jupyter kernel.
- No DataLab installation or GUI is required.
- Data are managed locally and persisted to `.h5` files.

**The same notebook runs unchanged in both modes.**

---

## Installation

### Standalone usage (desktop Jupyter)

```bash
pip install datalab-kernel[cli] sigima
python -m datalab_kernel install
jupyter lab
```

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

### JupyterLite

DataLab-Kernel is compatible with **JupyterLite** (browser-based Jupyter).
In this environment, kernels are bundled at build time, so you load DataLab-Kernel
as an IPython extension instead.

**1. Add to your `environment.yml`:**

```yaml
name: xeus-python-kernel
channels:
  - https://repo.mamba.pm/emscripten-forge
  - conda-forge
dependencies:
  - numpy
  - matplotlib
  - h5py
  - datalab-kernel
  - sigima
```

**2. Load the extension in your notebook:**

```python
%load_ext datalab_kernel
```

This injects the DataLab namespace (`workspace`, `plotter`, `sigima`, etc.)
into your environment.

The `[cli]` extra is not needed in JupyterLite since `jupyter-client` depends
on `pyzmq`, which requires native sockets unavailable in WebAssembly.

### Dependencies

DataLab-Kernel uses **xeus-python** as its backend, which provides:

- Improved performance compared to ipykernel
- Native debugger support
- JupyterLite compatibility
- Better Qt event loop integration

The kernel requires:

- `xeus-python>=0.17.0` - The xeus-based Python kernel
- `xeus-python-shell>=0.6.0` - Python shell utilities for xeus-python
- `sigima>=1.0` - Scientific signal and image processing
- `numpy>=1.22`, `h5py>=3.0`, `matplotlib>=3.5`

Optional dependency (via `[cli]` extra):

- `jupyter-client>=7.0` - For `install`/`uninstall` CLI commands

### With DataLab

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

### Installing from conda-forge (recommended)

For best compatibility, especially on Windows:

```bash
mamba create -n datalab-kernel
mamba activate datalab-kernel
mamba install xeus-python datalab-kernel -c conda-forge
python -m datalab_kernel install
```

---

## Persistence and Sharing

Workspace state can be saved and reloaded:

```python
workspace.save("analysis.h5")
workspace.load("analysis.h5")
```

This enables:

- sharing notebooks and data with collaborators,
- replaying analyses without DataLab,
- resuming workflows inside DataLab by reopening the associated project.

---

## Documentation

- **User contract and behavior**: see `plans/specification.md`
- **Vision and architectural principles**: see `plans/architecture.md`

---

## Project Status

DataLab-Kernel is under active design and development.

---

## License

This project is released under an open-source license (see `LICENSE` file).
