tessl/pypi-jupyterhub

A multi-user server for Jupyter notebooks that provides authentication, spawning, and proxying for multiple users simultaneously

—

Pending

Overview

Eval results

Files

Core Application Management

Name: tessl/pypi-jupyterhub
Author: tessl

The JupyterHub application system provides the main orchestration layer for the multi-user notebook server. It manages configuration, initialization, startup, and shutdown processes for the entire JupyterHub deployment.

Capabilities

Main Application Class

The primary JupyterHub application class that coordinates all system components including the hub server, proxy, database, and user management.

class JupyterHub(Application):
    """
    The JupyterHub application class.
    
    Manages the overall JupyterHub system including configuration,
    initialization, and coordination of all components.
    """
    
    # Configuration attributes
    ip: str  # IP address to bind to
    port: int  # Port to bind to  
    hub_ip: str  # Hub internal IP
    hub_port: int  # Hub internal port
    base_url: str  # Base URL prefix
    db_url: str  # Database URL
    
    # Component classes
    authenticator_class: str  # Authenticator to use
    spawner_class: str  # Spawner to use
    proxy_class: str  # Proxy to use
    
    def initialize(self, argv=None):
        """
        Initialize the application.
        
        Args:
            argv: Command line arguments
        """
    
    def start(self):
        """
        Start the JupyterHub application.
        
        Starts the tornado web server and begins handling requests.
        """
    
    def stop(self):
        """
        Stop the JupyterHub application.
        
        Gracefully shuts down all components.
        """
    
    def cleanup(self):
        """
        Cleanup on shutdown.
        
        Stops spawners, closes database connections, etc.
        """

Entry Point Functions

Command-line entry points for starting JupyterHub components.

def main(argv=None):
    """
    Main entry point for the jupyterhub command.
    
    Args:
        argv: Command line arguments (defaults to sys.argv)
        
    Returns:
        Exit code (0 for success)
    """

def singleuser_main(argv=None):  
    """
    Main entry point for jupyterhub-singleuser command.
    
    Args:
        argv: Command line arguments
        
    Returns:
        Exit code (0 for success)
    """

Configuration Management

JupyterHub uses the traitlets configuration system for managing settings.

# Configuration access pattern
from traitlets.config import get_config

c = get_config()

# Core settings
c.JupyterHub.ip = '0.0.0.0'
c.JupyterHub.port = 8000
c.JupyterHub.base_url = '/'

# Database
c.JupyterHub.db_url = 'sqlite:///jupyterhub.sqlite'

# Authentication  
c.JupyterHub.authenticator_class = 'pam'
c.Authenticator.admin_users = {'admin'}

# Spawning
c.JupyterHub.spawner_class = 'localprocess'
c.Spawner.start_timeout = 60

Usage Examples

Basic Deployment

# Create minimal JupyterHub instance
from jupyterhub.app import JupyterHub

app = JupyterHub()
app.ip = '0.0.0.0'
app.port = 8000
app.initialize()
app.start()

Configuration File Deployment

# jupyterhub_config.py
c = get_config()

# Network configuration
c.JupyterHub.ip = '0.0.0.0'
c.JupyterHub.port = 8000
c.JupyterHub.hub_ip = '127.0.0.1'

# Use dummy authenticator for testing
c.JupyterHub.authenticator_class = 'dummy'

# Set admin users
c.Authenticator.admin_users = {'admin', 'teacher'}

# Configure spawner
c.JupyterHub.spawner_class = 'localprocess'
c.LocalProcessSpawner.create_system_users = True

# Database
c.JupyterHub.db_url = 'postgresql://user:password@localhost/jupyterhub'

Programmatic Control

import asyncio
from jupyterhub.app import JupyterHub

async def run_hub():
    """Run JupyterHub programmatically"""
    app = JupyterHub()
    
    # Configure programmatically
    app.ip = '127.0.0.1'
    app.port = 8000
    app.authenticator_class = 'dummy'
    
    # Initialize and start
    app.initialize()
    
    try:
        await app.start()
    except KeyboardInterrupt:
        await app.stop()
        await app.cleanup()

# Run the hub
asyncio.run(run_hub())

Integration Patterns

Custom Application Subclass

from jupyterhub.app import JupyterHub

class CustomJupyterHub(JupyterHub):
    """Custom JupyterHub with additional functionality"""
    
    def initialize(self, argv=None):
        """Initialize with custom setup"""
        super().initialize(argv)
        
        # Add custom initialization
        self.setup_custom_components()
    
    def setup_custom_components(self):
        """Setup custom components"""
        # Add custom handlers, services, etc.
        pass

Service Integration

# Add external services to JupyterHub
c.JupyterHub.services = [
    {
        'name': 'announcement',
        'url': 'http://localhost:8001',
        'command': ['python', '/path/to/announcement-service.py'],
        'oauth_redirect_uri': 'http://localhost:8001/oauth-callback'
    }
]

Install with Tessl CLI