jupyter_server.gateway package#

Submodules#

Gateway connection classes.

class jupyter_server.gateway.connections.GatewayWebSocketConnection(**kwargs)#

Bases: BaseKernelWebsocketConnection

Web socket connection that proxies to a kernel/enterprise gateway.

async connect()#: Connect to the socket.

disconnect()#: Handle a disconnect.

disconnected#: A boolean (True, False) trait.

handle_incoming_message(message)#

Send message to gateway server.

Return type:: None

handle_outgoing_message(incoming_msg, *args)#

Send message to the notebook client.

Return type:: None

kernel_ws_protocol#: A trait for unicode strings.

retry#: An int trait.

ws#

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

Subclasses can declare default classes by overriding the klass attribute

ws_future#

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

Subclasses can declare default classes by overriding the klass attribute

A kernel gateway client.

class jupyter_server.gateway.gateway_client.GatewayClient(**kwargs: Any)#

Bases: SingletonConfigurable

This class manages the configuration. It’s its own singleton class so that we can share these values across all objects. It also contains some options. helper methods to build request arguments out of the various config

KERNEL_LAUNCH_TIMEOUT = 40#

accept_cookies#: Accept and manage cookies sent by the service side. This is often useful for load balancers to decide which backend node to use. (JUPYTER_GATEWAY_ACCEPT_COOKIES env var)

accept_cookies_env = 'JUPYTER_GATEWAY_ACCEPT_COOKIES'#

accept_cookies_value = False#

allowed_envs#: A comma-separated list of environment variable names that will be included, along with their values, in the kernel startup request. The corresponding client_envs configuration value must also be set on the Gateway server - since that configuration value indicates which environmental values to make available to the kernel. (JUPYTER_GATEWAY_ALLOWED_ENVS env var)

allowed_envs_default_value = ''#

allowed_envs_env = 'JUPYTER_GATEWAY_ALLOWED_ENVS'#

auth_header_key#

The authorization header’s key name (typically ‘Authorization’) used in the HTTP headers. The header will be formatted as:

{'{auth_header_key}': '{auth_scheme} {auth_token}'}

If the authorization header key takes a single value, auth_scheme should be set to None and ‘auth_token’ should be configured to use the appropriate value.

(JUPYTER_GATEWAY_AUTH_HEADER_KEY env var)

auth_header_key_default_value = 'Authorization'#

auth_header_key_env = 'JUPYTER_GATEWAY_AUTH_HEADER_KEY'#

auth_scheme#: The auth scheme, added as a prefix to the authorization token used in the HTTP headers. (JUPYTER_GATEWAY_AUTH_SCHEME env var)

auth_scheme_default_value = 'token'#

auth_scheme_env = 'JUPYTER_GATEWAY_AUTH_SCHEME'#

auth_token#

The authorization token used in the HTTP headers. The header will be formatted as:

{'{auth_header_key}': '{auth_scheme} {auth_token}'}

(JUPYTER_GATEWAY_AUTH_TOKEN env var)

auth_token_default_value = ''#

auth_token_env = 'JUPYTER_GATEWAY_AUTH_TOKEN'#

ca_certs#: The filename of CA certificates or None to use defaults. (JUPYTER_GATEWAY_CA_CERTS env var)

ca_certs_env = 'JUPYTER_GATEWAY_CA_CERTS'#

client_cert#: The filename for client SSL certificate, if any. (JUPYTER_GATEWAY_CLIENT_CERT env var)

client_cert_env = 'JUPYTER_GATEWAY_CLIENT_CERT'#

client_key#: The filename for client SSL key, if any. (JUPYTER_GATEWAY_CLIENT_KEY env var)

client_key_env = 'JUPYTER_GATEWAY_CLIENT_KEY'#

connect_timeout#: The time allowed for HTTP connection establishment with the Gateway server. (JUPYTER_GATEWAY_CONNECT_TIMEOUT env var)

connect_timeout_default_value = 40.0#

connect_timeout_env = 'JUPYTER_GATEWAY_CONNECT_TIMEOUT'#

