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]:
_images/notebooks_Starters_4_0.svg

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]:
_images/notebooks_Starters_7_0.svg

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]:
_images/notebooks_Starters_9_0.svg

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]:
_images/notebooks_Starters_12_0.svg

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

For Users

Pre-requisites

Before you begin, you’ll need JupyterLab and NodeJS. conda is highly recommended to install both of them:

conda install -c conda-forge jupyterlab=2 nodejs

Or you can get nodejs… somehow… and JupyterLab via pip:

pip install jupyterlab=2

Installing

Get up and running fast with pip:

pip install --pre jupyter_starters
jupyter labextension install @deathbeds/jupyterlab-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:

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_notebook_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

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.

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'><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'><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"
}
Property Type Required Nullable
starters object Required cannot be null
running array Optional cannot be null
version string Required cannot be null
starters

a named set of Starters

starters

  • is required

  • Type: object (Starters)

  • cannot be null

starters Type

object (Starters)

running

Starters currently using a process/resource

running

  • is optional

  • Type: string[]

  • cannot be null

running Type

string[]

version

The version of the Jupyter Starters API

version

  • is required

  • Type: string (API Version)

  • cannot be null

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"
}
Property Type Required Nullable
Additional Properties Merged Optional cannot be null
Additional Properties

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

  • is optional

  • Type: object (Starter)

  • cannot be null

additionalProperties Type

object (Starter)

any of

Definitions group start-response

Reference this group by using

{
  "$ref": "v2.json#/definitions/start-response"
}
Property Type Required Nullable
starter Merged Required cannot be null
status string Required cannot be null
name string Required cannot be null
body object Required cannot be null
path string Required cannot be null
copy boolean Optional cannot be null
errors array Optional cannot be null
starter

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

starter

  • is required

  • Type: object (Starter)

  • cannot be null

status

the current state of the Starter

status

  • is required

  • Type: string (Status)

  • cannot be null

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

name Type

string (Name)

body

user data populated by the client

body

  • is required

  • Type: object (Body)

  • cannot be null

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

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

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

errors Type

string[] (Error Text)

Definitions group starter

Reference this group by using

{
  "$ref": "v2.json#/definitions/starter"
}
Property Type Required Nullable
type string Required cannot be null
type

type

type Type

string (Starter Type)

Definitions group starter-meta

Reference this group by using

{
  "$ref": "v2.json#/definitions/starter-meta"
}
Property Type Required Nullable
label string Required cannot be null
description string Required cannot be null
icon string Optional cannot be null
commands array Optional cannot be null
ignore array Optional cannot be null
schema object Optional cannot be null
uiSchema object Optional cannot be null
label

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

label

  • is required

  • Type: string (Label)

  • cannot be null

label Type

string (Label)

description

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

description

  • is required

  • Type: string (Description)

  • cannot be null

description Type

string (Description)

icon

SVG string to use in Launcher cards and tab icons

icon

  • is optional

  • Type: string (Icon)

  • cannot be null

icon Type

string (Icon)

commands

JupyterLab commands to run after the Starter has completed

commands

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

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

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

uiSchema Type

object (UI Schema)

Definitions group command

Reference this group by using

{
  "$ref": "v2.json#/definitions/command"
}
Property Type Required Nullable
id string Required cannot be null
args object Optional cannot be null
id

canonical name for the command

id

  • is required

  • Type: string (Command ID)

  • cannot be null

id Type

string (Command ID)

args

optional values provided to the command when executed

args

  • is optional

  • Type: object (Arguments)

  • cannot be null

args Type

object (Arguments)

Definitions group starter-copy

Reference this group by using

{
  "$ref": "v2.json#/definitions/starter-copy"
}
Property Type Required Nullable
type string Optional cannot be null
type

Signifies a copy type

type

  • is optional

  • Type: string (Copy Type)

  • cannot be null

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"
}
Property Type Required Nullable
dest string Required cannot be null
dest

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

dest

dest Type

string (Copy Destination)

Definitions group starter-notebook

Reference this group by using

{
  "$ref": "v2.json#/definitions/starter-notebook"
}
Property Type Required Nullable
type string Optional cannot be null
type

Signifies a notebook starter

type

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"
}
Property Type Required Nullable
type string Optional cannot be null
callable string Required cannot be null
type

Signifies a python starter

type

  • is optional

  • Type: string (Python Type)

  • cannot be null

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

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"
}
Property Type Required Nullable
src string Required cannot be null
py_src string Optional cannot be null
src

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

src

src Type

string (Starter Source)

py_src

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

py_src

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

