NubladoClient

class rubin.nublado.client.NubladoClient(*, username, token, discovery_client=None, logger=None, timeout=datetime.timedelta(seconds=30))

Bases: object

Client for talking to JupyterHub and Jupyter labs that use Nublado.

Parameters:

• username (str) – User whose lab should be managed.

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

• discovery_client (DiscoveryClient | None, default: None) – If given, Repertoire discovery client to use. Otherwise, a new client will be created.

• logger (BoundLogger | None, default: None) – Logger to use. If not given, the default structlog logger will be used.

• timeout (timedelta, default: datetime.timedelta(seconds=30)) – Timeout to use when talking to JupyterHub and Jupyter lab. This is used as a connection, read, and write timeout for all regular HTTP calls.

username

User whose lab is managed by this object.

Notes

This class creates its own httpx.AsyncClient for each instance, separate from the one used by the rest of the application, since it needs to isolate the cookies set by JupyterHub and the lab from those for any other user.

Although principally intended as a Lab/Hub client, the underlying httpx.AsyncClient is exposed via the http property.

Methods Summary

aclose()	Close the underlying HTTP connection pool.
auth_to_hub()	Retrieve the JupyterHub home page.
auth_to_lab()	Authenticate to the user's JupyterLab.
is_lab_stopped(*[, log_running])	Determine if the lab is fully stopped.
open_lab_session([notebook_name, ...])	Open a Jupyter lab session.
spawn_lab(config)	Spawn a Jupyter lab pod.
stop_lab()	Stop the user's Jupyter lab.
watch_spawn_progress()	Monitor lab spawn progress.

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 auth_to_hub()

Retrieve the JupyterHub home page.

This resets the underlying HTTP client to clear cookies and force a complete refresh of stored state, including XSRF tokens. Less aggressive reset mechanisms resulted in periodic errors about stale XSRF cookies.

Raises:

JupyterProtocolError – Raised if no _xsrf cookie was set in the reply from the lab.

Return type:

None

async auth_to_lab()

Authenticate to the user’s JupyterLab.

Request the top-level lab page, which will force the OpenID Connect authentication with JupyterHub and set authentication cookies. This will be done implicitly the first time, but for long-running clients, you may need to do this periodically to refresh credentials.

Raises:

JupyterProtocolError – Raised if no _xsrf cookie was set in the reply from the lab.

Return type:

None

async is_lab_stopped(*, log_running=False)

Determine if the lab is fully stopped.

Parameters:

log_running (bool, default: False) – Log a warning with additional information if the lab still exists.

Return type:

bool

open_lab_session(notebook_name=None, *, max_websocket_size=None, kernel_name='LSST')

Open a Jupyter lab session.

Returns a context manager object so must be called via async with or the equivalent. The lab session will automatically be deleted when the context manager exits.

Parameters:

• notebook_name (str | None, default: None) – Name of the notebook we will be running, which is passed to the session and might influence logging on the lab side. If set, the session type will be set to notebook. If not set, the session type will be set to console.

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

• kernel_name (str, default: 'LSST') – Name of the kernel to use for the session.

Returns:

Context manager to open the WebSocket session.

Return type:

JupyterLabSession

async spawn_lab(config)

Spawn a Jupyter lab pod.

Parameters:

config (NubladoImage) – Image configuration.

Raises:

JupyterWebError – Raised if an error occurred talking to JupyterHub.

Return type:

None

async stop_lab()

Stop the user’s Jupyter lab.

Return type:

None

async watch_spawn_progress()

Monitor lab spawn progress.

This is an EventStream API, which provides a stream of events until the lab is spawned or the spawn fails.

Yields:

SpawnProgressMessage – Next progress message from JupyterHub.

Return type:

AsyncGenerator[SpawnProgressMessage]