jupyter_server.base package#


Provides access to variables pertaining to specific call contexts.

class jupyter_server.base.call_context.CallContext#

Bases: object

CallContext essentially acts as a namespace for managing context variables.

Although not required, it is recommended that any “file-spanning” context variable names (i.e., variables that will be set or retrieved from multiple files or services) be added as constants to this class definition.


Provides access to the current request handler once set.

classmethod context_variable_names()#

Returns a list of variable names set for this call context.


names – A list of variable names set for this call context.

Return type:


classmethod get(name)#

Returns the value corresponding the named variable relative to this context.

If the named variable doesn’t exist, None will be returned.


name (str) – The name of the variable to get from the call context


value – The value associated with the named variable for this call context

Return type:


classmethod set(name, value)#

Sets the named variable to the specified value in the current call context.

  • name (str) – The name of the variable to store into the call context

  • value (Any) – The value of the variable to store into the call context

Return type:


Base Tornado handlers for the Jupyter server.

class jupyter_server.base.handlers.APIHandler(application, request, **kwargs)#

Bases: JupyterHandler

Base class for API handlers

property content_security_policy#

The default Content-Security-Policy header

Can be overridden by defining Content-Security-Policy in settings[‘headers’]

finish(*args, **kwargs)#

Finish an API response.


Get the login url.

options(*args, **kwargs)#

Get the options.

async prepare()#

Prepare an API response.


Update last_activity of API requests

write_error(status_code, **kwargs)#

APIHandler errors are JSON, not human pages

class jupyter_server.base.handlers.APIVersionHandler(application, request, **kwargs)#

Bases: APIHandler

An API handler for the server version.


Get the server version info.

class jupyter_server.base.handlers.AuthenticatedFileHandler(application, request, **kwargs)#

Bases: JupyterHandler, StaticFileHandler

static files should only be accessible when logged in

auth_resource = 'contents'#

Compute the etag.

property content_security_policy#

The default Content-Security-Policy header

Can be overridden by defining Content-Security-Policy in settings[‘headers’]

get(path, **kwargs)#

Get a file by path.


Get the content type.


Get the head response for a path.


Set the headers.

validate_absolute_path(root, absolute_path)#

Validate and return the absolute path.

Requires tornado 3.1

Adding to tornado’s own handling, forbids the serving of hidden files.

class jupyter_server.base.handlers.AuthenticatedHandler(application, request, **kwargs)#

Bases: RequestHandler

A RequestHandler with an authenticated user.

property authorizer#
property base_url: str#

Clear a login cookie.

property content_security_policy#

The default Content-Security-Policy header

Can be overridden by defining Content-Security-Policy in settings[‘headers’]

property cookie_name#

Force a cookie clear.


Get the current user.

property identity_provider#
property logged_in#

Is a user currently logged in?

property login_available#

May a user proceed to log in?

This returns True if login capability is available, irrespective of whether the user is already logged in or not.

property login_handler#

Return the login handler for this application, if any.


Set the default headers.


Ask my login_handler if I should skip the origin_check

For example: in the default LoginHandler, if a request is token-authenticated, origin checking should be skipped.

property token#

Return the login token for this application, if any.

property token_authenticated#

Have I been authenticated with a token?

class jupyter_server.base.handlers.FileFindHandler(application, request, **kwargs)#

Bases: JupyterHandler, StaticFileHandler

subclass of StaticFileHandler for serving files from a search path

The setting “static_immutable_cache” can be set up to serve some static file as immutable (e.g. file name containing a hash). The setting is a list of base URL, every static file URL starting with one of those will be immutable.


Compute the etag.

classmethod get_absolute_path(roots, path)#

locate a file to serve on our static file search path

initialize(path, default_filename=None, no_cache_paths=None)#

Initialize the file find handler.

root: tuple#

Set the headers.

validate_absolute_path(root, absolute_path)#

check if the file should be served (raises 404, 403, etc.)

class jupyter_server.base.handlers.FilesRedirectHandler(application, request, **kwargs)#

Bases: JupyterHandler

Handler for redirecting relative URLs to the /files/ handler

async static redirect_to_files(self, path)#

make redirect logic a reusable static method

so it can be called from other handlers.

class jupyter_server.base.handlers.JupyterHandler(application, request, **kwargs)#

