Jupyter[Lab] Starters

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{:whatever}?starter/{:starter-name}{:starter-path}

For example:

http://localhost:8888/lab?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%3Fstarter%2Fcookiecutter%2Fexamples%2F

For Users

Pre-requisites

Before you begin, you’ll need JupyterLab 3.

pip install jupyterlab=3

conda or mamba is also highly recommended, once you have heavy custom dependencies:

conda install -c conda-forge jupyterlab=3

Installing

Get up and running fast with pip:

pip install --pre jupyter_starters

…or conda:

TBD

Extras

Cookiecutter

jupyter_starters integrates with (but doesn’t require) cookiecutter. It also uses importlib_resources to populate the curated “pantry” of cookiecutters. Again, install it with pip…

pip install cookiecutter importlib_resources

or conda…

conda install -c conda-forge cookiecutter importlib_resources

For Developers

and other adventurous scientists

Use Cases

The Demo

I built a cool Binder (and even included ?urlpath=lab/tree/tutorial.ipynb to open a notebook) to showcase my library, but when visitors get to their Binder, they still have to read a notebook and shift+enter their way through my example to see the plot at the end.

A starter can increase engagement by:

creating personalized content
running JupyterLab commands on the users behalf, including the mighty Run All Cells
launching a starter directly, with a Starter Tree URL

The Chore

When my scientists start a new experiment they hope will become reproducible research, they start a new folder that contains a notebook, a spreadsheet and a few other artifacts. Sometimes they don’t do it… quite right.

A starter can enhance reproducibility by:

automating boring chores
standardizing file names

Packaging Starters

Starters are configured through the traitlets system. As of notebook 5.3, these configurations can be packaged as simple files. Here’s a quick example, assuming the following file structure:

my-project:
  - setup.py
  - MANIFEST.in
  # other good stuff like LICENSE, README.md, CHANGELOG.md, CODE_OF_CONDUCT.md
  - src:
      - my_project:
          - __init__.py
          - foo.py
          - my-starter-folder:
              - my-starter-file.json
          - etc:
              - my-project-starter.json

`MANIFEST.in`

# the usual suspects
include LICENSE README.md CHANGELOG.md CODE_OF_CONDUCT.md
# ensure the starter is included in the source distribution
recursive-include src *.json

`setup.py`

import setuptools

setuptools.setup(
    ...
    include_package_data=True,
    data_files=[
        (
            "etc/jupyter/jupyter_server_config.d",
            ["src/my_project/etc/my-project-starter.json"],
        )
    ]
    zip_safe=False
)

`my-project-starter.json`

{
  "StarterManager": {
    "extra_starters": {
      "my-project-starter": {
        "label": "My Starter",
        "description": "copies a JSON file to your working directory",
        "type": "copy",
        "py_src": "my_project",
        "src": "my-starter-folder/my-starter-file.json"
      }
    }
  }
}

Note that all paths should be ``/``-delimited, even on Windows.

src can be absolute or relative to the cwd of the running notebook server…

This is not very useful when packaging, as these values cannot be known in advance!

Starter copy and notebook types, in addition to src, can use a py_src of any importable module as a portable “anchor” without

having to know the details of the installed location
or executing/importing any arbitrary code until the user requests it

However, because of how dynamic the python import system is (see importnb), giving a dotted module, e.g. my_module.foo does cause the top-level module to be imported.

Python API

Starter Manager

manager, for starters

class jupyter_starters.manager.StarterManager(**kwargs)[source]

handlers starting starters

property contents_manager: use the contents manager from parent

async just_copy(root, path)[source]: just copy, with some dummy values

property kernel_manager: use the kernel manager from parent

resolve_src(starter)[source]: resolve the src of a file-based starter

property running: report names of all starters that could be stopped

async save_one(src, dest)[source]: use the contents manager to write a single file/folder

async start(name, path, body)[source]: start a starter

async start_copy(name, starter, path, body)[source]: start a copy starter

async start_notebook(name, starter, path, body)[source]: delegate running the notebook to a kernel

async start_python(name, starter, path, body)[source]: start a python starter

property starter_names: List[str]

convenience method to get names of starters

Return type: List[str]

property starters

augment notebook starters

TODO: caching

async stop(name)[source]: stop a starter. presently only works for notebooks

async stop_notebook(name)[source]: stop running the notebook kernel

jupyter_starters.manager.iter_not_ignored(root, ignore_patterns=None)[source]: yield all children under a root that do not match the ignore patterns

Starters

Cookiecutter

a starter that runs cookiecutter

jupyter_starters.py_starters.cookiecutter.cookiecutter_pantry()[source]: try to load the pantry from the cookiecutter metadata

jupyter_starters.py_starters.cookiecutter.cookiecutter_starters(manager)[source]: try to find some cookiecutters

jupyter_starters.py_starters.cookiecutter.cookiecutter_to_schema(cookiecutter)[source]: convert a cookiecutter context to a JSON schema

async jupyter_starters.py_starters.cookiecutter.start(name, starter, path, body, manager)[source]

run cookiecutter

Return type: Dict[str, Any]

