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.

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.

lab_session([notebook_name, kernel_name, ...])

Create a lab session manager.

run_notebook(content, *[, kernel_name, ...])

Run a notebook via the Nublado notebook execution extension.

spawn_lab(config)

Spawn a Jupyter lab pod.

stop_lab()

Stop the user's Jupyter lab.

wait_for_spawn()

Wait for lab spawn to complete without monitoring it.

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

Raises:
Return type:

bool

lab_session(notebook_name=None, *, kernel_name='lsst', max_websocket_size=None, websocket_open_timeout=datetime.timedelta(seconds=60))#

Create a lab session manager.

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.

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

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

  • websocket_open_timeout (timedelta, default: datetime.timedelta(seconds=60)) – Timeout for opening a WebSocket.

Returns:

Context manager to open the WebSocket session.

Return type:

JupyterLabSessionManager

async run_notebook(content, *, kernel_name=None, read_timeout=None)#

Run a notebook via the Nublado notebook execution extension.

This runs the notebook using nbconvert via a Nublado JupyterLab extension, rather than executing it cell-by-cell within a session and kernel.

Parameters:

  • content (str) – Content of the notebook to execute.

  • kernel_name (str | None, default: None) – If provided, override the default kernel name.

  • read_timeout (timedelta | None, default: None) – If provided, overrides the default read timeout for Nublado API calls. The default timeout is 30 seconds and the notebook execution is synchronous, so providing a longer timeout is recommended unless the notebook is quick to execute. This will only change the read timeout, used when waiting for results, not the timeouts on connecting and sending the request.

Returns:

Execution results from the notebook. If the notebook execution failed due to an issue with a cell, rather than a lower-level issue with notebook execution, the error attribute of this result will be filled in.

Return type:

NotebookExecutionResult

Raises:
async spawn_lab(config)#

Spawn a Jupyter lab pod.

Parameters:

config (NubladoImage) – Image configuration.

Raises:
Return type:

None

async stop_lab()#

Stop the user’s Jupyter lab.

Raises:
Return type:

None

async wait_for_spawn()#

Wait for lab spawn to complete without monitoring it.

This method can be used instead of watch_spawn_progress if the caller is not interested in the spawn progress messages. It will return when the spawn is complete.

Raises:
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. The caller can distinguish between the two by checking if the ready field of the last yielded message is True, indicating the spawn succeeded.

Yields:

SpawnProgressMessage – Next progress message from JupyterHub.

Raises:
Return type:

AsyncGenerator[SpawnProgressMessage]