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.

Attributes Summary

`http`
`hub_xsrf`
`lab_xsrf`

Methods Summary

`auth_to_hub`()	Retrieve the JupyterHub home page.
`auth_to_lab`()	Authenticate to the user's JupyterLab.
`close`()	Close the underlying HTTP connection pool.
`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.

Attributes Documentation

http#

hub_xsrf#

lab_xsrf#

Methods Documentation

async auth_to_hub()#

Retrieve the JupyterHub home page.

This forces a refresh of the authentication cookies set in the client session, which may be required to use API calls that return 401 errors instead of redirecting the user to log in. It also detects the initial redirect if JupyterHub is running in a different domain and updates the JupyterHub base URL accordingly.

The reply will set an _xsrf cookie that must be lifted into the headers for subsequent requests.

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 is required before making API calls to the lab, such as running code. Also inspect the redirect chain to see if per-user subdomains are in use and, if so, update our understanding of the base URL for JupyterLab so that subsequent non-GET calls will work correctly.

The reply will set an _xsrf cookie that must be lifted into the headers for subsequent requests.

Raises:: JupyterProtocolError – Raised if no _xsrf cookie was set in the reply from the lab.
Return type:: None

async close()#

Close the underlying HTTP connection pool.

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]