Skip to main content
`Ctrl`+`K`

# 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.

  abstractmethod 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`

## Module contents