Spawners

The FirecRESTSpawnerBase class

class firecrestspawner.spawner.FirecRESTSpawnerBase(*args: t.Any, **kwargs: t.Any)

Bases: Spawner

Base class for spawners using PyFirecrest to submit jobs

This class defines the spawner’s main functions: start(), poll() and stop() as well as traits that can be set in the JupyterHub configuration via c.Spawner.

All req_xyz traits will be available as substvars for templated strings in the batch script.

access_token_is_valid

Indicates whether the current access token is valid. This is used in the home.html template to manage the stopbutton availability

batch_script

Template for job submission script. Traits on this class named like req_xyz will be substituted in the template for {xyz} using string.Formatter. Must include {cmd} which will be replaced with the jupyterhub-singleuser command line.

batchspawner_singleuser_cmd

A wrapper which is capable of special batchspawner setup: currently sets the port on the remote host. Not needed to be set under normal circumstances, unless path needs specification.

async cancel_batch_job() → None

Cancel the job running the notebooks sever

clear_state() → None

Clear job_id state

cmd_formatted_for_batch()

The command which is substituted inside of the batch script.

async firecrest_poll()

Helper function to poll jobs.

async get_firecrest_client()

Returns a firecrest client that uses Keycloak’s Authorization Code Flow method

async get_firecrest_client_service_account()

Returns a firecrest client that uses the Client Credentials Authorization method

get_req_subvars()

Prepare substitution variables for templates using req_xyz traits.

get_state() → None

Add job_id to state

ip

Address for singleuser server to listen at

job_id

A trait for unicode strings.

job_status

A trait for unicode strings.

load_state(state) → None

Load job_id from state

async poll() → int | None

Poll the process

polling_with_service_account

If True, use a service account client for job polling.

progress() → AsyncGenerator[dict[str, str], None]

Async generator that yields status messages reflecting the progress of a job.

This generator continuously checks the job’s current state and yields an appropriate status message:

• If the job is pending, a message is shown in the hub indicating the job is waiting in the queue.

• If the job is running, a message is hown in the hub that the cluster job is running.

• For any other state, a message is shwon in the hub indicating it is awaiting a status update.

Yields:

dict: A dictionary containing a “message” key with a status message.

Note:

This generator pauses for one second between each status check to avoid excessive polling.

async query_job_status()

Check job status, return JobStatus object.

req_account

Account name string to pass to the resource manager

req_epilogue

Script to run after single user server ends.

req_homedir

A trait for unicode strings.

req_host

Host name of batch server to submit job to resource manager

req_memory

Memory to request from resource manager

req_ngpus

Number of GPUs to request from resource manager

req_nnodes

Number of nodes to request from resource manager

req_nprocs

Number of processors to request from resource manager

req_options

Other options to include into job submission script

req_partition

Partition name to submit job to resource manager

req_prologue

Script to run before single user server starts.

req_queue

Queue name to submit job to resource manager

req_reservation_custom

Custom reservation to pass in the form

req_runtime

Length of time for submitted job to run

req_uenv

Name of a uenv to mount

req_uenv_view

Name of a uenv view to activate

req_username

A trait for unicode strings.

async start() → tuple[str, int]

Start the process

start_timeout

Timeout before giving up on starting of single-user server

startup_poll_interval

Polling interval to check job state during startup

state_gethost() → str

Return string, hostname or addr of running job, likely by parsing self.job_status

state_ispending() → bool

Return boolean indicating if job is still waiting to run, likely by parsing self.job_status

state_isrunning() → bool

Return boolean indicating if job is running, likely by parsing self.job_status

state_isunknown() → bool | None

Return boolean indicating if job state retrieval failed because of the resource manager

async stop(now: str = False) → None

Stop the singleuser server job.

Returns immediately after sending job cancellation command if now=True, otherwise tries to confirm that job is no longer running.

async submit_batch_script()

Submits the batch script that starts the notebook server job

It’s called by spawner.start.

workdir

Directory where the job will be submitted from

The FirecRESTSpawnerRegexStates class