Abstract Extensible Status Identifiable Custom Properties Additional Properties Access Restrictions
Can be instantiated No Unknown status Unknown identifiability Forbidden Allowed none
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
Abstract Extensible Status Identifiable Custom Properties Additional Properties Access Restrictions
Can be instantiated No Unknown status Unknown identifiability Forbidden Allowed none
items Type

string

Running Starters Schema

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

Starters currently using a process/resource

Abstract Extensible Status Identifiable Custom Properties Additional Properties Access Restrictions
Can be instantiated No Unknown status Unknown identifiability Forbidden Allowed none
running Type

string[]

Untitled undefined type in Jupyter Starters JSON Schema

v2.json#/definitions/all-starters/properties
Abstract Extensible Status Identifiable Custom Properties Additional Properties Access Restrictions
Can be instantiated No Unknown status Unknown identifiability Forbidden Allowed none
properties Type

unknown

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
all-starters Type

object (All Starters Server Response)

All Starters Server Response Properties

Property Type Required Nullable
starters object Required cannot be null
running array Optional cannot be null
version string Required cannot be null
starters

a named set of Starters

starters

  • is required

  • Type: object (Starters)

  • cannot be null

starters Type

object (Starters)

running

Starters currently using a process/resource

running

  • is optional

  • Type: string[]

  • cannot be null

running Type

string[]

version

The version of the Jupyter Starters API

version

  • is required

  • Type: string (API Version)

  • cannot be null

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

Abstract Extensible Status Identifiable Custom Properties Additional Properties Access Restrictions
Can be instantiated No Unknown status Unknown identifiability Forbidden Allowed none
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"

Untitled undefined type in Jupyter Starters JSON Schema

v2.json#/definitions/starter-copy/properties
Abstract Extensible Status Identifiable Custom Properties Additional Properties Access Restrictions
Can be instantiated No Unknown status Unknown identifiability Forbidden Allowed none
properties Type

unknown

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

Copy Starter Properties

Property Type Required Nullable
type string Optional cannot be null
type

Signifies a copy type

type

  • is optional

  • Type: string (Copy Type)

  • cannot be null

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

Abstract Extensible Status Identifiable Custom Properties Additional Properties Access Restrictions
Can be instantiated No Unknown status Unknown identifiability Forbidden Allowed none
dest Type

string (Copy Destination)

Untitled undefined type in Jupyter Starters JSON Schema

v2.json#/definitions/starter-copy-with-dest/properties
Abstract Extensible Status Identifiable Custom Properties Additional Properties Access Restrictions
Can be instantiated No Unknown status Unknown identifiability Forbidden Allowed none
properties Type

unknown

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
starter-copy-with-dest Type

object (Copy with Destination Starter)

all of

Copy with Destination Starter Properties

Property Type Required Nullable
dest string Required cannot be null
dest

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

dest

dest Type

string (Copy Destination)

Arguments Schema

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

optional values provided to the command when executed

Abstract Extensible Status Identifiable Custom Properties Additional Properties Access Restrictions
Can be instantiated No Unknown status Unknown identifiability Forbidden Allowed none
args Type

object (Arguments)

Command ID Schema

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

canonical name for the command

Abstract Extensible Status Identifiable Custom Properties Additional Properties Access Restrictions
Can be instantiated No Unknown status Unknown identifiability Forbidden Allowed none
id Type

string (Command ID)

Untitled undefined type in Jupyter Starters JSON Schema

v2.json#/definitions/command/properties
Abstract Extensible Status Identifiable Custom Properties Additional Properties Access Restrictions
Can be instantiated No Unknown status Unknown identifiability Forbidden Allowed none
properties Type

unknown

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
items Type

object (JupyterLab Command)

JupyterLab Command Properties

Property Type Required Nullable
id string Required cannot be null
args object Optional cannot be null
id

canonical name for the command

id

  • is required

  • Type: string (Command ID)

  • cannot be null

id Type

string (Command ID)

args

optional values provided to the command when executed

args

  • is optional

  • Type: object (Arguments)

  • cannot be null

args Type

object (Arguments)

Notebook Type Schema

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

Signifies a notebook starter

Abstract Extensible Status Identifiable Custom Properties Additional Properties Access Restrictions
Can be instantiated No Unknown status Unknown identifiability Forbidden Allowed none
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"

Untitled undefined type in Jupyter Starters JSON Schema

v2.json#/definitions/starter-notebook/properties
Abstract Extensible Status Identifiable Custom Properties Additional Properties Access Restrictions
Can be instantiated No Unknown status Unknown identifiability Forbidden Allowed none
properties Type

unknown

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
starter-notebook Type

object (Notebook Starter)

all of

Notebook Starter Properties

Property Type Required Nullable
type string Optional cannot be null
type

Signifies a notebook starter

type

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

Abstract Extensible Status Identifiable Custom Properties Additional Properties Access Restrictions
Can be instantiated No Unknown status Unknown identifiability Forbidden Allowed none
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

Abstract Extensible Status Identifiable Custom Properties Additional Properties Access Restrictions
Can be instantiated No Unknown status Unknown identifiability Forbidden Allowed none
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"

Untitled undefined type in Jupyter Starters JSON Schema

v2.json#/definitions/starter-python/properties
Abstract Extensible Status Identifiable Custom Properties Additional Properties Access Restrictions
Can be instantiated No Unknown status Unknown identifiability Forbidden Allowed none
properties Type

unknown

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
starter-python Type

object (Python Starter)

all of

Python Starter Properties

Property Type Required Nullable
type string Optional cannot be null
callable string Required cannot be null
type

Signifies a python starter

type

  • is optional

  • Type: string (Python Type)

  • cannot be null

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

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

Abstract Extensible Status Identifiable Custom Properties Additional Properties Access Restrictions
Can be instantiated No Unknown status Unknown identifiability Forbidden Allowed none
path Type

string (API Path)

Body Schema

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

user data populated by the client

Abstract Extensible Status Identifiable Custom Properties Additional Properties Access Restrictions
Can be instantiated No Unknown status Unknown identifiability Forbidden Allowed none
body Type

object (Body)

Error Text Schema

v2.json#/definitions/start-response/properties/errors/items
Abstract Extensible Status Identifiable Custom Properties Additional Properties Access Restrictions
Can be instantiated No Unknown status Unknown identifiability Forbidden Allowed none
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

Abstract Extensible Status Identifiable Custom Properties Additional Properties Access Restrictions
Can be instantiated No Unknown status Unknown identifiability Forbidden Allowed none
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

Abstract Extensible Status Identifiable Custom Properties Additional Properties Access Restrictions
Can be instantiated No Unknown status Unknown identifiability Forbidden Allowed none
copy Type

boolean (Force Copy)

Name Schema

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

the canonical name of the starter

Abstract Extensible Status Identifiable Custom Properties Additional Properties Access Restrictions
Can be instantiated No Unknown status Unknown identifiability Forbidden Allowed none
name Type

string (Name)

Status Schema

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

the current state of the Starter

Abstract Extensible Status Identifiable Custom Properties Additional Properties Access Restrictions
Can be instantiated No Unknown status Unknown identifiability Forbidden Allowed none
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"

Untitled undefined type in Jupyter Starters JSON Schema

v2.json#/definitions/start-response/properties
Abstract Extensible Status Identifiable Custom Properties Additional Properties Access Restrictions
Can be instantiated No Unknown status Unknown identifiability Forbidden Allowed none
properties Type

unknown

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
start-response Type

object (Start Response)

Start Response Properties

Property Type Required Nullable
starter Merged Required cannot be null
status string Required cannot be null
name string Required cannot be null
body object Required cannot be null
path string Required cannot be null
copy boolean Optional cannot be null
errors array Optional cannot be null
starter

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

starter

  • is required

  • Type: object (Starter)

  • cannot be null

status

the current state of the Starter

status

  • is required

  • Type: string (Status)

  • cannot be null

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

name Type

string (Name)

body

user data populated by the client

body

  • is required

  • Type: object (Body)

  • cannot be null

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

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

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

errors Type

string[] (Error Text)

Commands Schema

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

JupyterLab commands to run after the Starter has completed

Abstract Extensible Status Identifiable Custom Properties Additional Properties Access Restrictions
Can be instantiated No Unknown status Unknown identifiability Forbidden Allowed none
commands Type

object[] (JupyterLab Command)

Description Schema

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

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

Abstract Extensible Status Identifiable Custom Properties Additional Properties Access Restrictions
Can be instantiated No Unknown status Unknown identifiability Forbidden Allowed none
description Type

string (Description)

Icon Schema

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

SVG string to use in Launcher cards and tab icons

Abstract Extensible Status Identifiable Custom Properties Additional Properties Access Restrictions
Can be instantiated No Unknown status Unknown identifiability Forbidden Allowed none
icon Type

string (Icon)

Untitled string in Jupyter Starters JSON Schema

v2.json#/definitions/starter-meta/properties/ignore/items
Abstract Extensible Status Identifiable Custom Properties Additional Properties Access Restrictions
Can be instantiated No Unknown status Unknown identifiability Forbidden Allowed none
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

Abstract Extensible Status Identifiable Custom Properties Additional Properties Access Restrictions
Can be instantiated No Unknown status Unknown identifiability Forbidden Allowed none
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

Abstract Extensible Status Identifiable Custom Properties Additional Properties Access Restrictions
Can be instantiated No Unknown status Unknown identifiability Forbidden Allowed none
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

Abstract Extensible Status Identifiable Custom Properties Additional Properties Access Restrictions
Can be instantiated No Unknown status Unknown identifiability Forbidden Allowed none
label Type

string (Label)

UI Schema Schema

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

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

Abstract Extensible Status Identifiable Custom Properties Additional Properties Access Restrictions
Can be instantiated No Unknown status Unknown identifiability Forbidden Allowed none
uiSchema Type

object (UI Schema)

Untitled undefined type in Jupyter Starters JSON Schema

v2.json#/definitions/starter-meta/properties
Abstract Extensible Status Identifiable Custom Properties Additional Properties Access Restrictions
Can be instantiated No Unknown status Unknown identifiability Forbidden Allowed none
properties Type

unknown

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
0 Type

object (Starter Metadata)

Starter Metadata Properties

Property Type Required Nullable
label string Required cannot be null
description string Required cannot be null
icon string Optional cannot be null
commands array Optional cannot be null
ignore array Optional cannot be null
schema object Optional cannot be null
uiSchema object Optional cannot be null
label

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

label

  • is required

  • Type: string (Label)

  • cannot be null

label Type

string (Label)

description

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

description

  • is required

  • Type: string (Description)

  • cannot be null

description Type

string (Description)

icon

SVG string to use in Launcher cards and tab icons

icon

  • is optional

  • Type: string (Icon)

  • cannot be null

icon Type

string (Icon)

commands

JupyterLab commands to run after the Starter has completed

commands

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

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

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

uiSchema Type

object (UI Schema)

Starter Type Schema

v2.json#/definitions/starter/properties/type
Abstract Extensible Status Identifiable Custom Properties Additional Properties Access Restrictions
Can be instantiated No Unknown status Unknown identifiability Forbidden Allowed none
type Type

string (Starter Type)

Untitled undefined type in Jupyter Starters JSON Schema

v2.json#/definitions/starter/properties
Abstract Extensible Status Identifiable Custom Properties Additional Properties Access Restrictions
Can be instantiated No Unknown status Unknown identifiability Forbidden Allowed none
properties Type

unknown

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

Abstract Extensible Status Identifiable Custom Properties Additional Properties Access Restrictions
Can be instantiated No Unknown status Unknown identifiability Forbidden Allowed none
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)

Abstract Extensible Status Identifiable Custom Properties Additional Properties Access Restrictions
Can be instantiated No Unknown status Unknown identifiability Forbidden Allowed none
src Type

string (Starter Source)

Untitled undefined type in Jupyter Starters JSON Schema

v2.json#/definitions/starter-with-src/properties
Abstract Extensible Status Identifiable Custom Properties Additional Properties Access Restrictions
Can be instantiated No Unknown status Unknown identifiability Forbidden Allowed none
properties Type

unknown

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
starter-with-src Type

object (Starter with Files)

Starter with Files Properties

Property Type Required Nullable
src string Required cannot be null
py_src string Optional cannot be null
src

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

src

src Type

string (Starter Source)

py_src

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

py_src

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

Starter Properties

Property Type Required Nullable
type string Required cannot be null
type

type

type Type

string (Starter Type)

Starters Schema

v2.json#/definitions/starters

a named set of Starters

Abstract Extensible Status Identifiable Custom Properties Additional Properties Access Restrictions
Can be instantiated No Unknown status Unknown identifiability Forbidden Allowed none
starters Type

object (Starters)

Starters Properties

Property Type Required Nullable
Additional Properties Merged Optional cannot be null
Additional Properties

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

  • is optional

  • Type: object (Starter)

  • cannot be null

additionalProperties Type

object (Starter)

any of

Untitled undefined type in Jupyter Starters JSON Schema

v2.json#/definitions
Abstract Extensible Status Identifiable Custom Properties Additional Properties Access Restrictions
Can be instantiated No Unknown status Unknown identifiability Forbidden Allowed none
definitions Type

unknown

For Posterity

History

[2]:

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) 2020, 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

pypi-badge npm-badge license-badge

python-badge jupyterlab-badge

ci-badge

binder-badge

docs-badge roadmap-badge changelog-badge

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 >=2,<3, python >=3.6, and nodejs >=12

pip install --pre jupyter_starters
jupyter labextension install @deathbeds/jupyterlab-starters

Check your installation:

jupyter serverextension 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_notebook_config.json>`__.

Alternatives

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