emit(data)#: Emit event using the core event schema from Jupyter Server’s Gateway Client.

env_whitelist#: Deprecated, use GatewayClient.allowed_envs

event_logger#

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

Subclasses can declare default classes by overriding the klass attribute

event_schema_id = 'https://events.jupyter.org/jupyter_server/gateway_client/v1'#

property gateway_enabled#

gateway_retry_interval#: The time allowed for HTTP reconnection with the Gateway server for the first time. Next will be JUPYTER_GATEWAY_RETRY_INTERVAL multiplied by two in factor of numbers of retries but less than JUPYTER_GATEWAY_RETRY_INTERVAL_MAX. (JUPYTER_GATEWAY_RETRY_INTERVAL env var)

gateway_retry_interval_default_value = 1.0#

gateway_retry_interval_env = 'JUPYTER_GATEWAY_RETRY_INTERVAL'#

gateway_retry_interval_max#: The maximum time allowed for HTTP reconnection retry with the Gateway server. (JUPYTER_GATEWAY_RETRY_INTERVAL_MAX env var)

gateway_retry_interval_max_default_value = 30.0#

gateway_retry_interval_max_env = 'JUPYTER_GATEWAY_RETRY_INTERVAL_MAX'#

gateway_retry_max#: The maximum retries allowed for HTTP reconnection with the Gateway server. (JUPYTER_GATEWAY_RETRY_MAX env var)

gateway_retry_max_default_value = 5#

gateway_retry_max_env = 'JUPYTER_GATEWAY_RETRY_MAX'#

gateway_token_renewer: GatewayTokenRenewerBase#

gateway_token_renewer_class#: The class to use for Gateway token renewal. (JUPYTER_GATEWAY_TOKEN_RENEWER_CLASS env var)

gateway_token_renewer_class_default_value = 'jupyter_server.gateway.gateway_client.NoOpTokenRenewer'#

gateway_token_renewer_class_env = 'JUPYTER_GATEWAY_TOKEN_RENEWER_CLASS'#

headers#: Additional HTTP headers to pass on the request. This value will be converted to a dict. (JUPYTER_GATEWAY_HEADERS env var)

headers_default_value = '{}'#

headers_env = 'JUPYTER_GATEWAY_HEADERS'#

http_pwd#: The password for HTTP authentication. (JUPYTER_GATEWAY_HTTP_PWD env var)

http_pwd_env = 'JUPYTER_GATEWAY_HTTP_PWD'#

http_user#: The username for HTTP authentication. (JUPYTER_GATEWAY_HTTP_USER env var)

http_user_env = 'JUPYTER_GATEWAY_HTTP_USER'#

init_connection_args()#: Initialize arguments used on every request. Since these are primarily static values, we’ll perform this operation once.

kernels_endpoint#: The gateway API endpoint for accessing kernel resources (JUPYTER_GATEWAY_KERNELS_ENDPOINT env var)

kernels_endpoint_default_value = '/api/kernels'#

kernels_endpoint_env = 'JUPYTER_GATEWAY_KERNELS_ENDPOINT'#

kernelspecs_endpoint#: The gateway API endpoint for accessing kernelspecs (JUPYTER_GATEWAY_KERNELSPECS_ENDPOINT env var)

kernelspecs_endpoint_default_value = '/api/kernelspecs'#

kernelspecs_endpoint_env = 'JUPYTER_GATEWAY_KERNELSPECS_ENDPOINT'#

kernelspecs_resource_endpoint#: The gateway endpoint for accessing kernelspecs resources (JUPYTER_GATEWAY_KERNELSPECS_RESOURCE_ENDPOINT env var)

kernelspecs_resource_endpoint_default_value = '/kernelspecs'#

kernelspecs_resource_endpoint_env = 'JUPYTER_GATEWAY_KERNELSPECS_RESOURCE_ENDPOINT'#

launch_timeout_pad#: Timeout pad to be ensured between KERNEL_LAUNCH_TIMEOUT and request_timeout such that request_timeout >= KERNEL_LAUNCH_TIMEOUT + launch_timeout_pad. (JUPYTER_GATEWAY_LAUNCH_TIMEOUT_PAD env var)