Notebook

use a notebook as a starter

async jupyter_starters.py_starters.notebook.copy_files(tmp_nb, path, manager)[source]: handle retrieving the files from the temporary directory

async jupyter_starters.py_starters.notebook.ensure_notebook(starter, path, body, tmpdir, manager)[source]: ensure a notebook exists in a temporary directory

async jupyter_starters.py_starters.notebook.get_kernel_and_tmpdir(name, starter, manager)[source]: use the manager to get a kernel and working directory

jupyter_starters.py_starters.notebook.kernel_for_path(src)[source]

get the kernel.

TODO: do better on account of freaky names

async jupyter_starters.py_starters.notebook.notebook_starter(name, starter, path, body, manager)[source]: (re)runs a notebook until its schema is correct

jupyter_starters.py_starters.notebook.response_from_nbjson(nbjson)[source]: get the starter response

jupyter_starters.py_starters.notebook.response_from_notebook(src)[source]: load a path and return the metadata

async jupyter_starters.py_starters.notebook.run_cells(nbjson, kernel, manager)[source]: actually run the cells

jupyter_starters.py_starters.notebook.starter_from_nbjson(nbjson)[source]: get just the starter

async jupyter_starters.py_starters.notebook.stop_kernel(name, manager)[source]: stop the kernel (and clean the tmpdir)

Miscellaneous

Types

some types and constants

class jupyter_starters.types.Status[source]

pseudo-enum for managing statuses

__weakref__: list of weak references to the object (if defined)

Traits

some more traits

these are not typechecked yet, because of the impedance between traitlets, JSON Schema, and mypy.

class jupyter_starters.trait_types.Schema(validator, *args, **kwargs)[source]

any… but validated by a jupyter_starters.json_.json_validator()

__init__(validator, *args, **kwargs)[source]

Declare a traitlet.

If allow_none is True, None is a valid value in addition to any values that are normally valid. The default is up to the subclass. For most trait types, the default value for allow_none is False.

If read_only is True, attempts to directly modify a trait attribute raises a TraitError.

Extra metadata can be associated with the traitlet using the .tag() convenience method or by using the traitlet instance’s .metadata dictionary.

validate(obj, value)[source]: applies a validator

Validators

some third-party preferred alternatives to stdlib/status quo for parsing and validating JSON

jupyter_starters.json_.JsonSchemaException: alias of jsonschema.exceptions.ValidationError

jupyter_starters.json_.dumps(): Converts arbitrary object recursively into JSON. Use ensure_ascii=false to output UTF-8. Set encode_html_chars=True to encode < > & as unicode escape sequences. Set escape_forward_slashes=False to prevent escaping / characters.Set allow_nan=False to raise an exception when NaN or Inf would be serialized.Set reject_bytes=True to raise TypeError on bytes.

jupyter_starters.json_.json_validator(schema)[source]

implements that fastjsonschema.compile API with jsonschema

Return type: Callable[[Dict[str, Any]], Any]

jupyter_starters.json_.loads(): Converts JSON as string to dict object structure.

REST API

jupyter_starters adds two routes to the Notebook server, which are primarily consumed by the @deathbeds/jupyterlab-starters JupyterLab extension.

Starter List

GET http://localhost:8888/starters

Returns a named map of starters, as loaded via traitlets. For example, the demo starters:

[1]:

{
  "starters": {
    "multi-stage-notebook": {
      "description": "Build a directory one file at a time",
      "label": "Multi-Stage Starter Notebook",
      "src": "./examples/Multi-Stage Starter Notebook.ipynb",
      "type": "notebook"
    },
    "notebook-starter": {
      "description": "A notebook that is also a starter",
      "label": "Starter Notebook",
      "src": "./examples/Starter Notebook.ipynb",
      "type": "notebook"
    },
    "whitepaper-multiple": {
      "description": "Some reusable notebooks for proposing research",
      "icon": "<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 48 48'><g class='jp-icon-contrast1' fill='#ccc'><circle cx='24' cy='24' r='24'/></g></svg>",
      "label": "Whitepaper Folder",
      "src": "examples/whitepaper-multiple",
      "type": "copy"
    },
    "whitepaper-named": {
      "description": "A renamed whitepaper",
      "dest": "{% now 'local' %} {{ dest }} Whitepaper.ipynb",
      "icon": "<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><g class='jp-icon-contrast3' fill='#ccc'><rect width='100' height='100'/></g></svg>",
      "label": "Named Whitepaper",
      "schema": {
        "description": "> A whitepaper that already has a name, based on the [Heilmeier Catechism](https://www.darpa.mil/work-with-us/heilmeier-catechism).",
        "properties": {
          "dest": {
            "default": "Unimagined",
            "description": "the _topic_ of the whitepaper",
            "title": "## Topic",
            "type": "string"
          }
        },
        "required": [
          "dest"
        ],
        "title": "# A Named whitepaper",
        "type": "object"
      },
      "src": "examples/whitepaper-single.ipynb",
      "type": "copy",
      "uiSchema": {
        "dest": {
          "ui:autofocus": true,
          "ui:help": "keep it short and simple: it will go in $1$ file named: `<topic> Whitepaper.ipynb`"
        }
      }
    },
    "whitepaper-single": {
      "description": "A reusable notebook for proposing research",
      "label": "Whitepaper Notebook",
      "src": "examples/whitepaper-single.ipynb",
      "type": "copy"
    }
  },
  "version": "2"
}

Starter

POST http://localhost:8888/starters/{:starter-name}/{:api-path}

Returns a start response, e.g.

{
  "body": null,
  "name": "whitepaper-single",
  "path": "whitepaper-single.ipynb",
  "starter": {
    "type": "copy",
    "label": "Whitepaper Notebook",
    "description": "A reusable notebook for proposing research",
    "src": "examples/whitepaper-single.ipynb"
  },
  "status": "done"
}

Jupyter Starters JSON Schema

v2.json

A collection of JSON types for configuring and operating Starters

| Abstract | Extensible | Status | Identifiable | Custom Properties | Additional Properties | Access Restrictions | | :——————— | :——— | :————- | :———————- | :—————- | :——————– | :—————— | :– | | Cannot be instantiated | Yes | Unknown status | Unknown identifiability | Forbidden | Allowed | none | |

Jupyter Starters JSON Type

object ()

any of

Jupyter Starters JSON Definitions

Definitions group all-starters

Reference this group by using

{
  "$ref": "v2.json#/definitions/all-starters"
}

starters

a named set of Starters

starters

is required
Type: object (Starters)
cannot be null
defined in:

starters Type

object (Starters)

running

Starters currently using a process/resource

running

is optional
Type: string[]
cannot be null
defined in:

running Type

string[]

version

The version of the Jupyter Starters API

version

is required
Type: string (API Version)
cannot be null
defined in:

version Type

string (API Version)

version Constraints

enum: the value of this property must be equal to one of the following values:

Value	Explanation
`"2"`

Definitions group starters

Reference this group by using

{
  "$ref": "v2.json#/definitions/starters"
}

Additional Properties

Additional properties are allowed, as long as they follow this schema:

is optional
Type: object (Starter)
cannot be null
defined in:

additionalProperties Type

object (Starter)

any of

all of
- Starter Metadata
- Starter with Files
all of
- all of
  - Starter Metadata
  - Starter with Files
all of
- Starter Metadata
all of
- Starter Metadata
- Starter with Files

Definitions group start-response

Reference this group by using

{
  "$ref": "v2.json#/definitions/start-response"
}

starter

the current definition of the starter: may change during multi-step starters

starter

is required
Type: object (Starter)
cannot be null
defined in:

starter Type

object (Starter)

any of

all of
- Starter Metadata
- Starter with Files
all of
- all of
  - Starter Metadata
  - Starter with Files
all of
- Starter Metadata
all of
- Starter Metadata
- Starter with Files

status

the current state of the Starter

status

is required
Type: string (Status)
cannot be null
defined in:

status Type

string (Status)

status Constraints

enum: the value of this property must be equal to one of the following values:

Value	Explanation
`"error"`
`"continuing"`
`"done"`

name

the canonical name of the starter

name

is required
Type: string (Name)
cannot be null
defined in:

name Type

string (Name)

body

user data populated by the client

body

is required
Type: object (Body)
cannot be null
defined in:

body Type

object (Body)

path

the API path (/ delimited) to which files will be written

path

is required
Type: string (API Path)
cannot be null
defined in:

path Type

string (API Path)

copy

copy files after starter is run (irrespective of status) if true

copy

is optional
Type: boolean (Force Copy)
cannot be null
defined in:

copy Type

boolean (Force Copy)

errors

a listing of system and user errors created during a starter

errors

is optional
Type: string[] (Error Text)
cannot be null
defined in:

errors Type

string[] (Error Text)

Definitions group starter

Reference this group by using

{
  "$ref": "v2.json#/definitions/starter"
}

type

type

is required
Type: string (Starter Type)
cannot be null
defined in:

type Type

string (Starter Type)

Definitions group starter-meta

Reference this group by using

{
  "$ref": "v2.json#/definitions/starter-meta"
}

label

human-readable, plain-text description used in UI labels and tab titles

label

is required
Type: string (Label)
cannot be null
defined in:

label Type

string (Label)

description

short, plain-text description of the intent of the Starter

description

is required
Type: string (Description)
cannot be null
defined in:

description Type

string (Description)

icon

SVG string to use in Launcher cards and tab icons

icon

is optional
Type: string (Icon)
cannot be null
defined in:

icon Type

string (Icon)

commands

JupyterLab commands to run after the Starter has completed

commands

is optional
Type: object[] (JupyterLab Command)
cannot be null
defined in:

commands Type

object[] (JupyterLab Command)

ignore

glob-style patterns for folders and files exclude from copying, with * for wildcards

ignore

is optional
Type: string[]
cannot be null
defined in:

ignore Type

string[]

schema

Draft 7 JSON Schema that generates a form like this one, which must validate the user’s data. Description fields may include markdown

schema

is optional
Type: object (JSON Schema)
cannot be null
defined in:

schema Type

object (JSON Schema)

uiSchema

react-jsonschema-form uiSchema for customizing the selection of widgets

uiSchema

is optional
Type: object (UI Schema)
cannot be null
defined in:

uiSchema Type

object (UI Schema)

Definitions group command

Reference this group by using

{
  "$ref": "v2.json#/definitions/command"
}

id

canonical name for the command

id

is required
Type: string (Command ID)
cannot be null
defined in:

id Type

string (Command ID)

args

optional values provided to the command when executed

args

is optional
Type: object (Arguments)
cannot be null
defined in:

args Type

object (Arguments)

Definitions group starter-copy

Reference this group by using

{
  "$ref": "v2.json#/definitions/starter-copy"
}

type

Signifies a copy type

type

is optional
Type: string (Copy Type)
cannot be null
defined in:

type Type

string (Copy Type)

type Constraints

enum: the value of this property must be equal to one of the following values:

Value	Explanation
`"copy"`

Definitions group starter-copy-with-dest

Reference this group by using

{
  "$ref": "v2.json#/definitions/starter-copy-with-dest"
}

dest

The file or folder to copy to: Jinja templates will be applied with body as the context

dest

is required
Type: string (Copy Destination)
cannot be null
defined in:

dest Type

string (Copy Destination)

Definitions group starter-notebook

Reference this group by using

{
  "$ref": "v2.json#/definitions/starter-notebook"
}

type

Signifies a notebook starter

type

is optional
Type: string (Notebook Type)
cannot be null
defined in:

type Type

string (Notebook Type)

type Constraints

enum: the value of this property must be equal to one of the following values:

Value	Explanation
`"notebook"`

Definitions group starter-python

Reference this group by using

{
  "$ref": "v2.json#/definitions/starter-python"
}

type

Signifies a python starter

type

is optional
Type: string (Python Type)
cannot be null
defined in:

type Type

string (Python Type)

type Constraints

enum: the value of this property must be equal to one of the following values:

Value	Explanation
`"python"`

callable

a python function that accepts the body

callable

is required
Type: string (Python Callable)
cannot be null
defined in:

callable Type

string (Python Callable)

callable Constraints

pattern: the string must match the following regular expression:

[a-zA-Z_\d\.]

Definitions group starter-with-src

Reference this group by using

{
  "$ref": "v2.json#/definitions/starter-with-src"
}

src

path to the starter. may be absolute or relative to the notebook launch directory (or py_src)

src

is required
Type: string (Starter Source)
cannot be null
defined in:

src Type

string (Starter Source)

py_src

name of a python module installed in the notebook environment to prepent to src

py_src

is optional
Type: string (Starter Python Source)
cannot be null
defined in:

py_src Type

string (Starter Python Source)

All JSON Schema

API Version Schema

v2.json#/definitions/all-starters/properties/version

The version of the Jupyter Starters API

version Type

string (API Version)

version Constraints

enum: the value of this property must be equal to one of the following values:

Value	Explanation
`"2"`

Untitled string in Jupyter Starters JSON Schema

v2.json#/definitions/all-starters/properties/running/items

items Type

string

Running Starters Schema

v2.json#/definitions/all-starters/properties/running

Starters currently using a process/resource

running Type

string[]

All Starters Server Response Schema

v2.json#/definitions/all-starters

| Abstract | Extensible | Status | Identifiable | Custom Properties | Additional Properties | Access Restrictions | | :—————— | :——— | :————- | :———– | :—————- | :——————– | :—————— | :———————————————————— | | Can be instantiated | No | Unknown status | No | Forbidden | Allowed | none | v2.json* |

all-starters Type

object (All Starters Server Response)

all-starters Properties

starters

a named set of Starters

starters

is required
Type: object (Starters)
cannot be null
defined in:

starters Type

object (Starters)

running

Starters currently using a process/resource

running

is optional
Type: string[]
cannot be null
defined in:

running Type

string[]

version

The version of the Jupyter Starters API

version

is required
Type: string (API Version)
cannot be null
defined in:

version Type

string (API Version)

version Constraints

enum: the value of this property must be equal to one of the following values:

Value	Explanation
`"2"`

Copy Type Schema

v2.json#/definitions/starter-copy/properties/type

Signifies a copy type

type Type

string (Copy Type)

type Constraints

enum: the value of this property must be equal to one of the following values:

Value	Explanation
`"copy"`

Copy Starter Schema

v2.json#/definitions/starter-copy-with-dest/allOf/0

All the properties from a Copy Starter

| Abstract | Extensible | Status | Identifiable | Custom Properties | Additional Properties | Access Restrictions | | :—————— | :——— | :————- | :———– | :—————- | :——————– | :—————— | :———————————————————— | | Can be instantiated | No | Unknown status | No | Forbidden | Allowed | none | v2.json* |

0 Type

object (Copy Starter)

all of

0 Properties

type

Signifies a copy type

type

is optional
Type: string (Copy Type)
cannot be null
defined in:

type Type

string (Copy Type)

type Constraints

enum: the value of this property must be equal to one of the following values:

Value	Explanation
`"copy"`

Copy Destination Schema

v2.json#/definitions/starter-copy-with-dest/properties/dest

The file or folder to copy to: Jinja templates will be applied with body as the context

dest Type

string (Copy Destination)

Copy with Destination Starter Schema

v2.json#/definitions/starter-copy-with-dest

| Abstract | Extensible | Status | Identifiable | Custom Properties | Additional Properties | Access Restrictions | | :—————— | :——— | :————- | :———– | :—————- | :——————– | :—————— | :———————————————————— | | Can be instantiated | No | Unknown status | No | Forbidden | Allowed | none | v2.json* |

starter-copy-with-dest Type

object (Copy with Destination Starter)

all of

all of
- Starter Metadata
- Starter with Files

starter-copy-with-dest Properties

dest

The file or folder to copy to: Jinja templates will be applied with body as the context

dest

is required
Type: string (Copy Destination)
cannot be null
defined in:

dest Type

string (Copy Destination)

Arguments Schema

v2.json#/definitions/command/properties/args

optional values provided to the command when executed

args Type

object (Arguments)

Command ID Schema

v2.json#/definitions/command/properties/id

canonical name for the command

id Type

string (Command ID)

JupyterLab Command Schema

v2.json#/definitions/starter-meta/properties/commands/items

| Abstract | Extensible | Status | Identifiable | Custom Properties | Additional Properties | Access Restrictions | | :—————— | :——— | :————- | :———– | :—————- | :——————– | :—————— | :———————————————————— | | Can be instantiated | No | Unknown status | No | Forbidden | Allowed | none | v2.json* |

items Type

object (JupyterLab Command)

items Properties

id

canonical name for the command

id

is required
Type: string (Command ID)
cannot be null
defined in:

id Type

string (Command ID)

args

optional values provided to the command when executed

args

is optional
Type: object (Arguments)
cannot be null
defined in:

args Type

object (Arguments)

Notebook Type Schema

v2.json#/definitions/starter-notebook/properties/type

Signifies a notebook starter

type Type

string (Notebook Type)

type Constraints

enum: the value of this property must be equal to one of the following values:

Value	Explanation
`"notebook"`

Notebook Starter Schema

v2.json#/definitions/starter-notebook

