jupyterlab-notifications-extension 1.0.19

Jupyterlab extension to receive and display notifications in the main panel. Those can be from the jupyterjub administrator or from other places.

jupyterlab_notifications_extension

JupyterLab extension enabling external systems to send notifications that appear in JupyterLab's notification center. Administrators, monitoring systems, and CI/CD pipelines broadcast alerts and status updates to users via a simple REST API.

The extension provides a POST endpoint for notification ingestion and polls every 30 seconds to display new notifications using JupyterLab's native notification system. Supports multiple notification types, configurable auto-close behavior, and optional action buttons.

Installation

pip install jupyterlab_notifications_extension

Requirements: JupyterLab >= 4.0.0

API Reference

POST /jupyterlab-notifications-extension/ingest

Send notifications to JupyterLab users. Requires authentication via Authorization: token <TOKEN> header or ?token=<TOKEN> query parameter.

Endpoint: POST /jupyterlab-notifications-extension/ingest

Request Body (application/json):

{
  "message": "Your notification message",
  "type": "info",
  "autoClose": 5000,
  "actions": [
    {
      "label": "Click here",
      "caption": "Additional info",
      "displayType": "accent"
    }
  ]
}

Request Parameters:

Field	Type	Required	Default	Description
message	string	Yes	-	Notification text displayed to users
type	string	No	"info"	Visual style: default, info, success, warning, error, in-progress
autoClose	number/boolean	No	5000	Milliseconds before auto-dismiss. false = manual dismiss only. 0 = silent mode (notification center only, no toast)
actions	array	No	[]	Action buttons (see below)

Action Button Schema:

Field	Type	Required	Default	Description
label	string	Yes	-	Button text
caption	string	No	""	Tooltip text
displayType	string	No	"default"	Visual style: default, accent, warn, link

Note: Action buttons are purely visual. Clicking any button dismisses the notification using JupyterLab's native behavior. Buttons do not trigger custom callbacks or actions.

Response (200 OK):

{
  "success": true,
  "notification_id": "notif_1762549476180_0"
}

Error Responses:

• 400 Bad Request - Missing message field or invalid JSON
• 401 Unauthorized - Missing or invalid authentication token
• 500 Internal Server Error - Server-side processing error

Usage Examples

Python Script

The included script auto-detects tokens from JUPYTERHUB_API_TOKEN, JPY_API_TOKEN, or JUPYTER_TOKEN environment variables:

# Basic notification
./scripts/send_notification.py --message "Deployment complete" --type success

# Persistent warning (no auto-close)
./scripts/send_notification.py --message "System maintenance in 1 hour" --type warning --no-auto-close

# Silent mode (notification center only)
./scripts/send_notification.py --message "Background task finished" --auto-close 0

cURL

# Basic info notification
curl -X POST http://localhost:8888/jupyterlab-notifications-extension/ingest \
  -H "Content-Type: application/json" \
  -H "Authorization: token YOUR_TOKEN" \
  -d '{"message": "Build completed", "type": "info"}'

# Error notification with action button
curl -X POST http://localhost:8888/jupyterlab-notifications-extension/ingest \
  -H "Content-Type: application/json" \
  -H "Authorization: token YOUR_TOKEN" \
  -d '{
    "message": "Build failed on main branch",
    "type": "error",
    "autoClose": false,
    "actions": [{
      "label": "View Logs",
      "caption": "Open build logs",
      "displayType": "accent"
    }]
  }'

Architecture

Broadcast-only model - all notifications delivered to all users.

Flow: External system POSTs to /jupyterlab-notifications-extension/ingest -> Server queues in memory -> Frontend polls /jupyterlab-notifications-extension/notifications every 30 seconds -> Displays via JupyterLab notification manager -> Clears queue after fetch.

Troubleshooting

Frontend installed but not working:

jupyter server extension list  # Verify server extension enabled

Server extension enabled but frontend missing:

jupyter labextension list  # Verify frontend extension installed

Notifications not appearing: Check browser console for polling errors or verify JupyterLab was restarted after installation.

Uninstall

pip uninstall jupyterlab_notifications_extension

Development

Setup

Requires NodeJS to build the extension. Uses jlpm (JupyterLab's pinned yarn) for package management.

# Install in development mode
python -m venv .venv
source .venv/bin/activate
pip install --editable ".[dev,test]"

# Link extension with JupyterLab
jupyter labextension develop . --overwrite
jupyter server extension enable jupyterlab_notifications_extension

# Build TypeScript
jlpm build

Development workflow

Run jlpm watch in one terminal to auto-rebuild on changes, and jupyter lab in another. Refresh browser after rebuilds to load changes.

jlpm watch           # Auto-rebuild on file changes
jupyter lab          # Run JupyterLab

Cleanup

jupyter server extension disable jupyterlab_notifications_extension
pip uninstall jupyterlab_notifications_extension
# Remove symlink: find via `jupyter labextension list`

Testing

Python tests (Pytest):

pip install -e ".[test]"
pytest -vv -r ap --cov jupyterlab_notifications_extension

Frontend tests (Jest):

jlpm test

Integration tests (Playwright/Galata): See ui-tests/README.md

Packaging

See RELEASE.md for release procedures.