launch_timeout_pad_default_value = 2.0#

launch_timeout_pad_env = 'JUPYTER_GATEWAY_LAUNCH_TIMEOUT_PAD'#

load_connection_args(**kwargs)#: Merges the static args relative to the connection, with the given keyword arguments. If static args have yet to be initialized, we’ll do that here.

request_timeout#: The time allowed for HTTP request completion. (JUPYTER_GATEWAY_REQUEST_TIMEOUT env var)

request_timeout_default_value = 42.0#

request_timeout_env = 'JUPYTER_GATEWAY_REQUEST_TIMEOUT'#

update_cookies(cookie)#

Update cookies from existing requests for load balancers

Return type:: None

url#: The url of the Kernel or Enterprise Gateway server where kernel specifications are defined and kernel management takes place. If defined, this Notebook server acts as a proxy for all kernel management and kernel specification retrieval. (JUPYTER_GATEWAY_URL env var)

url_env = 'JUPYTER_GATEWAY_URL'#

validate_cert#: For HTTPS requests, determines if server’s certificate should be validated or not. (JUPYTER_GATEWAY_VALIDATE_CERT env var)

validate_cert_default_value = True#

validate_cert_env = 'JUPYTER_GATEWAY_VALIDATE_CERT'#

ws_url#: The websocket url of the Kernel or Enterprise Gateway server. If not provided, this value will correspond to the value of the Gateway url with ‘ws’ in place of ‘http’. (JUPYTER_GATEWAY_WS_URL env var)

ws_url_env = 'JUPYTER_GATEWAY_WS_URL'#

class jupyter_server.gateway.gateway_client.GatewayTokenRenewerBase(**kwargs)#

Bases: ABC, LoggingConfigurable

Abstract base class for refreshing tokens used between this server and a Gateway server. Implementations requiring additional configuration can extend their class with appropriate configuration values or convey those values via appropriate environment variables relative to the implementation.

abstract get_token(auth_header_key, auth_scheme, auth_token, **kwargs)#

Given the current authorization header key, scheme, and token, this method returns a (potentially renewed) token for use against the Gateway server.

Return type:: str

class jupyter_server.gateway.gateway_client.GatewayTokenRenewerMeta(name, bases, classdict, **kwds)#

Bases: ABCMeta, MetaHasTraits

The metaclass necessary for proper ABC behavior in a Configurable.

class jupyter_server.gateway.gateway_client.NoOpTokenRenewer(**kwargs)#

Bases: GatewayTokenRenewerBase

NoOpTokenRenewer is the default value to the GatewayClient trait gateway_token_renewer and merely returns the provided token.

get_token(auth_header_key, auth_scheme, auth_token, **kwargs)#

This implementation simply returns the current authorization token.

Return type:: str

class jupyter_server.gateway.gateway_client.RetryableHTTPClient#

Bases: object