class firecrestspawner.spawner.FirecRESTSpawnerRegexStates(*args: t.Any, **kwargs: t.Any)

Bases: FirecRESTSpawnerBase

Uses config-supplied regular expressions to interact with the batch submission system state.

Provides implementations of the following methods:

• state_ispending

• state_isrunning

• state_gethost

In place of these methods, the user should supply the following configuration options:

• state_pending_re: A regular expression that matches job_status

  if the job is waiting to run.

• state_running_re: A regular expression that matches job_status if the job is running.

• state_exechost_re: A regular expression with at least one capture group that extracts the execution host from job_status.

• state_exechost_exp: If empty, the notebook IP will be set to the contents of the first capture group. If this variable is set, the match object will be expanded using this string to obtain the notebook IP. (See Python documentation for re.match.expand for more details.)

state_exechost_exp

If empty, notebook IP will be set to the contents of the first capture group.

If this variable is set, the match object will be expanded using this string to obtain the notebook IP. See Python docs: re.match.expand

state_exechost_re

Regex with at least one capture group that extracts the execution host from job_status output

async state_gethost() → str

Return string, hostname or addr of running job, likely by parsing self.job_status

state_ispending() → bool

Return boolean indicating if job is still waiting to run, likely by parsing self.job_status

state_isrunning() → bool

Return boolean indicating if job is running, likely by parsing self.job_status

state_isunknown() → bool | None

Return boolean indicating if job state retrieval failed because of the resource manager

state_pending_re

Regex that matches job_status if job is waiting to run

state_running_re

Regex that matches job_status if job is running

state_unknown_re

Regex that matches job_status if the resource manager is not answering. Blank indicates not used.

The SlurmSpawner class

class firecrestspawner.spawner.SlurmSpawner(*args: t.Any, **kwargs: t.Any)

Bases: FirecRESTSpawnerRegexStates

Implementation of the FirecRESTSpawner for Slurm

batch_script

A trait for unicode strings.

custom_state_gethost

A custom function to get the name or ip of the node where the single-user server is running

firecrest_url = 'dummy'

node_name_template

A template for the DNS name of the node

req_cluster

Cluster name to submit job to resource manager

req_constraint

Specify the constraint

req_gres

Additional resources (e.g. GPUs) requested

req_qos

QoS name to submit job to resource manager

req_reservation

Reservation name to submit to resource manager

req_srun

Set req_srun=’’ to disable running in job step, and note that this affects environment handling. This is effectively a prefix for the singleuser command.

req_submitenv

Submit environment

state_exechost_re

A trait for unicode strings.

state_pending_re

A trait for unicode strings.

state_running_re

A trait for unicode strings.

state_unknown_re

A trait for unicode strings.

The JobStatus class

class firecrestspawner.spawner.JobStatus(*values)

Enumeration representing the status of a job.

Attributes:

• NOTFOUND: indicates the job was not found (value = 0)

• RUNNING: indicates the job is currently running (value = 1)

• PENDING: indicates the job is waiting to be processed (value = 2)

• UNKNOWN: indicates the job status is unknown (value = 3)

Any other status is included in one of those listed above via regexes. For instance, Slurm’s CONFIGURING and COMPLETING are considered as PENDING and RUNNING respectively.

The AuthorizationCodeFlowAuth class

class firecrestspawner.spawner.AuthorizationCodeFlowAuth(client_id: str, client_secret: str, refresh_token: str, token_url: str)

Bases: object

Authorization Code Flow class

Parameters:

• client_id – name of the client registered in the authorization server

• client_secret – secret associated to the client

• refresh_token – refresh token for the SSO session

• token_url – URL of the token request in the authorization server

This is used with PyFirecREST clients based on Keycloak’s Authorization Code Flow method. It’s simlar PyFirecREST’s ClientCredentialsAuth class which is used with clients based on the Keycloak’s Client Credentials method.

get_access_token() → str | None

Returns an access token to be used for accessing resources.

Given a refresh token, this function does a request to Keycloak to refresh the access token. If the request is successful, the access token is returned, otherwise the function returns None.