Bases: AuthenticatedHandler

Jupyter-specific extensions to authenticated handling

Mostly property shortcuts to Jupyter-specific settings.

property allow_credentials#

Whether to set Access-Control-Allow-Credentials

property allow_origin#

Normal Access-Control-Allow-Origin

property allow_origin_pat#

Regular expression version of allow_origin


Check the host header if remote access disallowed.

Returns True if the request should continue, False otherwise.


Check Origin for cross-site API requests, including websockets

Copied from WebSocket with changes:

  • allow unspecified host/origin (e.g. scripts)

  • allow token-authenticated requests


Check Referer for cross-site requests. Disables requests to certain endpoints with external or missing Referer. If set, allow_origin settings are applied to the Referer to whitelist specific cross-origin sites. Used on GET for api endpoints and /files/ to block cross-site inclusion (XSSI).

Bypass xsrf cookie checks when token-authenticated

property config#
property config_manager#
property contents_js_source#
property contents_manager#
property default_url#
property event_logger: EventLogger#

Return the body of the request as JSON data.


Return the jinja template object for a given name

property jinja_template_vars#

User-supplied values to supply to jinja templates.

property kernel_manager#
property kernel_spec_manager#
property log#

use the Jupyter log by default, falling back on tornado’s logger

property mathjax_config#
property mathjax_url#
async prepare()#

Pepare a response.

render_template(name, **ns)#

Render a template by name.

property serverapp#
property session_manager#

Set Content-Disposition: attachment header

As a method to ensure handling of filename encoding


Add CORS headers, if defined

Now that current_user is async (jupyter-server 2.0), must be called at the end of prepare(), instead of in set_default_headers.


Add CORS headers, if defined

property template_namespace#
property terminal_manager#
property version_hash#

The version hash to use for cache hints for static files

write_error(status_code, **kwargs)#

render custom error pages

property ws_url#
class jupyter_server.base.handlers.MainHandler(application, request, **kwargs)#

Bases: JupyterHandler

Simple handler for base_url.


Get the main template.


Get the main template.


Get the main template.

class jupyter_server.base.handlers.PrometheusMetricsHandler(application, request, **kwargs)#

Bases: JupyterHandler

Return prometheus metrics for this server


Get prometheus metrics.

class jupyter_server.base.handlers.RedirectWithParams(application, request, **kwargs)#

Bases: RequestHandler

Sam as web.RedirectHandler, but preserves URL parameters


Get a redirect.

initialize(url, permanent=True)#

Initialize a redirect handler.

class jupyter_server.base.handlers.Template404(application, request, **kwargs)#

Bases: JupyterHandler

Render our 404 template

async prepare()#

Prepare a 404 response.

class jupyter_server.base.handlers.TrailingSlashHandler(application, request, **kwargs)#

Bases: RequestHandler

Simple redirect handler that strips trailing slashes

This should be the first, highest priority handler.


Handle trailing slashes in a get.


Handle trailing slashes in a get.


Handle trailing slashes in a get.


Decorate methods with this to return GitHub style JSON errors.

This should be used on any JSON API on any handler method that can raise HTTPErrors.

This will grab the latest HTTPError exception using sys.exc_info and then:

  1. Set the HTTP status code based on the HTTPError

  2. Create and return a JSON body with a message field describing the error in a human readable form.


Get sys info as json.


Get the application log.

Base websocket classes.

class jupyter_server.base.websocket.WebSocketMixin#

Bases: object

Mixin for common websocket options


Check Origin == Host or Access-Control-Allow-Origin.

Tornado >= 4 calls this method automatically, raising 403 if it returns False.

meaningless for websockets

last_ping = 0.0#
last_pong = 0.0#

Handle a pong message.

open(*args, **kwargs)#

Open the websocket.

ping_callback = None#
property ping_interval#

The interval for websocket keep-alive pings.

Set ws_ping_interval = 0 to disable pings.

property ping_timeout#

If no ping is received in this many milliseconds, close the websocket connection (VPNs, etc. can fail to cleanly close ws connections). Default is max of 3 pings or 30 seconds.


send a ping to keep the websocket alive

stream: Optional[IOStream] = None#

This module is deprecated in Jupyter Server 2.0

Module contents#