datalab-kernel 0.1.0__tar.gz

datalab_kernel-0.1.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2023, DataLab Platform Developers.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

datalab_kernel-0.1.0/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: datalab-kernel
+Version: 0.1.0
+Summary: A standalone 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
+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: ipykernel>=6.0
+Requires-Dist: jupyter-client>=7.0
+Requires-Dist: numpy>=1.22
+Requires-Dist: h5py>=3.0
+Requires-Dist: matplotlib>=3.5
+Requires-Dist: sigima>=1.0
+Provides-Extra: webapi
+Requires-Dist: httpx>=0.25.0; extra == "webapi"
+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"
+Requires-Dist: httpx>=0.25.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.0; extra == "datalab"
+Dynamic: license-file
+
+# DataLab-Kernel
+
+**A standalone 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 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.**
+
+---
+
+## 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:
+
+- **Web API** (recommended): HTTP/JSON connection using `DATALAB_WORKSPACE_URL` and `DATALAB_WORKSPACE_TOKEN` environment variables
+- **XML-RPC** (legacy): Automatic connection when DataLab is running with remote control enabled
+
+### 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
+
+```bash
+pip install datalab-kernel sigima
+jupyter lab
+```
+
+Then select **DataLab Kernel** from the kernel list.
+
+### With DataLab
+
+When installed alongside DataLab, the kernel is automatically available and can be launched directly from the DataLab interface.
+
+---
+
+## 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).

datalab_kernel-0.1.0/README.md

@@ -0,0 +1,138 @@
+# DataLab-Kernel
+
+**A standalone 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 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.**
+
+---
+
+## 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:
+
+- **Web API** (recommended): HTTP/JSON connection using `DATALAB_WORKSPACE_URL` and `DATALAB_WORKSPACE_TOKEN` environment variables
+- **XML-RPC** (legacy): Automatic connection when DataLab is running with remote control enabled
+
+### 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
+
+```bash
+pip install datalab-kernel sigima
+jupyter lab
+```
+
+Then select **DataLab Kernel** from the kernel list.
+
+### With DataLab
+
+When installed alongside DataLab, the kernel is automatically available and can be launched directly from the DataLab interface.
+
+---
+
+## 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).

datalab_kernel-0.1.0/datalab_kernel/__init__.py

@@ -0,0 +1,45 @@
+# Copyright (c) DataLab Platform Developers, BSD 3-Clause License
+# See LICENSE file for details
+
+"""
+DataLab Jupyter Kernel
+======================
+
+A standalone Jupyter kernel providing seamless, reproducible access to DataLab
+workspaces, with optional live synchronization to the DataLab GUI.
+
+Main components:
+- `workspace`: Data access and persistence API
+- `plotter`: Visualization frontend
+- `sigima`: Scientific processing library (re-exported)
+
+Example usage::
+
+    # In a Jupyter notebook with datalab-kernel
+    img = workspace.get("i042")
+    filtered = sigima.proc.image.butterworth(img, cut_off=0.2)
+    workspace.add("filtered_i042", filtered)
+    plotter.plot("filtered_i042")
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+__author__ = "DataLab Platform Developers"
+
+from datalab_kernel.plotter import Plotter
+from datalab_kernel.workspace import Workspace
+
+# Global instances (initialized when kernel starts)
+# pylint: disable=invalid-name
+workspace: Workspace | None = None
+plotter: Plotter | None = None
+# pylint: enable=invalid-name
+
+__all__ = [
+    "__version__",
+    "Workspace",
+    "Plotter",
+    "workspace",
+    "plotter",
+]

datalab_kernel-0.1.0/datalab_kernel/__main__.py

@@ -0,0 +1,38 @@
+# Copyright (c) DataLab Platform Developers, BSD 3-Clause License
+# See LICENSE file for details
+
+"""
+DataLab Kernel main module.
+
+Supports running as:
+    python -m datalab_kernel install
+    python -m datalab_kernel uninstall
+"""
+
+from __future__ import annotations
+
+import sys
+
+from datalab_kernel.install import main as install_main
+
+
+def main() -> None:
+    """Main entry point for the datalab_kernel module."""
+    if len(sys.argv) > 1 and sys.argv[1] in ("install", "uninstall"):
+        # Handle install/uninstall commands
+        install_main()
+    else:
+        # Launch kernel (default behavior when run by Jupyter)
+        # Delayed import: only needed when launching as kernel
+        from ipykernel.kernelapp import (  # pylint: disable=import-outside-toplevel
+            IPKernelApp,
+        )
+
+        # pylint: disable-next=import-outside-toplevel
+        from datalab_kernel.kernel import DataLabKernel
+
+        IPKernelApp.launch_instance(kernel_class=DataLabKernel)
+
+
+if __name__ == "__main__":
+    main()

datalab_kernel-0.1.0/datalab_kernel/backends/__init__.py

@@ -0,0 +1,33 @@
+# Copyright (c) DataLab Platform Developers, BSD 3-Clause License
+# See LICENSE file for details
+
+"""
+Workspace Backends
+==================
+
+Backend implementations for the DataLab Kernel workspace.
+
+Available backends:
+
+- :class:`StandaloneBackend`: Local memory storage with HDF5 persistence
+- :class:`WebApiBackend`: HTTP/JSON + NPZ synchronization with DataLab
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "StandaloneBackend",
+    "WebApiBackend",
+    "WorkspaceBackend",
+]
+
+# Re-export base class from workspace module for convenience
+# Import backends
+from datalab_kernel.backends.standalone import StandaloneBackend
+from datalab_kernel.workspace import WorkspaceBackend
+
+try:
+    from datalab_kernel.backends.webapi import WebApiBackend
+except ImportError:
+    # httpx not installed, WebApiBackend not available
+    WebApiBackend = None  # type: ignore