0
# Web Request Handlers
1
2
The web request handlers manage HTTP requests for the different notebook interfaces, including the file browser, notebook editor, console, terminal, and file editor. These handlers serve the web-based user interface and manage the notebook's web application functionality.
3
4
## Capabilities
5
6
### Base Handler
7
8
The `NotebookBaseHandler` provides common functionality for all notebook web handlers, including page configuration and template rendering.
9
10
```python { .api }
11
class NotebookBaseHandler(ExtensionHandlerJinjaMixin, ExtensionHandlerMixin, JupyterHandler):
12
"""
13
The base notebook API handler.
14
15
Provides common functionality for all notebook web handlers including
16
page configuration, template rendering, and authentication.
17
"""
18
19
@property
20
def custom_css(self) -> Any:
21
"""
22
Whether custom CSS is enabled.
23
24
Returns:
25
Any: Custom CSS setting from application configuration
26
(returns self.settings.get("custom_css", True))
27
"""
28
29
def get_page_config(self) -> dict[str, Any]:
30
"""
31
Get the page configuration for the web interface.
32
33
Builds complete page configuration including application metadata,
34
URLs, authentication tokens, frontend settings, and JupyterHub
35
integration if applicable.
36
37
Returns:
38
dict[str, Any]: Complete page configuration for frontend
39
"""
40
```
41
42
### Tree/File Browser Handler
43
44
The `TreeHandler` manages requests for the file browser interface, handling directory listings and file navigation.
45
46
```python { .api }
47
class TreeHandler(NotebookBaseHandler):
48
"""
49
A tree page handler for the file browser interface.
50
51
Handles requests for directory listings and file navigation,
52
redirecting to appropriate editors based on file type.
53
"""
54
55
@web.authenticated
56
async def get(self, path: str = "") -> None:
57
"""
58
Display appropriate page for given path.
59
60
Behavior depends on path type:
61
- Directory: Shows directory listing/tree view
62
- Notebook file: Redirects to notebook editor
63
- Other files: Redirects to raw file view
64
65
Parameters:
66
- path: str, file system path relative to server root
67
68
Returns:
69
None: Renders template or performs redirect
70
71
Raises:
72
HTTPError: 404 if path doesn't exist or is hidden
73
"""
74
```
75
76
### Notebook Document Handler
77
78
The `NotebookHandler` manages requests for notebook document editing interface.
79
80
```python { .api }
81
class NotebookHandler(NotebookBaseHandler):
82
"""
83
A notebook page handler for the notebook editing interface.
84
85
Handles requests for notebook documents, providing the main
86
notebook editing environment.
87
"""
88
89
@web.authenticated
90
async def get(self, path: str = "") -> Any:
91
"""
92
Get the notebook page or redirect if path is a directory.
93
94
Parameters:
95
- path: str, notebook file path relative to server root
96
97
Returns:
98
Any: Rendered notebook template or redirect response
99
100
If the path is a directory, redirects to tree view.
101
Otherwise renders the notebook editing interface.
102
"""
103
```
104
105
### Console Handler
106
107
The `ConsoleHandler` manages requests for the console/kernel interface.
108
109
```python { .api }
110
class ConsoleHandler(NotebookBaseHandler):
111
"""
112
A console page handler for interactive console interface.
113
114
Provides access to interactive Python/kernel consoles
115
for code execution and debugging.
116
"""
117
118
@web.authenticated
119
def get(self, path: str | None = None) -> Any:
120
"""
121
Get the console page.
122
123
Parameters:
124
- path: str | None, optional path parameter (unused)
125
126
Returns:
127
Any: Rendered console template
128
129
Renders the console interface template with current
130
page configuration.
131
"""
132
```
133
134
### Terminal Handler
135
136
The `TerminalHandler` manages requests for the terminal interface.
137
138
```python { .api }
139
class TerminalHandler(NotebookBaseHandler):
140
"""
141
A terminal page handler for system terminal access.
142
143
Provides web-based terminal access for command line
144
operations and system administration.
145
"""
146
147
@web.authenticated
148
def get(self, path: str | None = None) -> Any:
149
"""
150
Get the terminal page.
151
152
Parameters:
153
- path: str | None, optional path parameter (unused)
154
155
Returns:
156
Any: Rendered terminal template
157
158
Renders the terminal interface template with current
159
page configuration.
160
"""
161
```
162
163
### File Editor Handler
164
165
The `FileHandler` manages requests for the file editing interface.
166
167
```python { .api }
168
class FileHandler(NotebookBaseHandler):
169
"""
170
A file page handler for text file editing interface.
171
172
Provides text editor functionality for non-notebook files
173
including source code, configuration files, and documentation.
174
"""
175
176
@web.authenticated
177
def get(self, path: str | None = None) -> Any:
178
"""
179
Get the file editor page.
180
181
Parameters:
182
- path: str | None, optional file path parameter (unused in current implementation)
183
184
Returns:
185
Any: Rendered file editor template
186
187
Renders the file editing interface template with current
188
page configuration.
189
"""
190
```
191
192
### Custom CSS Handler
193
194
The `CustomCssHandler` serves custom CSS files for interface customization.
195
196
```python { .api }
197
class CustomCssHandler(NotebookBaseHandler):
198
"""
199
A custom CSS handler for serving user customizations.
200
201
Serves custom CSS files to allow users to customize
202
the notebook interface appearance.
203
"""
204
205
@web.authenticated
206
def get(self) -> Any:
207
"""
208
Get the custom CSS file.
209
210
Returns:
211
Any: CSS file content with appropriate content type
212
213
Serves custom.css from the Jupyter configuration directory
214
or static directory if available. Sets appropriate CSS
215
content type header.
216
"""
217
```
218
219
## Usage Examples
220
221
### Handler Registration
222
223
```python
224
from notebook.app import JupyterNotebookApp
225
226
# Handlers are automatically registered by JupyterNotebookApp
227
app = JupyterNotebookApp()
228
app.initialize_handlers()
229
230
# The following URL patterns are registered:
231
# - "/tree(.*)" -> TreeHandler
232
# - "/notebooks(.*)" -> NotebookHandler
233
# - "/edit(.*)" -> FileHandler
234
# - "/consoles/(.*)" -> ConsoleHandler
235
# - "/terminals/(.*)" -> TerminalHandler
236
# - "/custom/custom.css" -> CustomCssHandler
237
```
238
239
### Page Configuration Access
240
241
```python
242
from notebook.app import NotebookBaseHandler
243
244
class CustomHandler(NotebookBaseHandler):
245
def get(self):
246
# Access page configuration
247
config = self.get_page_config()
248
249
# Configuration includes:
250
# - appVersion: Application version
251
# - baseUrl: Base URL for the server
252
# - token: Authentication token
253
# - terminalsAvailable: Whether terminals are enabled
254
# - preferredPath: Default directory path
255
# - Custom CSS settings
256
# - JupyterHub integration settings (if applicable)
257
258
return self.render_template("custom.html", page_config=config)
259
```
260
261
### Authentication and Error Handling
262
263
```python
264
from tornado import web
265
from notebook.app import NotebookBaseHandler
266
267
class SecureHandler(NotebookBaseHandler):
268
@web.authenticated # Requires user authentication
269
async def get(self, path: str = ""):
270
try:
271
# Check if path exists and is accessible
272
cm = self.contents_manager
273
if await cm.dir_exists(path=path):
274
# Handle directory
275
if await cm.is_hidden(path) and not cm.allow_hidden:
276
raise web.HTTPError(404, "Directory not found")
277
# Render directory view
278
elif await cm.file_exists(path):
279
# Handle file
280
# Render file view or redirect
281
else:
282
raise web.HTTPError(404, "Path not found")
283
except Exception as e:
284
# Handle errors appropriately
285
raise web.HTTPError(500, str(e))
286
```