nbstager 0.1.0

Jupyter Server extension for staging notebook workspaces from repositories, parameters, and data URLs.

NBStager

NBStager is a Jupyter Server extension for preparing notebook workspaces from launch URLs.

It can:

• write launch parameters into a .env file;
• stage data files from HTTP(S) URLs;
• redirect to a notebook in JupyterLab.

NBStager is designed to work in Binder, JupyterHub, and local JupyterLab environments.

Install

From PyPI, once published:

pip install nbstager

From GitHub:

pip install git+https://github.com/recap/nbstager.git@v0.1.0

For development:

pip install -e .

The package includes a Jupyter Server config file that enables the extension automatically. If needed, enable it manually:

jupyter server extension enable --py nbstager --sys-prefix

Check:

jupyter server extension list

Endpoint

NBStager registers this route:

/launch

Example local URL:

http://localhost:8888/launch?notebookpath=mynotebook.ipynb&DATASET_URL=https://example.org/data.csv

Reserved query parameters

Parameter	Required	Default	Description
notebookpath	no	—	Notebook path relative to the target repository root.
data	no	—	JSON object or array describing data files to download.

All other query parameters are written to .env.

Passing notebook parameters

/launch?notebookpath=mynotebook.ipynb&DATASET_URL=https://example.org/data.csv

creates:

DATASET_URL=https://example.org/data.csv

inside:

.env

Python notebooks can read it with:

from dotenv import load_dotenv
import os

load_dotenv('.env')
print(os.getenv('DATASET_URL'))

R notebooks can read it with:

library(dotenv)
load_dot_env('.env')
Sys.getenv('DATASET_URL')

Data staging

The data parameter accepts JSON.

Decoded example:

[
  {
    "url": "https://example.org/customers.csv",
    "path": "data/customers.csv"
  }
]

NBStager downloads the files into the workspace and writes:

data_manifest.json

Binder usage

In Binder, install NBStager in your requirements.txt. Then launch a target repository through the wrapper with:

https://mybinder.org/v2/gh/OWNER/WRAPPER_REPO/main?urlpath=launch?notebookpath=mynotebook.ipynb&DATASET_URL=https://example.org/data.csv