Uses a notebook as both the configuration object (in #/metadata/jupyter-starters) and execution

| Abstract | Extensible | Status | Identifiable | Custom Properties | Additional Properties | Access Restrictions | | :—————— | :——— | :————- | :———– | :—————- | :——————– | :—————— | :———————————————————— | | Can be instantiated | No | Unknown status | No | Forbidden | Allowed | none | v2.json* |

starter-notebook Type

object (Notebook Starter)

all of

starter-notebook Properties

type

Signifies a notebook starter

type

is optional
Type: string (Notebook Type)
cannot be null
defined in:

type Type

string (Notebook Type)

type Constraints

enum: the value of this property must be equal to one of the following values:

Value	Explanation
`"notebook"`

Python Callable Schema

v2.json#/definitions/starter-python/properties/callable

a python function that accepts the body

callable Type

string (Python Callable)

callable Constraints

pattern: the string must match the following regular expression:

[a-zA-Z_\d\.]

Python Type Schema

v2.json#/definitions/starter-python/properties/type

Signifies a python starter

type Type

string (Python Type)

type Constraints

enum: the value of this property must be equal to one of the following values:

Value	Explanation
`"python"`

Python Starter Schema

v2.json#/definitions/starter-python

Invokes an importable python function (multiple times)

| Abstract | Extensible | Status | Identifiable | Custom Properties | Additional Properties | Access Restrictions | | :—————— | :——— | :————- | :———– | :—————- | :——————– | :—————— | :———————————————————— | | Can be instantiated | No | Unknown status | No | Forbidden | Allowed | none | v2.json* |

starter-python Type

object (Python Starter)

all of

Starter Metadata

starter-python Properties

type

Signifies a python starter

type

is optional
Type: string (Python Type)
cannot be null
defined in:

type Type

string (Python Type)

type Constraints

enum: the value of this property must be equal to one of the following values:

Value	Explanation
`"python"`

callable

a python function that accepts the body

callable

is required
Type: string (Python Callable)
cannot be null
defined in:

callable Type

string (Python Callable)

callable Constraints

pattern: the string must match the following regular expression:

[a-zA-Z_\d\.]

API Path Schema

v2.json#/definitions/start-response/properties/path

the API path (/ delimited) to which files will be written

path Type

string (API Path)

Body Schema

v2.json#/definitions/start-response/properties/body

user data populated by the client

body Type

object (Body)

Error Text Schema

v2.json#/definitions/start-response/properties/errors/items

items Type

string (Error Text)

Errors Schema

v2.json#/definitions/start-response/properties/errors

a listing of system and user errors created during a starter

errors Type

string[] (Error Text)

Force Copy Schema

v2.json#/definitions/start-response/properties/copy

copy files after starter is run (irrespective of status) if true

copy Type

boolean (Force Copy)

Name Schema

v2.json#/definitions/start-response/properties/name

the canonical name of the starter

name Type

string (Name)

Status Schema

v2.json#/definitions/start-response/properties/status

the current state of the Starter

status Type

string (Status)

status Constraints

enum: the value of this property must be equal to one of the following values:

Value	Explanation
`"error"`
`"continuing"`
`"done"`

Start Response Schema

v2.json#/definitions/start-response

| Abstract | Extensible | Status | Identifiable | Custom Properties | Additional Properties | Access Restrictions | | :—————— | :——— | :————- | :———– | :—————- | :——————– | :—————— | :———————————————————— | | Can be instantiated | No | Unknown status | No | Forbidden | Allowed | none | v2.json* |

start-response Type

object (Start Response)

start-response Properties

starter

the current definition of the starter: may change during multi-step starters

starter

is required
Type: object (Starter)
cannot be null
defined in:

starter Type

object (Starter)

any of

all of
- Starter Metadata
- Starter with Files
all of
- all of
  - Starter Metadata
  - Starter with Files
all of
- Starter Metadata
all of
- Starter Metadata
- Starter with Files

status

the current state of the Starter

status

is required
Type: string (Status)
cannot be null
defined in:

status Type

string (Status)

status Constraints

enum: the value of this property must be equal to one of the following values:

Value	Explanation
`"error"`
`"continuing"`
`"done"`

name

the canonical name of the starter

name

is required
Type: string (Name)
cannot be null
defined in:

name Type

string (Name)

body

user data populated by the client

body

is required
Type: object (Body)
cannot be null
defined in:

body Type

object (Body)

path

the API path (/ delimited) to which files will be written

path

is required
Type: string (API Path)
cannot be null
defined in:

path Type

string (API Path)

copy

copy files after starter is run (irrespective of status) if true

copy

is optional
Type: boolean (Force Copy)
cannot be null
defined in:

copy Type

boolean (Force Copy)

errors

a listing of system and user errors created during a starter

errors

is optional
Type: string[] (Error Text)
cannot be null
defined in:

errors Type

string[] (Error Text)

Commands Schema

v2.json#/definitions/starter-meta/properties/commands

JupyterLab commands to run after the Starter has completed

commands Type

object[] (JupyterLab Command)

Description Schema

v2.json#/definitions/starter-meta/properties/description

short, plain-text description of the intent of the Starter

description Type

string (Description)

Icon Schema

v2.json#/definitions/starter-meta/properties/icon

SVG string to use in Launcher cards and tab icons

icon Type

string (Icon)

Untitled string in Jupyter Starters JSON Schema

v2.json#/definitions/starter-meta/properties/ignore/items

items Type

string

Ignore Files Schema

v2.json#/definitions/starter-meta/properties/ignore

glob-style patterns for folders and files exclude from copying, with * for wildcards

ignore Type

string[]

JSON Schema Schema

v2.json#/definitions/starter-meta/properties/schema

Draft 7 JSON Schema that generates a form like this one, which must validate the user’s data. Description fields may include markdown

schema Type

object (JSON Schema)

Label Schema

v2.json#/definitions/starter-meta/properties/label

human-readable, plain-text description used in UI labels and tab titles

label Type

string (Label)

UI Schema Schema

v2.json#/definitions/starter-meta/properties/uiSchema

react-jsonschema-form uiSchema for customizing the selection of widgets

uiSchema Type

object (UI Schema)

Starter Metadata Schema

v2.json#/definitions/starter-python/allOf/0

common metadata for Starters

| Abstract | Extensible | Status | Identifiable | Custom Properties | Additional Properties | Access Restrictions | | :—————— | :——— | :————- | :———– | :—————- | :——————– | :—————— | :———————————————————— | | Can be instantiated | No | Unknown status | No | Forbidden | Allowed | none | v2.json* |

0 Type

object (Starter Metadata)

0 Properties

label

human-readable, plain-text description used in UI labels and tab titles

label

is required
Type: string (Label)
cannot be null
defined in:

label Type

string (Label)

description

short, plain-text description of the intent of the Starter

description

is required
Type: string (Description)
cannot be null
defined in:

description Type

string (Description)

icon

SVG string to use in Launcher cards and tab icons

icon

is optional
Type: string (Icon)
cannot be null
defined in:

icon Type

string (Icon)

commands

JupyterLab commands to run after the Starter has completed

commands

is optional
Type: object[] (JupyterLab Command)
cannot be null
defined in:

commands Type

object[] (JupyterLab Command)

ignore

glob-style patterns for folders and files exclude from copying, with * for wildcards

ignore

is optional
Type: string[]
cannot be null
defined in:

ignore Type

string[]

schema

Draft 7 JSON Schema that generates a form like this one, which must validate the user’s data. Description fields may include markdown

schema

is optional
Type: object (JSON Schema)
cannot be null
defined in:

schema Type

object (JSON Schema)

uiSchema

react-jsonschema-form uiSchema for customizing the selection of widgets

uiSchema

is optional
Type: object (UI Schema)
cannot be null
defined in:

uiSchema Type

object (UI Schema)

Starter Type Schema

v2.json#/definitions/starter/properties/type

type Type

string (Starter Type)

Starter Python Source Schema

v2.json#/definitions/starter-with-src/properties/py_src

name of a python module installed in the notebook environment to prepent to src

py_src Type

string (Starter Python Source)

Starter Source Schema

v2.json#/definitions/starter-with-src/properties/src

path to the starter. may be absolute or relative to the notebook launch directory (or py_src)

src Type

string (Starter Source)

Starter with Files Schema

v2.json#/definitions/starter-with-src

| Abstract | Extensible | Status | Identifiable | Custom Properties | Additional Properties | Access Restrictions | | :—————— | :——— | :————- | :———– | :—————- | :——————– | :—————— | :———————————————————— | | Can be instantiated | No | Unknown status | No | Forbidden | Allowed | none | v2.json* |

starter-with-src Type

object (Starter with Files)

starter-with-src Properties

src

path to the starter. may be absolute or relative to the notebook launch directory (or py_src)

src

is required
Type: string (Starter Source)
cannot be null
defined in:

src Type

string (Starter Source)

py_src

name of a python module installed in the notebook environment to prepent to src

py_src

is optional
Type: string (Starter Python Source)
cannot be null
defined in:

py_src Type

string (Starter Python Source)

Starter Schema

v2.json#/definitions/starter

| Abstract | Extensible | Status | Identifiable | Custom Properties | Additional Properties | Access Restrictions | | :—————— | :——— | :————- | :———– | :—————- | :——————– | :—————— | :———————————————————— | | Can be instantiated | No | Unknown status | No | Forbidden | Allowed | none | v2.json* |

starter Type

object (Starter)

any of

all of
- Starter Metadata
- Starter with Files
all of
- all of
  - Starter Metadata
  - Starter with Files
all of
- Starter Metadata
all of
- Starter Metadata
- Starter with Files

starter Properties

type

type

is required
Type: string (Starter Type)
cannot be null
defined in:

type Type

string (Starter Type)

Starters Schema

v2.json#/definitions/starters

a named set of Starters

starters Type

object (Starters)

starters Properties

Additional Properties

Additional properties are allowed, as long as they follow this schema:

is optional
Type: object (Starter)
cannot be null
defined in:

additionalProperties Type

object (Starter)

any of

all of
- Starter Metadata
- Starter with Files
all of
- all of
  - Starter Metadata
  - Starter with Files
all of
- Starter Metadata
all of
- Starter Metadata
- Starter with Files

Untitled undefined type in Jupyter Starters JSON Schema

v2.json#/definitions

definitions Type

unknown

For Posterity

History

[2]:

`jupyter_starters 1.0.2` (unreleased)

#54 adapt kernel shutdown to newer jupyter_client >=6.1 API

`@deathbeds/jupyterlab-starters 1.0.2` (unreleased)

`@deathbeds/jupyterlab-rjsf 1.0.2` (unreleased)

#56 upgrade to @rjsf/core 2.5.1

`jupyter_starters 1.0.1a0`

#51 update of @deathbeds/jupyterlab-rjsf and @deathbeds/jupyterlab-starters.

`@deathbeds/jupyterlab-starters 1.0.1a0`

#51 uses new @deathbeds/jupyterlab-rjsf API

`@deathbeds/jupyterlab-rjsf 1.0.1a0`

#51 make more exports lazy loading

`jupyter_starters 1.0.0a0`

#48 support JupyterLab 3.x
it is now only necessary (and supported) to pip install this package to also install JupyterLab extensions
JupyterLab 1/2-style installation for user Lab Apps is no longer tested
for downstreams extensions, releases will continue on npmjs.org
- versions sycned to the python package
- on-going API support TBD

Breaking changes

due to upstream changes, the router URL has, for now, has changed from:
/lab/tree/starter/<starter>/<path> to
?starter=<starter>/<path>

`@deathbeds/jupyterlab-rjsf 1.0.0a0`

#48 support JupyterLab 3.x

`@deathbeds/jupyterlab-starters 1.0.0a0`

#48 support JupyterLab 3.x

`jupyter_starters 0.6.0a0`

#45 use new @deathbeds/jupyterlab-starters 0.6.0a0
#45 be more specific on URL patterns

`@deathbeds/jupyterlab-rjsf 0.6.0a0`

#45 upgrade @rjsf/core for anyOf fixes
#45 upgrade react-codemirror2

`@deathbeds/jupyterlab-starters 0.6.0a0`

#45 use new @deathbeds/jupyterlab-rjsf 0.6.0a0

`jupyter_starters 0.5.0a0`

#41 handle more recent cookiecutter metadata

`@deathbeds/jupyterlab-rjsf 0.5.0a0`

#41 upgrade react-jsonschema-form to @rjsf/core

`@deathbeds/jupyterlab-starters 0.5.0a0`

#41 upgrade @deathbeds/jupyterlab-rjsf

`@deathbeds/jupyterlab-rjsf 0.4.0a0`

#38 split out rjsf into its own package

`@deathbeds/jupyterlab-starters 0.4.0a0`

#38 depend on @deathbeds/jupyterlab-rjsf

`jupyter_starters 0.4.0a0`

Updated for parity with frontend

`jupyter_starters 0.3.0a0`

#39 adds listing and stopping of currently-running kernels to REST API

`@deathbeds/jupyterlab-starters 0.3.0a0`

#39 supports JupyterLab 2.0
#39 adds listing and stopping of running kernel-backed starters

`jupyter_starters 0.2.2a0`

#23 rename _json module to json_, start documentation site in earnest

`@deathbeds/jupyterlab-starters 0.2.2a0`

#29 some updated class names based on schema
#34 add stauts indicator for starting/continuing
#35 add /lab/tree/starter/<starter>/<path> URL router

`jupyter_starters 0.2.1a0`

#25 add py_src for easier distribution of starters
#25 add unit tests
#29 handle minimally specified notebook metadata

`@deathbeds/jupyterlab-starters 0.2.1a0`

#29 handle minimally specified notebook metadata

`jupyter_starters 0.2.0a0`

#13 add notebook as starter
#18 add copying files and commands while starter is continuing

`@deathbeds/jupyterlab-starters 0.2.0a0`

#13 add notebook metadata authoring
#17 add Jupyter markdown to title, description and ui:help in schema forms
#18 all starters launch in right sidebar
#21 enable CodeMirror for JSON, Markdown, etc. editing

`jupyter_starters 0.1.0a3`

make optional dependency messages only appear in debug mode

–

`jupyter_starters 0.1.0a2`

add ignore patterns to schema
fix default ignore patterns

`@deathbeds/jupyterlab-starters 0.1.0a2`

add glob ignore patterns to schema

`jupyter_starters 0.1.0a1`

add more sources of config

`@deathbeds/jupyterlab-starters 0.1.0a0`

initial implementation

`jupyter_starters 0.1.0a0`

initial implementation

Roadmap

[3]:

[ ] Adopt some well-known locations for more user-serviceable starters
[ ] Add generic script type
[ ] Add preview/dry-run
[ ] Add better error handling and logging
[ ] Explore json-e integration
[ ] Add starter builder with command explorer

License

[4]:

BSD 3-Clause License

Copyright (c) 2021, dead pixels collective
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, this
  list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright notice,
  this list of conditions and the following disclaimer in the documentation
  and/or other materials provided with the distribution.

* Neither the name of the copyright holder nor the names of its
  contributors may be used to endorse or promote products derived from
  this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

[1]:

releases	deps	ci	demo	docs

screenshot

What’s a starter?

A starter is a…

single file
directory
python function
cookiecutter
notebook

… that creates a…

single file
directory of files (or more directories)

… that shows up where you want it in JupyterLab at the click of a button

Installing

You’ll need jupyterlab >=3,<4, python >=3.6, and nodejs >=12

pip install --pre jupyter_starters

Check your installation:

jupyter serverextension list
jupyter labextension list

If you don’t see jupyterlab_starters run:

jupyter serverextension enable --sys-prefix jupyterlab_starters

Configuring

Like the Jupyter Notebook server, JupyterHub and other Jupyter interactive computing tools, jupyter-starters can be configured via Python or JSON files in well-known locations. You can find out where to put them on your system with:

jupyter --paths

They will be merged from bottom to top, and the directory where you launch your notebook server wins, making it easy to check in to version control.

The very simplest starter, copy, will copy a file or folder to the location it is launched from in the JupyterLab Launcher.

{
  "StarterManager": {
    "extra_starters": {
      "whitepaper-single": {
        "type": "copy",
        "label": "Whitepaper Notebook",
        "description": "A reusable notebook for proposing research",
        "src": "examples/whitepaper-single.ipynb"
      }
    }
  }
}

more docs TBD: for now, see examples in the `demo configuration <https://github.com/deathbeds/jupyterlab-starters/tree/master/jupyter_server_config.json>`__.

Alternatives

Don’t like what you see here? Try these other approaches:

jupyterlab_templates

Jupyter[Lab] Starters

For Starters

Types of Starters

Copy

Python

Notebook

Built-ins

Cookiecutter

Extras

Starter Tree URL

For Users

Pre-requisites

Installing

Extras

Cookiecutter

For Developers

Use Cases

The Demo

The Chore

Packaging Starters

MANIFEST.in

setup.py

my-project-starter.json

Python API

Starter Manager

Starters

Cookiecutter

Notebook

Miscellaneous

Types

Traits

Validators

REST API

Starter List

Starter

Jupyter Starters JSON Schema

Jupyter Starters JSON Type

Jupyter Starters JSON Definitions

Definitions group all-starters

starters

starters Type

running

running Type

version

version Type

version Constraints

Definitions group starters

Additional Properties

additionalProperties Type

Definitions group start-response

starter

starter Type

status

status Type

status Constraints

name

name Type

body

body Type

path

path Type

copy

copy Type

errors

errors Type

Definitions group starter

type

type Type

Definitions group starter-meta

label

label Type

description

description Type

icon

icon Type

commands

commands Type

ignore

ignore Type

schema

`MANIFEST.in`

`setup.py`

`my-project-starter.json`