Awesome
wrapspawner for Jupyterhub
This package includes WrapSpawner and ProfilesSpawner, which provide mechanisms for runtime configuration of spawners. The inspiration for their development was to allow users to select from a range of pre-defined batch job profiles, but their operation is completely generic.
Installation
-
Most users can install via pip:
pip install wrapspawner
To install an editable copy for development, from root directory of this repo (where setup.py is), run
pip install -e .
See also pip VCS support if you need a specific revision. -
Add lines in
jupyterhub_config.py
for the spawner you intend to use, e.g.c.JupyterHub.spawner_class = 'wrapspawner.ProfilesSpawner'
-
Depending on the spawner, additional configuration will likely be needed.
Wrapper and Profile Spawners
Overview
WrapSpawner
provides a mechanism to wrap the interface of a JupyterHub Spawner such that
the Spawner class to use for single-user servers can be chosen dynamically.
Subclasses may modify the class or properties of the child Spawner at any point
before start()
is called (e.g. from Authenticator pre_spawn
hooks or options form
processing) and that state will be preserved on restart. The start/stop/poll
methods are not real coroutines, but simply pass through the Futures returned
by the wrapped Spawner class.
ProfilesSpawner
leverages JupyterHub's Spawner
"options form" feature to allow user-driven
configuration of Spawner classes while permitting:
- configuration of Spawner classes that don't natively implement
options_form
- administrator control of allowed configuration changes
- runtime choice of which Spawner backend to launch
Example
Here is a screenshot of a typical dropdown menu letting the user choose between several SLURM instances:
The following configuration snippet lets the user choose between a Jupyter server
running as a local process or one of two different Docker Images to run within DockerSpawner
.
c.JupyterHub.spawner_class = 'wrapspawner.ProfilesSpawner'
c.Spawner.http_timeout = 120
#------------------------------------------------------------------------------
# ProfilesSpawner configuration
#------------------------------------------------------------------------------
# List of profiles to offer for selection. Signature is:
# List(Tuple( Unicode, Unicode, Type(Spawner), Dict ))
# corresponding to profile display name, unique key, Spawner class,
# dictionary of spawner config options.
#
# The first three values will be exposed in the input_template as {display},
# {key}, and {type}
#
c.ProfilesSpawner.profiles = [
( "Host process", 'local', 'jupyterhub.spawner.LocalProcessSpawner', {'ip':'0.0.0.0'} ),
('Docker Python 3', 'singleuser', 'dockerspawner.SystemUserSpawner', dict(image="jupyterhub/singleuser")),
('Docker Python 3 Scipy', 'scipy-notebook', 'dockerspawner.SystemUserSpawner', dict(image="jupyter/scipy-notebook")),
]
History
These mechanisms originated as part of the batchspawner
package.
The batchspawner
README contains additional examples on the use of ProfilesSpawner.