0
# jupyter_server
1

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

4
## Package Information
5

6
- **Package Name**: jupyter_server
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install jupyter_server`
10
- **PyPI**: https://pypi.org/project/jupyter-server/
11
- **Documentation**: https://jupyter-server.readthedocs.io/
12
- **Source**: https://github.com/jupyter-server/jupyter_server
13

14
**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.
15

16
**Key Dependencies:**
17
- tornado >= 6.1.0 (Web framework)
18
- jupyter_client (Kernel management)
19
- traitlets (Configuration system)
20
- jupyter_core (Core Jupyter functionality)
21
- nbformat (Notebook format handling)
22

23
## Core Imports
24

25
```python { .api }
26
# Version and constants
27
from jupyter_server import __version__, version_info
28
from jupyter_server import DEFAULT_JUPYTER_SERVER_PORT, DEFAULT_STATIC_FILES_PATH, DEFAULT_TEMPLATE_PATH_LIST
29

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

34
# Extension system
35
from jupyter_server.extension.application import ExtensionApp
36
from jupyter_server.extension.manager import ExtensionManager
37
from jupyter_server.extension.config import ExtensionConfigManager
38

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

44
# Authentication and authorization
45
from jupyter_server.auth.identity import IdentityProvider, User, LegacyIdentityProvider
46
from jupyter_server.auth.authorizer import Authorizer, AllowAllAuthorizer
47
from jupyter_server.auth.decorator import authorized
48
from jupyter_server.auth.security import passwd, passwd_check, set_password
49

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

53
# Configuration management
54
from jupyter_server.config_manager import BaseJSONConfigManager
55

56
# Gateway integration
57
from jupyter_server.gateway import GatewayClient, GatewayMappingKernelManager
58
```
59

60
## Basic Usage
61

62
### Starting a Jupyter Server
63

64
```python { .api }
65
from jupyter_server.serverapp import ServerApp
66

67
# Create and configure server
68
app = ServerApp()
69
app.port = 8888
70
app.allow_remote_access = True
71
app.token = "my-secret-token"
72

73
# Initialize and start
74
app.initialize()
75
app.start()
76
```
77

78
### Creating a Simple Extension
79

80
```python
81
from jupyter_server.extension.application import ExtensionApp
82
from jupyter_server.base.handlers import JupyterHandler
83
from tornado.web import RequestHandler
84

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

89
class MyExtension(ExtensionApp):
90
    name = "my_extension"
91

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

96
# Load extension
97
def _load_jupyter_server_extension(serverapp):
98
    extension = MyExtension()
99
    extension.serverapp = serverapp
100
    extension.load_config_file()
101
    extension.initialize()
102
```
103

104
## Architecture
105

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

108
### Core Application Layer
109
- **ServerApp**: Main application coordinating all components
110
- **ServerWebApplication**: Tornado web application wrapper
111
- **Extension System**: Pluggable extension architecture
112

113
### Service Layer
114
- **Contents Service**: File and notebook management
115
- **Kernels Service**: Jupyter kernel lifecycle management
116
- **Sessions Service**: Kernel-frontend session management
117
- **Configuration Service**: Runtime configuration management
118
- **API Services**: REST endpoints and OpenAPI specifications
119

120
### Security Layer
121
- **Identity Providers**: User authentication mechanisms
122
- **Authorizers**: Access control and permissions
123
- **Security Handlers**: Login, logout, and CSRF protection
124

125
### Handler Layer
126
- **Base Handlers**: Core request handling infrastructure
127
- **Service Handlers**: REST API endpoints for each service
128
- **WebSocket Handlers**: Real-time communication channels
129

130
## Core Application
131

132
**[➜ Core Application Reference](core-application.md)**
133

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

136
```python { .api }
137
# ServerApp configuration
138
from jupyter_server.serverapp import ServerApp
139

140
app = ServerApp()
141
app.port = 8888
142
app.ip = "127.0.0.1"
143
app.open_browser = False
144
```
145

146
Key capabilities:
147
- Server lifecycle management (start, stop, restart)
148
- Port and network configuration
149
- SSL/TLS support for secure connections
150
- Integration with system process management
151

152
## Extension System
153

154
**[➜ Extensions Reference](extensions.md)**
155

156
Comprehensive extension framework for building Jupyter server applications and plugins.
157

158
```python { .api }
159
# Extension development
160
from jupyter_server.extension.application import ExtensionApp
161

162
class MyApp(ExtensionApp):
163
    name = "my_jupyter_app"
164
    description = "My custom Jupyter application"
165
```
166

167
Key capabilities:
168
- Extension discovery and loading
169
- Extension-specific configuration
170
- Handler registration and routing
171
- Template and static file management
172

173
## Service Modules
174

175
**[➜ Services Reference](services.md)**
176

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

179
```python { .api }
180
# Contents management
181
from jupyter_server.services.contents.manager import ContentsManager
182

183
# Kernel management
184
from jupyter_server.services.kernels.kernelmanager import MappingKernelManager
185

186
# Session management
187
from jupyter_server.services.sessions.sessionmanager import SessionManager
188
```
189

190
Key capabilities:
191
- File and notebook CRUD operations
192
- Kernel lifecycle management (start, stop, interrupt)
193
- Session tracking and cleanup
194
- Kernel specification management
195

196
## Authentication and Authorization
197

198
**[➜ Auth Reference](auth.md)**
199

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

202
```python{ .api }
203
# Custom identity provider
204
from jupyter_server.auth.identity import IdentityProvider, User
205

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

212
Key capabilities:
213
- Password-based authentication
214
- Token-based authentication
215
- Custom identity provider integration
216
- Fine-grained authorization controls
217

218
## Base Handlers and Utilities
219

220
**[➜ Handlers Reference](handlers.md)**
221

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

224
```python{ .api }
225
# Custom API handler
226
from jupyter_server.base.handlers import APIHandler
227
from jupyter_server.auth.decorator import authorized
228

229
class MyAPIHandler(APIHandler):
230
    @authorized
231
    async def get(self):
232
        self.finish({"status": "success"})
233
```
234

235
Key capabilities:
236
- Authenticated request handling
237
- REST API base classes
238
- WebSocket support for real-time communication
239
- Static file serving with authentication
240

241
## Configuration Management
242

243
**[➜ Configuration Reference](configuration.md)**
244

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

247
```python{ .api }
248
# Configuration management
249
from jupyter_server.services.config.manager import ConfigManager
250

251
config_manager = ConfigManager()
252
config = config_manager.get("my_section")
253
config_manager.set("my_section", "key", "value")
254
```
255

256
Key capabilities:
257
- JSON-based configuration files
258
- Runtime configuration updates
259
- Extension-specific configuration sections
260
- Configuration validation and defaults