or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

auth.mdconfiguration.mdcore-application.mdextensions.mdhandlers.mdindex.mdservices.md
tile.json

tessl/pypi-jupyter-server

The backend infrastructure for Jupyter web applications providing core services, APIs, and REST endpoints.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/jupyter-server@2.1.x

To install, run

npx @tessl/cli install tessl/pypi-jupyter-server@2.1.0

index.mddocs/

jupyter_server

A multi-user, extensible Jupyter server providing REST APIs and WebSocket channels for Jupyter frontend applications.

Package Information

  • Package Name: jupyter_server
  • Package Type: pypi
  • Language: Python
  • Installation: pip install jupyter_server
  • PyPI: https://pypi.org/project/jupyter-server/
  • Documentation: https://jupyter-server.readthedocs.io/
  • Source: https://github.com/jupyter-server/jupyter_server

Summary: The Jupyter Server is the backend—the server, web application, and various APIs—for Jupyter frontends like Notebook, JupyterLab, and Voila. It provides the common foundation that these frontends can build upon.

Key Dependencies:

  • tornado >= 6.1.0 (Web framework)
  • jupyter_client (Kernel management)
  • traitlets (Configuration system)
  • jupyter_core (Core Jupyter functionality)
  • nbformat (Notebook format handling)

Core Imports

# Version and constants
from jupyter_server import __version__, version_info
from jupyter_server import DEFAULT_JUPYTER_SERVER_PORT, DEFAULT_STATIC_FILES_PATH, DEFAULT_TEMPLATE_PATH_LIST

# Main application and server
from jupyter_server.serverapp import ServerApp, ServerWebApplication
from jupyter_server.serverapp import JupyterPasswordApp, JupyterServerStopApp, JupyterServerListApp

# Extension system
from jupyter_server.extension.application import ExtensionApp
from jupyter_server.extension.manager import ExtensionManager
from jupyter_server.extension.config import ExtensionConfigManager

# Service interfaces
from jupyter_server.services.contents.manager import ContentsManager, AsyncContentsManager
from jupyter_server.services.kernels.kernelmanager import MappingKernelManager, AsyncMappingKernelManager
from jupyter_server.services.sessions.sessionmanager import SessionManager

# Authentication and authorization
from jupyter_server.auth.identity import IdentityProvider, User, LegacyIdentityProvider
from jupyter_server.auth.authorizer import Authorizer, AllowAllAuthorizer
from jupyter_server.auth.decorator import authorized
from jupyter_server.auth.security import passwd, passwd_check, set_password

# Base handler classes
from jupyter_server.base.handlers import JupyterHandler, APIHandler, AuthenticatedFileHandler

# Configuration management
from jupyter_server.config_manager import BaseJSONConfigManager

# Gateway integration
from jupyter_server.gateway import GatewayClient, GatewayMappingKernelManager

Basic Usage

Starting a Jupyter Server

from jupyter_server.serverapp import ServerApp

# Create and configure server
app = ServerApp()
app.port = 8888
app.allow_remote_access = True
app.token = "my-secret-token"

# Initialize and start
app.initialize()
app.start()

Creating a Simple Extension

from jupyter_server.extension.application import ExtensionApp
from jupyter_server.base.handlers import JupyterHandler
from tornado.web import RequestHandler

class HelloHandler(JupyterHandler):
    def get(self):
        self.write({"message": "Hello from extension!"})

class MyExtension(ExtensionApp):
    name = "my_extension"

    def initialize_handlers(self):
        handlers = [(r"/my_extension/hello", HelloHandler)]
        self.handlers.extend(handlers)

# Load extension
def _load_jupyter_server_extension(serverapp):
    extension = MyExtension()
    extension.serverapp = serverapp
    extension.load_config_file()
    extension.initialize()

Architecture

The Jupyter Server follows a modular architecture with several key layers:

Core Application Layer

  • ServerApp: Main application coordinating all components
  • ServerWebApplication: Tornado web application wrapper
  • Extension System: Pluggable extension architecture

Service Layer

  • Contents Service: File and notebook management
  • Kernels Service: Jupyter kernel lifecycle management
  • Sessions Service: Kernel-frontend session management
  • Configuration Service: Runtime configuration management
  • API Services: REST endpoints and OpenAPI specifications

Security Layer

  • Identity Providers: User authentication mechanisms
  • Authorizers: Access control and permissions
  • Security Handlers: Login, logout, and CSRF protection

Handler Layer

  • Base Handlers: Core request handling infrastructure
  • Service Handlers: REST API endpoints for each service
  • WebSocket Handlers: Real-time communication channels

Core Application

➜ Core Application Reference

The ServerApp class and main server functionality for starting, configuring, and managing Jupyter servers.

# ServerApp configuration
from jupyter_server.serverapp import ServerApp

app = ServerApp()
app.port = 8888
app.ip = "127.0.0.1"
app.open_browser = False

Key capabilities:

  • Server lifecycle management (start, stop, restart)
  • Port and network configuration
  • SSL/TLS support for secure connections
  • Integration with system process management

Extension System

➜ Extensions Reference

Comprehensive extension framework for building Jupyter server applications and plugins.

# Extension development
from jupyter_server.extension.application import ExtensionApp

class MyApp(ExtensionApp):
    name = "my_jupyter_app"
    description = "My custom Jupyter application"

Key capabilities:

  • Extension discovery and loading
  • Extension-specific configuration
  • Handler registration and routing
  • Template and static file management

Service Modules

➜ Services Reference

Core service modules providing REST APIs and backend functionality for Jupyter frontends.

# Contents management
from jupyter_server.services.contents.manager import ContentsManager

# Kernel management
from jupyter_server.services.kernels.kernelmanager import MappingKernelManager

# Session management
from jupyter_server.services.sessions.sessionmanager import SessionManager

Key capabilities:

  • File and notebook CRUD operations
  • Kernel lifecycle management (start, stop, interrupt)
  • Session tracking and cleanup
  • Kernel specification management

Authentication and Authorization

➜ Auth Reference

Flexible authentication and authorization system supporting multiple identity providers and access control mechanisms.

# Custom identity provider
from jupyter_server.auth.identity import IdentityProvider, User

class MyIdentityProvider(IdentityProvider):
    async def get_user(self, request_handler) -> User | None:
        # Implement authentication logic
        return User(username="user", display_name="User Name")

Key capabilities:

  • Password-based authentication
  • Token-based authentication
  • Custom identity provider integration
  • Fine-grained authorization controls

Base Handlers and Utilities

➜ Handlers Reference

Base classes and utilities for building secure, authenticated web handlers and APIs.

# Custom API handler
from jupyter_server.base.handlers import APIHandler
from jupyter_server.auth.decorator import authorized

class MyAPIHandler(APIHandler):
    @authorized
    async def get(self):
        self.finish({"status": "success"})

Key capabilities:

  • Authenticated request handling
  • REST API base classes
  • WebSocket support for real-time communication
  • Static file serving with authentication

Configuration Management

➜ Configuration Reference

Powerful configuration system supporting JSON config files, command-line arguments, and runtime updates.

# Configuration management
from jupyter_server.services.config.manager import ConfigManager

config_manager = ConfigManager()
config = config_manager.get("my_section")
config_manager.set("my_section", "key", "value")

Key capabilities:

  • JSON-based configuration files
  • Runtime configuration updates
  • Extension-specific configuration sections
  • Configuration validation and defaults