For Starters¶

The basic idea of a starter is:

pick a destination in the JupyterLab File Browser

click a button in the JupyterLab Launcher

see useful files

A slightly more accurate version is:

configure via traitlets

advertise to JupyterLab via the REST API

display in the JupyterLab Launcher

click a button in the JupyterLab Launcher

or immediately start with a Starter Tree URL

zero or more (but usually one) times:

gather more information from the user via react-jsonschema-form

perform further processing

copy files via the Contents API

see useful files in the JupyterLab File Browser

run JupyterLab Commands to do other things to JupyterLab

Which of these steps a particular starter performs depends primarily on its type.

Types of Starters¶

Copy¶

"type": "copy"

"src": "<an absolute or relative path>"

The simplest starter, copy, just… copies. It can copy a single file, or a directory of files (and subdirectories). The src attribute tells the starter where to get the files.

[2]:

copy, like all the starters, makes use of the Contents API directly. Existing files will not be overwritten.

Python¶

"type": "python"

"callable": "<a dotted notation python function>"

A Python Starter is a function. This type has the fewest limitations, as it has full access to the StarterManager (and by extension, it’s parent, the NotebookApp). This powers both the Cookiecutter the Notebook starters, with the latter directly using the notebook server’s Kernel Manager to start short-lifespan kernels.

[3]:

Notebook¶

"type": "notebook"

A notebook can be a starter. Each starter run gets its own, private kernel which can persist between interactions with the user. Communication with the server manager is handled through manipulating a copy of the notebook, specfically the notebook metadata. The advantages of this approach over the Python starter is:

works with any installed kernel
state is maintained between successive re-executions
jupyterlab-starters provides authoring support for editing and validating the starter

[4]:

Built-ins¶

Cookiecutter¶

The cookiecutter starter will be available if cookiecutter is installed in the same Python environment as the notebook server.

Additionally, if available, importlib_metadata will be used to list the (previously) curated list of community-contributed cookiecutters. It is now recommended to search for them directly on GitHub by topic or advanced search.

One of the original motivations for Jupyter Starters was a way to provide a convenient, consistent, web-based experience for the cookiecutter ecosystem. Briefly, a cookiecutter is:

a repository, zip archive, or directory that contains

cookiecutter.json

a (potentially nested) directory that uses Jinja2 to describe file names and contents

What they may lack in dynamism, the make up for in consistency and robustness.

[5]:

Under the hood, the cookiecutter starter is implemented as a Python starter, and can be seen as tutorial in how to create a starter from a complex piece of existing functionality.

Extras¶

Starter Tree URL¶

By specifying a special URL when starting JupyterLab, you can immediately start a Starter, without requiring the launcher. The pattern is:

{:protocol}://{:host}:{:port}{:base-url}/lab/tree/starter/{:starter-name}{:starter-path}

For example:

http://localhost:8888/lab/tree/starter/cookiecutter

On Binder, this path is determined by the urlpath GET parameter, for example:

https://mybinder.org/v2/gh/deathbeds/jupyterlab-starters/master?urlpath=lab%2Ftree%2Fstarter%2Fcookiecutter%2Fexamples