Metadata-Version: 2.5
Name: jupyterlab_slurm
Version: 4.1.0
Dynamic: Keywords
Summary: A JupyterLab extension to interface with the Slurm workload manager.
Project-URL: Homepage, https://github.com/NERSC/jupyterlab-slurm
Project-URL: Bug Tracker, https://github.com/NERSC/jupyterlab-slurm/issues
Project-URL: Repository, https://github.com/NERSC/jupyterlab-slurm.git
Author: Matt Henderson, LBNL
License: 
        BSD 3-Clause License
        
        Copyright (c) 2018, NERSC
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        * Redistributions of source code must retain the above copyright notice, this
          list of conditions and the following disclaimer.
        
        * 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.
        
        * 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.
License-File: AUTHORS
License-File: LICENSE
Classifier: Framework :: Jupyter
Classifier: Framework :: Jupyter :: JupyterLab
Classifier: Framework :: Jupyter :: JupyterLab :: 4
Classifier: Framework :: Jupyter :: JupyterLab :: Extensions
Classifier: Framework :: Jupyter :: JupyterLab :: Extensions :: Prebuilt
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: jupyter-server<3,>=2.0.1
Provides-Extra: docs
Requires-Dist: myst-parser; extra == 'docs'
Requires-Dist: sphinx; extra == 'docs'
Requires-Dist: sphinx-rtd-theme; extra == 'docs'
Requires-Dist: sphinxcontrib-mermaid; extra == 'docs'
Provides-Extra: test
Requires-Dist: coverage; extra == 'test'
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-asyncio; extra == 'test'
Requires-Dist: pytest-cov; extra == 'test'
Requires-Dist: pytest-jupyter[server]>=0.6.0; extra == 'test'
Requires-Dist: tornado<6.5.9; extra == 'test'
Description-Content-Type: text/markdown

# Slurm JupyterLab Extension

A JupyterLab extension that interfaces with the Slurm Workload Manager,
providing simple and intuitive controls for viewing and managing jobs on the queue.

![Slurm Extension](./docs/images/slurm.png)

## Prerequisites

- JupyterLab 4.5.7
- Slurm

## Architecture

This extension consists of two main parts:

- **Backend (Python)**: A Jupyter Server extension that provides a REST API to interface with Slurm commands (`squeue`, `sbatch`, `scancel`, `scontrol`, `sacct`).
  - Handlers are located in `jupyterlab_slurm/handlers.py`.
  - It uses a base class `SlurmCommandHandler` to execute shell commands and handle errors.
  - Job details use a specialized `JobDetailsHandler` that normalizes data from both `scontrol` and `sacct`.
- **Frontend (TypeScript/React)**: A JupyterLab extension that provides the UI.
  - Built with React, MUI (Material UI), and `ag-grid-react` for high-performance table rendering.
  - Main components: `SlurmWidget` (top-level), `SqueueDataTable` (live queue), `SlurmJobHistory` (completed jobs), and `JobDetailsPanel` (detailed inspection).
  - State management handles polling, selection snapshots, and navigation between job details.

## Installation

This extension includes both a client-side JupyterLab extension and a server-side
Jupyter notebook server extension. Install these using the command line with

```bash
pip install jupyterlab_slurm
```

If you are running Notebook 5.2 or earlier, enable the server extension by running

```bash
jupyter serverextension enable --py --sys-prefix jupyterlab_slurm
```

After launching JupyterLab, the extension can be found in the command palette under
the name `Slurm Dashboard`, and is listed under the `HPC TOOLS` section
of the palette and the launcher.

### Development install

As described in the [JupyterLab documentation](https://jupyterlab.readthedocs.io/en/stable/extension/extension_dev.html#extension-authoring) for a development install of the labextension you can run the following in this directory:

```bash
# install the extension in editable mode
pip install -e .
# point the labextension dev install at the current dir
jupyter labextension develop --overwrite .
# rerun this if there are updates:
jlpm run build
```

### Testing against a local Slurm cluster

For realistic, end-to-end testing against a real Slurm controller, this repo
builds on top of the upstream
[`giovtorres/slurm-docker-cluster`](https://github.com/giovtorres/slurm-docker-cluster)
project, which provides a Docker Compose stack running a current,
version-selectable Slurm (multi-arch, with pre-built images). It is a plain
git checkout (not a submodule) into `docker/slurm-cluster`, which is
git-ignored in this repo. `docker/cluster.sh up` automates checking it out
and bringing it up (see `docker/README.md` for the full set of automated
commands and the manual steps they replace), then install this extension
(`pip install -e .`) into a
JupyterLab 4 environment that shares the cluster's munge key and
`/etc/slurm` so the Slurm client commands can connect. `docker/jupyterhub/`
builds on top of that cluster to also exercise per-user JupyterHub spawning
against it.