Inspired by urllib.util.Retry (https://urllib3.readthedocs.io/en/stable/reference/urllib3.util.html), this class is initialized with desired retry characteristics, uses a recursive method fetch() against an instance of AsyncHTTPClient which tracks the current retry count across applicable request retries.

MAX_RETRIES_CAP = 10#

MAX_RETRIES_DEFAULT = 2#

backoff_factor: float = 0.1#

async fetch(endpoint, **kwargs)#

Retryable AsyncHTTPClient.fetch() method. When the request fails, this method will recurse up to max_retries times if the condition deserves a retry.

Return type:: HTTPResponse

max_retries: int = 2#

retried_errors: set[int] = {502, 503, 504, 599}#

retried_exceptions: set[type] = {<class 'ConnectionError'>}#

retried_methods: set[str] = {'DELETE', 'GET'}#

async jupyter_server.gateway.gateway_client.gateway_request(endpoint, **kwargs)#

Make an async request to kernel gateway endpoint, returns a response

Return type:: HTTPResponse

Gateway API handlers.

class jupyter_server.gateway.handlers.GatewayResourceHandler(application, request, **kwargs)#

Bases: APIHandler

Retrieves resources for specific kernelspec definitions from kernel/enterprise gateway.

get(kernel_name, path, include_body=True)#: Get a gateway resource by name and path.

class jupyter_server.gateway.handlers.GatewayWebSocketClient(**kwargs: Any)#

Bases: LoggingConfigurable

Proxy web socket connection to a kernel/enterprise gateway.

on_close()#: Web socket closed event.

on_message(message)#: Send message to gateway server.

on_open(kernel_id, message_callback, **kwargs)#: Web socket connection open against gateway server.

class jupyter_server.gateway.handlers.WebSocketChannelsHandler(application, request, **kwargs)#

Bases: WebSocketHandler, JupyterHandler

Gateway web socket channels handler.

authenticate()#

Run before finishing the GET request

Extend this method to add logic that should fire before the websocket finishes completing.

check_origin(origin=None)#: Check origin for the socket.

gateway = None#

async get(kernel_id, *args, **kwargs)#: Get the socket.

get_compression_options()#: Get the compression options for the socket.

initialize()#: Initialize the socket.

kernel_id = None#

on_close()#: Handle a closing socket.

on_message(message)#: Forward message to gateway web socket handler.

open(kernel_id, *args, **kwargs)#: Handle web socket connection open to notebook server and delegate to gateway web socket handler

ping_callback = None#

send_ping()#: Send a ping to the socket.

session = None#

set_default_headers()#: Undo the set_default_headers in JupyterHandler which doesn’t make sense for websockets

write_message(message, binary=False)#: Send message back to notebook client. This is called via callback from self.gateway._read_messages.

Kernel gateway managers.

class jupyter_server.gateway.managers.ChannelQueue(channel_name, channel_socket, log)#

Bases: Queue

A queue for a named channel.

channel_name: Optional[str] = None#

async get_msg(*args, **kwargs)#

Get a message from the queue.

Return type:: dict[str, Any]

is_alive()#

Whether the queue is alive.

Return type:: bool

response_router_finished: bool#

send(msg)#

Send a message to the queue.

Return type:: None

static serialize_datetime(dt)#: Serialize a datetime object.

start()#

Start the queue.

Return type:: None

stop()#

Stop the queue.

Return type:: None

class jupyter_server.gateway.managers.GatewayKernelClient(**kwargs: Any)#

Bases: AsyncKernelClient

Communicates with a single kernel indirectly via a websocket to a gateway server.

There are five channels associated with each kernel:

shell: for request/reply calls to the kernel.
iopub: for the kernel to publish results to frontends.
hb: for monitoring the kernel’s heartbeat.
stdin: for frontends to reply to raw_input calls in the kernel.
control: for kernel management calls to the kernel.

The messages that can be sent on these channels are exposed as methods of the client (KernelClient.execute, complete, history, etc.). These methods only send the message, they don’t wait for a reply. To get results, use e.g. get_shell_msg() to fetch messages from the shell channel.

allow_stdin: bool = False#

property control_channel#: Get the control channel object for this kernel.

property hb_channel#: Get the hb channel object for this kernel.

property iopub_channel#: Get the iopub channel object for this kernel.

property shell_channel#: Get the shell channel object for this kernel.

async start_channels(shell=True, iopub=True, stdin=True, hb=True, control=True)#

Starts the channels for this kernel.

For this class, we establish a websocket connection to the destination and set up the channel-based queues on which applicable messages will be posted.

property stdin_channel#: Get the stdin channel object for this kernel.

stop_channels()#

Stops all the running channels for this kernel.

For this class, we close the websocket connection and destroy the channel-based queues.

class jupyter_server.gateway.managers.GatewayKernelManager(**kwargs: Any)#

Bases: ServerKernelManager

Manages a single kernel remotely via a Gateway Server.

cleanup_resources(restart=False)#: Clean up resources when the kernel is shut down

client(**kwargs)#: Create a client configured to connect to our kernel

client_class: DottedObjectName#: A string holding a valid dotted object name in Python, such as A.b3._c

client_factory: Type#: A trait whose value must be a subclass of a specified class.

property has_kernel#: Has a kernel been started that we are managing.

async interrupt_kernel()#: Interrupts the kernel via an HTTP request.

async is_alive()#: Is the kernel process still running?

kernel = None#

kernel_id: Optional[str] = None#

async refresh_model(model=None)#

Refresh the kernel model.

Parameters:: model (dict) – The model from which to refresh the kernel. If None, the kernel model is fetched from the Gateway server.

async restart_kernel(**kw)#: Restarts a kernel via HTTP.

async shutdown_kernel(now=False, restart=False)#: Attempts to stop the kernel process cleanly via HTTP.

async start_kernel(**kwargs)#

Starts a kernel via HTTP in an asynchronous manner.

Parameters:: **kwargs (optional) – keyword arguments that are passed down to build the kernel_cmd and launching the kernel (e.g. Popen kwargs).

class jupyter_server.gateway.managers.GatewayKernelSpecManager(**kwargs: Any)#

Bases: KernelSpecManager

A gateway kernel spec manager.

async get_all_specs()#: Get all of the kernel specs for the gateway.

async get_kernel_spec(kernel_name, **kwargs)#

Get kernel spec for kernel_name.

Parameters:: kernel_name (str) – The name of the kernel.

async get_kernel_spec_resource(kernel_name, path)#

Get kernel spec for kernel_name.

Parameters:

kernel_name (str) – The name of the kernel.
path (str) – The name of the desired resource

async list_kernel_specs()#: Get a list of kernel specs.

class jupyter_server.gateway.managers.GatewayMappingKernelManager(**kwargs: Any)#

Bases: AsyncMappingKernelManager

Kernel manager that supports remote kernels hosted by Jupyter Kernel or Enterprise Gateway.

async cull_kernels()#: Override cull_kernels, so we can be sure their state is current.

async interrupt_kernel(kernel_id, **kwargs)#

Interrupt a kernel by its kernel uuid.

Parameters:: kernel_id (uuid) – The id of the kernel to interrupt.

async kernel_model(kernel_id)#

Return a dictionary of kernel information described in the JSON standard model.

Parameters:: kernel_id (uuid) – The uuid of the kernel.

async list_kernels(**kwargs)#

Get a list of running kernels from the Gateway server.

We’ll use this opportunity to refresh the models in each of the kernels we’re managing.

remove_kernel(kernel_id)#: Complete override since we want to be more tolerant of missing keys

async restart_kernel(kernel_id, now=False, **kwargs)#

Restart a kernel by its kernel uuid.

Parameters:: kernel_id (uuid) – The id of the kernel to restart.

async shutdown_all(now=False)#: Shutdown all kernels.

async shutdown_kernel(kernel_id, now=False, restart=False)#

Shutdown a kernel by its kernel uuid.

Parameters:

kernel_id (uuid) – The id of the kernel to shutdown.
now (bool) – Shutdown the kernel immediately (True) or gracefully (False)
restart (bool) – The purpose of this shutdown is to restart the kernel (True)

async start_kernel(*, kernel_id=None, path=None, **kwargs)#

Start a kernel for a session and return its kernel_id.

Parameters:

kernel_id (uuid) – The uuid to associate the new kernel with. If this is not None, this kernel will be persistent whenever it is requested.
path (API path) – The API path (unicode, ‘/’ delimited) for the cwd. Will be transformed to an OS path relative to root_dir.

class jupyter_server.gateway.managers.GatewaySessionManager(**kwargs: Any)#

Bases: SessionManager

A gateway session manager.

async kernel_culled(kernel_id)#

Checks if the kernel is still considered alive and returns true if it’s not found.

Return type:: bool

kernel_manager#

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

Subclasses can declare default classes by overriding the klass attribute

class jupyter_server.gateway.managers.HBChannelQueue(channel_name, channel_socket, log)#

Bases: ChannelQueue

A queue for the heartbeat channel.

is_beating()#

Whether the channel is beating.

Return type:: bool

jupyter_server.gateway package#

Submodules#

Module contents#