JupyterAsyncClient#

class rubin.nublado.client.JupyterAsyncClient(*, discovery_client, logger, timeout, token, username)#

Bases: object

Wrapper around an HTTP client with JupyterHub and JupyterLab support.

The Nublado client, rather than using Jupyter access tokens, simulates a web browser when interacting with JupyterHub and JupyterLab. This requires some special handling:

  • An Authorization header must be set on every request to get past Gafaelfawr authentication.

  • The client needs a persistent cookie jar to handle XSRF cookies.

  • An additional X-XSRFToken header must be added to requests containing the XSRF token. (This is easier than trying to inject it into the query string or POST body.)

  • The XSRF token for the X-XSRFToken header must be extracted from the cookie jar, but it may only be present in some intermediate responses in redirect chains.

  • Sec-Fetch-Mode must be set to appropriate values on different requests to avoid annoying logs messages or XSRF validation failures.

This wrapper around an HTTPX AsyncClient handles that complexity and exposes a simple API to the rest of the Nublado client.

Parameters:

  • discovery_client (DiscoveryClient) – Repertoire discovery client, used to find the base URL of JupyterHub.

  • logger (BoundLogger) – Logger to use.

  • timeout (timedelta) – Timeout to use when talking to JupyterHub and JupyterLab. This is used as a connection, read, and write timeout for all regular HTTP calls.

  • token (str) – Gafaelfawr token to use for authentication.

  • username (str) – Username on whose behalf the client will be acting.

Methods Summary

aclose()

Close the underlying HTTP connection pool.

delete(route, *[, add_referer])

Perform a DELETE request to JupyterHub or JupyterLab.

get(route, *[, add_referer, fetch_mode])

Perform a GET request to JupyterHub or JupyterLab.

open_sse_stream(route)

Open a server-sent events stream.

open_websocket(route, *, open_timeout, max_size)

Open a WebSocket connection.

post(route, *[, content, data, json, ...])

Perform a POST request to JupyterHub or JupyterLab.

Methods Documentation

async aclose()#

Close the underlying HTTP connection pool.

This invalidates the client object. It can no longer be used after this method is called.

Return type:

None

async delete(route, *, add_referer=False)#

Perform a DELETE request to JupyterHub or JupyterLab.

Parameters:

  • route (str) – Route relative to the base URL of Nublado. Routes starting with user are considered JupyterLab routes.

  • add_referer (bool, default: False) – Whether to add a Referer header pointing to the JupyterHub home page. This is required by JupyterHub in some cases.

Returns:

HTTP response at the end of any redirect chain.

Return type:

httpx.Response

Raises:
async get(route, *, add_referer=False, fetch_mode='same-origin')#

Perform a GET request to JupyterHub or JupyterLab.

Handles authentication and redirect following, ensuring that the redirects are relative to either the JupyterHub or JupyterLab base URLs.

Parameters:

  • route (str) – Route relative to the base URL of Nublado. Routes starting with user are considered JupyterLab routes.

  • add_referer (bool, default: False) – Whether to add a Referer header pointing to the JupyterHub home page. This is required by JupyterHub in some cases.

  • fetch_mode (TypeAliasType, default: 'same-origin') – Value of Sec-Fetch-Mode header to send. This suppresses some log noise and improves XSRF handling in JupyterHub and JupyterLab.

Returns:

HTTP response at the end of any redirect chain.

Return type:

httpx.Response

Raises:
async open_sse_stream(route)#

Open a server-sent events stream.

Parameters:

route (str) – Route relative to the base URL of Nublado. Routes starting with user are considered JupyterLab routes.

Returns:

Context manager that provides an httpx_sse.EventSource.

Return type:

contextlib.AbstractAsyncContextManager

Raises:
async open_websocket(route, *, open_timeout, max_size)#

Open a WebSocket connection.

Parameters:

  • route (str) – Route relative to the base URL of Nublado. Routes starting with user are considered JupyterLab routes.

  • max_size (int | None) – Maximum size of a WebSocket message, or None for no limit.

  • open_timeout (timedelta)

Returns:

Context manager that provides a ClientConnection.

Return type:

contextlib.AbstractAsyncContextManager

Raises:
async post(route, *, content=None, data=None, json=None, timeout=None, add_referer=False, extra_headers=None)#

Perform a POST request to JupyterHub or JupyterLab.

Follows redirects in the response using GET requests.

Parameters:

  • route (str) – Route relative to the base URL of Nublado. Routes starting with user are considered JupyterLab routes.

  • contents – Raw contents for the POST body. Only one of contents, data, or json may be specified.

  • data (dict[str, Any] | None, default: None) – Data for the POST body. Only one of contents, data, or json may be specified.

  • json (dict[str, Any] | None, default: None) – Data for a POST body formatted as JSON. Only one of contents, data, or json may be specified.

  • timeout (Timeout | None, default: None) – HTTPX timeout settings, overriding the defaults.

  • add_referer (bool, default: False) – Whether to add a Referer header pointing to the JupyterHub home page. This is required by JupyterHub in some cases.

  • extra_headers (dict[str, str] | None, default: None) – Additional headers to add to the request. These headers should not conflict with the standard headers; if they do, the values in extra_headers will override the standard headers, which will probably break.

  • content (str | None, default: None)

Returns:

HTTP response at the end of any redirect chain.

Return type:

httpx.Response

Raises: