Jupyter Integration

Run and monitor Jupyter notebook servers directly from Stanza’s CLI. The integration provides persistent server management, real-time notebook monitoring, and automatic cell output logging - all designed to streamline interactive development workflows.

Quick Start

Installation Requirements

Jupyter integration requires additional dependencies:

pip install "cq-stanza[notebook]"

This installs:

• jupyter_server for server management
• jupyter_core for runtime discovery
• Required dependencies for log streaming and monitoring

Start a Jupyter server in your project directory:

# Start server on default port 8888
stanza jupyter start
# Start in specific directory with custom port
stanza jupyter start /path/to/notebooks --port 8889
# Check server status
stanza jupyter status
# Open Jupyter in browser
stanza jupyter open

The server runs in the background and persists across terminal sessions, making it ideal for long-running experiments on remote machines.

Server Management

Starting the Server

Launch a persistent Jupyter server that survives terminal closure:

from stanza.jupyter import start
from pathlib import Path
# Start server programmatically
state = start(notebook_dir=Path.cwd(), port=8888)
print(f"Server running at: {state['url']}")
print(f"PID: {state['pid']}")

Or via CLI:

stanza jupyter start

The server automatically configures:

• Auto-logging of cell outputs to notebook_name.log files
• Authentication tokens for secure access
• Background process management with graceful shutdown

Checking Status

Get server information including uptime and URL:

from stanza.jupyter import status
server_status = status()
if server_status:
    print(f"PID: {server_status['pid']}")
    print(f"URL: {server_status['url']}")
    print(f"Uptime: {server_status['uptime_seconds']:.0f}s")
    print(f"Root: {server_status['root_dir']}")
else:
    print("No server running")

Via CLI:

stanza jupyter status

Stopping the Server

Gracefully shutdown using escalating strategies (REST API CMD → SIGTERM → SIGKILL):

from stanza.jupyter import stop
stop()

Via CLI:

stanza jupyter stop

Notebook Monitoring

Listing Active Sessions

View all running notebook kernels with their log file metadata:

from stanza.jupyter import list_sessions
sessions = list_sessions()
for session in sessions:
    print(f"Notebook: {session['notebook_path']}")
    print(f"Log: {session['log_path']}")
    print(f"Lines: {session['line_count']}")

Via CLI:

stanza jupyter list

Viewing Logs

Monitor notebook output in real-time without interrupting execution:

# List all notebook logs
stanza jupyter logs
# Tail a specific notebook's output (Ctrl+C to detach)
stanza jupyter logs my_notebook.ipynb
# Show last 20 lines of context
stanza jupyter logs my_notebook.ipynb -n 20

The logs command is useful for monitoring long-running experiments while preserving the ability to detach without affecting the notebook kernel.

Attaching to Notebooks

Connect directly to a notebook kernel with interactive control:

# Attach with kernel control (Ctrl+C kills kernel, ESC exits)
stanza jupyter attach my_notebook.ipynb
# Show more initial context
stanza jupyter attach my_notebook.ipynb -n 30

When attached:

• Ctrl+C: Kills the notebook kernel and exits
• ESC (twice): Exits without killing the kernel
• Output streams in real-time directly to your terminal

This mode is ideal for active development and debugging when you need full control over kernel lifecycle.

Python API Examples

Complete Server Workflow

from pathlib import Path
from stanza.jupyter import start, status, list_sessions, stop
# Start server
notebook_dir = Path("./experiments")
state = start(notebook_dir=notebook_dir, port=8888)
print(f"Started: {state['url']}")
# Check status
server_status = status()
print(f"Uptime: {server_status['uptime_seconds']:.0f}s")
# List running notebooks
sessions = list_sessions()
print(f"Active notebooks: {len(sessions)}")
# Cleanup
stop()

Programmatic Log Streaming

from pathlib import Path
from stanza.jupyter import log_stream
# Follow a notebook's log file
log_file = Path("./experiments/analysis.log")
log_stream.follow(log_file, lines=10)

Kernel Management

from stanza.jupyter import kill_kernel
# Stop a specific notebook's kernel
kill_kernel("analysis.ipynb")

Auto-Logging

When you start the Jupyter server through Stanza, cell outputs are automatically logged to {notebook_name}.log files in the same directory as each notebook. This enables:

• Persistent record of all cell executions
• Real-time monitoring via stanza jupyter logs
• Post-experiment analysis without re-running cells

Log files capture stdout, stderr, and display outputs, providing a complete record of your notebook’s execution history.

Remote Development

For SSH sessions to lab computers, use port forwarding to access Jupyter in your local browser:

# On your local machine
ssh -L 8888:localhost:8888 user@lab-computer
# On the remote machine
stanza jupyter start
stanza jupyter status  # Copy the URL
# Open the URL in your local browser

The persistent server ensures your notebooks keep running even if your SSH connection drops.

Tips and Best Practices

Background execution: The server runs as a detached process, so you can close your terminal without stopping Jupyter. Use stanza jupyter status to rediscover the URL after reconnecting.

Monitor long experiments: Use stanza jupyter logs to check progress on multi-hour measurements without opening the browser or disrupting execution.

Clean shutdown: Always use stanza jupyter stop to gracefully shutdown the server. This ensures proper cleanup of runtime files and state.

Port conflicts: If port 8888 is already in use, specify a different port with --port 8889 when starting the server.

Next Steps

• Data Logging - Configure automatic logging for routine outputs
• Live Plotting - Visualize data in real-time as measurements run