Spawners

Module: jupyterhub.spawner

Contains base Spawner class & default implementation

Spawner

class jupyterhub.spawner.Spawner(**kwargs)

Base class for spawning single-user notebook servers.

Subclass this, and override the following methods:

  • load_state
  • get_state
  • start
  • stop
  • poll

As JupyterHub supports multiple users, an instance of the Spawner subclass is created for each user. If there are 20 JupyterHub users, there will be 20 instances of the subclass.

format_string(s)

Render a Python format string

Uses Spawner.template_namespace() to populate format namespace.

Parameters:s (str) – Python format-string to be formatted.
Returns:Formatted string, rendered
Return type:str
get_args()

Return the arguments to be passed after self.cmd

Doesn’t expect shell expansion to happen.

get_env()

Return the environment dict to use for the Spawner.

This applies things like env_keep, anything defined in Spawner.environment, and adds the API token to the env.

When overriding in subclasses, subclasses must call super().get_env(), extend the returned dict and return it.

Use this to access the env in Spawner.start to allow extension in subclasses.

get_state()

Save state of spawner into database.

A black box of extra state for custom spawners. The returned value of this is passed to load_state.

Subclasses should call super().get_state(), augment the state returned from there, and return that state.

Returns:state – a JSONable dict of state
Return type:dict
options_from_form(form_data)

Interpret HTTP form data

Form data will always arrive as a dict of lists of strings. Override this function to understand single-values, numbers, etc.

This should coerce form data into the structure expected by self.user_options, which must be a dict.

Instances will receive this data on self.user_options, after passing through this function, prior to Spawner.start.

poll()

Check if the single-user process is running

Returns:None if single-user process is running. Integer exit status (0 if unknown), if it is not running.

State transitions, behavior, and return response:

  • If the Spawner has not been initialized (neither loaded state, nor called start), it should behave as if it is not running (status=0).
  • If the Spawner has not finished starting, it should behave as if it is running (status=None).

Design assumptions about when poll may be called:

  • On Hub launch: poll may be called before start when state is loaded on Hub launch. poll should return exit status 0 (unknown) if the Spawner has not been initialized via load_state or start.
  • If .start() is async: poll may be called during any yielded portions of the start process. poll should return None when start is yielded, indicating that the start process has not yet completed.
start()

Start the single-user server

Returns:the (ip, port) where the Hub can connect to the server.
Return type:(str, int)

Changed in version 0.7: Return ip, port instead of setting on self.user.server directly.

stop(now=False)

Stop the single-user server

If now is set to False, do not wait for the server to stop. Otherwise, wait for the server to stop before returning.

Must be a Tornado coroutine.

template_namespace()

Return the template namespace for format-string formatting.

Currently used on default_url and notebook_dir.

Subclasses may add items to the available namespace.

The default implementation includes:

{
  'username': user.name,
  'base_url': users_base_url,
}
Returns:namespace for string formatting.
Return type:ns (dict)
class jupyterhub.spawner.LocalProcessSpawner(**kwargs)

A Spawner that uses subprocess.Popen to start single-user servers as local processes.

Requires local UNIX users matching the authenticated users to exist. Does not work on Windows.

This is the default spawner for JupyterHub.