CLI#

Hide code cell content 
import os, pathlib, tempfile, shutil, atexit, hashlib, pprint
from IPython.display import *
from IPython import get_ipython  # needed for `jupyter_execute` because magics?

RTD = os.environ.get("READTHEDOCS")

The jupyter lite (or jupyter-lite) CLI provides tools for lifecycle of combining…

  • the core JupyterLite static assets

  • extra application features like Lab Extensions and settings

  • kernel-specific resources like Python wheels

  • user-authored content like Notebooks

… into a ready-to-deploy (and optionally reproducible) Jupyter sites which require an HTTP server, but no application server.

Installation#

!pip install jupyterlite
!jupyter lite --version

Requirement already satisfied: jupyterlite in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (0.1.0b14)

Requirement already satisfied: doit<1,>=0.34 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyterlite) (0.36.0)
Requirement already satisfied: jupyter_core>=4.7 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyterlite) (5.0.0)
Requirement already satisfied: importlib-metadata>=4.4 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from doit<1,>=0.34->jupyterlite) (5.0.0)
Requirement already satisfied: cloudpickle in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from doit<1,>=0.34->jupyterlite) (2.2.0)
Requirement already satisfied: traitlets in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter_core>=4.7->jupyterlite) (5.5.0)
Requirement already satisfied: platformdirs in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter_core>=4.7->jupyterlite) (2.5.2)
Requirement already satisfied: zipp>=0.5 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from importlib-metadata>=4.4->doit<1,>=0.34->jupyterlite) (3.10.0)

0.1.0b14

Addon Dependencies#

Some extra features of different addons have additional dependencies.

pip install jupyterlite[contents] # jupyter_server for contents API indexing
pip install jupyterlite[serve]    # tornado for better local previewing with `serve`
pip install jupyterlite[piplite]  # pkginfo for reading wheel metadata for the pyolite kernel
pip install jupyterlite[mathjax]  # reuse the MathJax assets from jupyter-server-mathjax
pip install jupyterlite[check]    # validate more data with jsonschema
pip install jupyterlite[lab]      # a known-compatible jupyterlab (entails `contents`, `serve`, `check`)

…or, for everything:

pip install jupyterlite[all]      # all of the above!

!pip install jupyterlite[all]
Hide code cell output 
Requirement already satisfied: jupyterlite[all] in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (0.1.0b14)

Requirement already satisfied: doit<1,>=0.34 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyterlite[all]) (0.36.0)
Requirement already satisfied: jupyter_core>=4.7 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyterlite[all]) (5.0.0)
Requirement already satisfied: jsonschema>=3 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyterlite[all]) (4.17.0)
Requirement already satisfied: jupyterlab_server<3,>=2.8.1 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyterlite[all]) (2.16.3)

Collecting jupyterlab<4,>=3.5.0

  Downloading jupyterlab-3.5.0-py3-none-any.whl (8.8 MB)
?25l                                              0.0/8.8 MB ? eta -:--:--

     ━━━━━━━━━━━━                             2.7/8.8 MB 81.8 MB/s eta 0:00:01
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╸ 8.8/8.8 MB 130.4 MB/s eta 0:00:01

     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 8.8/8.8 MB 83.9 MB/s eta 0:00:00
?25h

Requirement already satisfied: jupyter-server-mathjax>=0.2.3 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyterlite[all]) (0.2.6)
Requirement already satisfied: pkginfo in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyterlite[all]) (1.8.3)
Requirement already satisfied: tornado>=6.1 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyterlite[all]) (6.2)
Requirement already satisfied: jupyter_server in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyterlite[all]) (1.23.2)
Requirement already satisfied: importlib-metadata>=4.4 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from doit<1,>=0.34->jupyterlite[all]) (5.0.0)
Requirement already satisfied: cloudpickle in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from doit<1,>=0.34->jupyterlite[all]) (2.2.0)
Requirement already satisfied: attrs>=17.4.0 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jsonschema>=3->jupyterlite[all]) (22.1.0)
Requirement already satisfied: pyrsistent!=0.17.0,!=0.17.1,!=0.17.2,>=0.14.0 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jsonschema>=3->jupyterlite[all]) (0.19.2)
Requirement already satisfied: platformdirs in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter_core>=4.7->jupyterlite[all]) (2.5.2)
Requirement already satisfied: traitlets in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter_core>=4.7->jupyterlite[all]) (5.5.0)

Requirement already satisfied: jinja2 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter_server->jupyterlite[all]) (3.1.2)
Requirement already satisfied: prometheus-client in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter_server->jupyterlite[all]) (0.15.0)
Requirement already satisfied: Send2Trash in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter_server->jupyterlite[all]) (1.8.0)
Requirement already satisfied: argon2-cffi in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter_server->jupyterlite[all]) (21.3.0)
Requirement already satisfied: packaging in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter_server->jupyterlite[all]) (21.3)
Requirement already satisfied: nbconvert>=6.4.4 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter_server->jupyterlite[all]) (7.2.5)
Requirement already satisfied: websocket-client in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter_server->jupyterlite[all]) (1.4.2)
Requirement already satisfied: terminado>=0.8.3 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter_server->jupyterlite[all]) (0.17.0)
Requirement already satisfied: pyzmq>=17 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter_server->jupyterlite[all]) (24.0.1)
Requirement already satisfied: jupyter-client>=6.1.12 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter_server->jupyterlite[all]) (7.4.7)
Requirement already satisfied: anyio<4,>=3.1.0 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter_server->jupyterlite[all]) (3.6.2)
Requirement already satisfied: nbformat>=5.2.0 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter_server->jupyterlite[all]) (5.7.0)

Collecting notebook<7
  Downloading notebook-6.5.2-py3-none-any.whl (439 kB)
?25l                                              0.0/439.1 kB ? eta -:--:--
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 439.1/439.1 kB 63.0 MB/s eta 0:00:00
?25h

Collecting nbclassic
  Downloading nbclassic-0.4.8-py3-none-any.whl (9.8 MB)
?25l                                              0.0/9.8 MB ? eta -:--:--

     ━━━━━━━━━━━━━━━━━━━━━━━                  5.7/9.8 MB 170.4 MB/s eta 0:00:01

     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╸ 9.8/9.8 MB 169.9 MB/s eta 0:00:01
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 9.8/9.8 MB 99.7 MB/s eta 0:00:00
?25h

Requirement already satisfied: ipython in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyterlab<4,>=3.5.0->jupyterlite[all]) (8.6.0)
Requirement already satisfied: tomli in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyterlab<4,>=3.5.0->jupyterlite[all]) (2.0.1)
Requirement already satisfied: requests in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyterlab_server<3,>=2.8.1->jupyterlite[all]) (2.28.1)
Requirement already satisfied: babel in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyterlab_server<3,>=2.8.1->jupyterlite[all]) (2.11.0)
Requirement already satisfied: json5 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyterlab_server<3,>=2.8.1->jupyterlite[all]) (0.9.5)

Requirement already satisfied: sniffio>=1.1 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from anyio<4,>=3.1.0->jupyter_server->jupyterlite[all]) (1.3.0)
Requirement already satisfied: idna>=2.8 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from anyio<4,>=3.1.0->jupyter_server->jupyterlite[all]) (3.4)

Requirement already satisfied: zipp>=0.5 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from importlib-metadata>=4.4->doit<1,>=0.34->jupyterlite[all]) (3.10.0)
Requirement already satisfied: MarkupSafe>=2.0 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jinja2->jupyter_server->jupyterlite[all]) (2.1.1)
Requirement already satisfied: python-dateutil>=2.8.2 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter-client>=6.1.12->jupyter_server->jupyterlite[all]) (2.8.2)
Requirement already satisfied: entrypoints in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter-client>=6.1.12->jupyter_server->jupyterlite[all]) (0.4)
Requirement already satisfied: nest-asyncio>=1.5.4 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter-client>=6.1.12->jupyter_server->jupyterlite[all]) (1.5.6)

Requirement already satisfied: defusedxml in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from nbconvert>=6.4.4->jupyter_server->jupyterlite[all]) (0.7.1)
Requirement already satisfied: tinycss2 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from nbconvert>=6.4.4->jupyter_server->jupyterlite[all]) (1.2.1)
Requirement already satisfied: beautifulsoup4 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from nbconvert>=6.4.4->jupyter_server->jupyterlite[all]) (4.11.1)
Requirement already satisfied: jupyterlab-pygments in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from nbconvert>=6.4.4->jupyter_server->jupyterlite[all]) (0.2.2)
Requirement already satisfied: nbclient>=0.5.0 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from nbconvert>=6.4.4->jupyter_server->jupyterlite[all]) (0.5.13)
Requirement already satisfied: pygments>=2.4.1 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from nbconvert>=6.4.4->jupyter_server->jupyterlite[all]) (2.13.0)
Requirement already satisfied: mistune<3,>=2.0.3 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from nbconvert>=6.4.4->jupyter_server->jupyterlite[all]) (2.0.4)
Requirement already satisfied: pandocfilters>=1.4.1 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from nbconvert>=6.4.4->jupyter_server->jupyterlite[all]) (1.5.0)
Requirement already satisfied: bleach in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from nbconvert>=6.4.4->jupyter_server->jupyterlite[all]) (5.0.1)
Requirement already satisfied: fastjsonschema in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from nbformat>=5.2.0->jupyter_server->jupyterlite[all]) (2.16.2)

Collecting ipython-genutils
  Downloading ipython_genutils-0.2.0-py2.py3-none-any.whl (26 kB)
Requirement already satisfied: ipykernel in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from notebook<7->jupyterlab<4,>=3.5.0->jupyterlite[all]) (6.17.1)

Collecting notebook-shim>=0.1.0
  Downloading notebook_shim-0.2.2-py3-none-any.whl (13 kB)

Requirement already satisfied: ptyprocess in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from terminado>=0.8.3->jupyter_server->jupyterlite[all]) (0.7.0)
Requirement already satisfied: argon2-cffi-bindings in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from argon2-cffi->jupyter_server->jupyterlite[all]) (21.2.0)
Requirement already satisfied: pytz>=2015.7 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from babel->jupyterlab_server<3,>=2.8.1->jupyterlite[all]) (2022.6)

Requirement already satisfied: stack-data in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from ipython->jupyterlab<4,>=3.5.0->jupyterlite[all]) (0.6.1)

Requirement already satisfied: backcall in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from ipython->jupyterlab<4,>=3.5.0->jupyterlite[all]) (0.2.0)
Requirement already satisfied: jedi>=0.16 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from ipython->jupyterlab<4,>=3.5.0->jupyterlite[all]) (0.18.1)
Requirement already satisfied: pexpect>4.3 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from ipython->jupyterlab<4,>=3.5.0->jupyterlite[all]) (4.8.0)
Requirement already satisfied: prompt-toolkit<3.1.0,>3.0.1 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from ipython->jupyterlab<4,>=3.5.0->jupyterlite[all]) (3.0.32)
Requirement already satisfied: decorator in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from ipython->jupyterlab<4,>=3.5.0->jupyterlite[all]) (5.1.1)
Requirement already satisfied: matplotlib-inline in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from ipython->jupyterlab<4,>=3.5.0->jupyterlite[all]) (0.1.6)
Requirement already satisfied: pickleshare in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from ipython->jupyterlab<4,>=3.5.0->jupyterlite[all]) (0.7.5)
Requirement already satisfied: pyparsing!=3.0.5,>=2.0.2 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from packaging->jupyter_server->jupyterlite[all]) (3.0.9)
Requirement already satisfied: charset-normalizer<3,>=2 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from requests->jupyterlab_server<3,>=2.8.1->jupyterlite[all]) (2.1.1)
Requirement already satisfied: certifi>=2017.4.17 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from requests->jupyterlab_server<3,>=2.8.1->jupyterlite[all]) (2022.9.24)
Requirement already satisfied: urllib3<1.27,>=1.21.1 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from requests->jupyterlab_server<3,>=2.8.1->jupyterlite[all]) (1.26.11)

Requirement already satisfied: parso<0.9.0,>=0.8.0 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jedi>=0.16->ipython->jupyterlab<4,>=3.5.0->jupyterlite[all]) (0.8.3)

Requirement already satisfied: wcwidth in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from prompt-toolkit<3.1.0,>3.0.1->ipython->jupyterlab<4,>=3.5.0->jupyterlite[all]) (0.2.5)
Requirement already satisfied: six>=1.5 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from python-dateutil>=2.8.2->jupyter-client>=6.1.12->jupyter_server->jupyterlite[all]) (1.16.0)

Requirement already satisfied: cffi>=1.0.1 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from argon2-cffi-bindings->argon2-cffi->jupyter_server->jupyterlite[all]) (1.15.1)
Requirement already satisfied: soupsieve>1.2 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from beautifulsoup4->nbconvert>=6.4.4->jupyter_server->jupyterlite[all]) (2.3.2.post1)

Requirement already satisfied: webencodings in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from bleach->nbconvert>=6.4.4->jupyter_server->jupyterlite[all]) (0.5.1)
Requirement already satisfied: psutil in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from ipykernel->notebook<7->jupyterlab<4,>=3.5.0->jupyterlite[all]) (5.9.4)
Requirement already satisfied: debugpy>=1.0 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from ipykernel->notebook<7->jupyterlab<4,>=3.5.0->jupyterlite[all]) (1.6.3)

Requirement already satisfied: executing>=1.2.0 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from stack-data->ipython->jupyterlab<4,>=3.5.0->jupyterlite[all]) (1.2.0)
Requirement already satisfied: asttokens>=2.1.0 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from stack-data->ipython->jupyterlab<4,>=3.5.0->jupyterlite[all]) (2.1.0)
Requirement already satisfied: pure-eval in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from stack-data->ipython->jupyterlab<4,>=3.5.0->jupyterlite[all]) (0.2.2)
Requirement already satisfied: pycparser in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from cffi>=1.0.1->argon2-cffi-bindings->argon2-cffi->jupyter_server->jupyterlite[all]) (2.21)

Installing collected packages: ipython-genutils, notebook-shim, nbclassic, notebook, jupyterlab

Successfully installed ipython-genutils-0.2.0 jupyterlab-3.5.0 nbclassic-0.4.8 notebook-6.5.2 notebook-shim-0.2.2

Quick Start#

Once installed, one can get to a locally-hosted, empty JupyterLite site with:

jupyter lite serve

This will:

  • init the baseline assets

  • build all extra assets

    • if a files/ folder is found, those will be copied into _output/files

      • … and indexed if jupyter_server is installed

  • serve the site locally and print out a URL

The Lite Dir#

When you run jupyter lite commands, it assumes your current working directory is the partial contents of a JupyterLite site. You can override this with --lite-dir. By default, the built site will be created in _output, but can be overridden with --output-dir.

Hide code cell content 
if "TMP_DIR" not in globals():
    TMP_DIR = pathlib.Path(tempfile.mkdtemp(prefix="_my_lite_dir_"))

    def clean():
        shutil.rmtree(TMP_DIR)

    atexit.register(clean)
os.chdir(TMP_DIR)
print(pathlib.Path.cwd())

/tmp/_my_lite_dir_3acidtx1

Well-known Files#

Some files in your --lite-dir that have special meaning:

look in path…

… for file named

… and if found

.
./lab
./retro

jupyter-lite.{json,ipynb}

merge with static in _output/{path}/jupyter-lite.{json,ipynb}

.
./lab
./retro

overrides.json

merge with static in _output/{*}/jupyter-lite.json

./files/

*

copy verbatim to _output/files/* and index in /api/contents

./pypi/

*.whl

copy verbatim to _output/pypi/* and index

./static/pyodide

pyodide.js, *.data, *.js

copy verbatim to _output/pyodide/*

See more about merging contents.

Usage#

Common Parameters#

parameter

description

default

environment variable

--lite-dir

configuration and content for the site

current working directory

JUPYTERLITE_DIR

--output-dir

where the hostable site will be created

_output

JUPYTERLITE_OUTPUT_DIR

--cache-dir

a cache directory for downloads

<lite_dir>/.cache

JUPYTERLITE_CACHE_DIR

--disable-addons

disable a specific addon by entrypoint name

--app-archive

an alternate site to base off of

bundled

--contents

directory to copy to _output/files/ and available as Contents

./files

--ignore-contents

patterns that should never be included in /files/ (even if found in lite-dir)

various

--extra-ignore-contents

additional patterns that should never be included in /files/ (even if found in lite-dir)

--output-archive

the path to the archive

<directory>-jupyterlite.tgz

JUPYTERLAB_OUTPUT_ARCHIVE

--port

port on 127.0.0.1 to serve the test server

8000

JUPYTERLITE_PORT

--base-url

the URL prefix to include before the site

/

JUPYTERLITE_BASE_URL

--source-date-epoch

optionally enable additional reproducible build measures (best-effort!)

SOURCE_DATE_EPOCH

--federated-extensions

paths to folders, pip/conda packages with extensions see note

--ignore-sys-prefix

don’t copy any contents, such as install labextensions, from sys.prefix

False

--settings-overrides

additional settings overrides to enable

--piplite-wheels

additional wheels to make available

--pyodide

the path or URL of a pyodide distribution (or .bz2 archive)

JUPYTERLITE_PYODIDE_URL

--mathjax-dir

the path to a MathJax 2 distribution

All parameters may be configured via a jupyter_lite_config.json in the directory where jupyter lite is launched, or given via --config.

Hint

For an advanced example, see the configuration used for this documentation.

Help#

The CLI provides its own documentation, under --help (or -h).

!jupyter lite --help
Hide code cell output 
A Jupyter Application

Subcommands
===========
Subcommands are launched as `jupyter cmd [args]`. For information on using
subcommand 'cmd', do: `jupyter cmd -h`.

list
    describe a JupyterLite site
status
    report about what a JupyterLite build _might_ do
init
    initialize a JupyterLite site from an app archive baseline
build
    build a JupyterLite site, including user content
check
    verify a JupyterLite site, using available schema and rules
serve
    serve a JupyterLite site, using best available HTTP server
archive
    build a JupyterLite app archive, which can be used as a baseline
doit
    use the full doit CLI, see https://pydoit.org/contents.html
pip
    tools for working with piplite

Options
=======
The options below are convenience aliases to configurable class-options,
as listed in the "Equivalent to" description-line of the aliases.
To see all configurable class-options for some <cmd>, use:
    <cmd> --help-all

--ignore-sys-prefix
    Do not copy anything from sys.prefix
    Equivalent to: [--LiteBuildConfig.ignore_sys_prefix=True]
--no-sourcemaps
    Strip all sourcemaps from applications and extensions
    Equivalent to: [--LiteBuildConfig.no_sourcemaps=True]
--no-unused-shared-packages
    Remove shared packages not used by --apps
    Equivalent to: [--LiteBuildConfig.no_unused_shared_packages=True]
--debug
    set log level to logging.DEBUG (maximize logging output)
    Equivalent to: [--Application.log_level=10]
-y
    Answer yes to any questions instead of prompting.
    Equivalent to: [--JupyterApp.answer_yes=True]
--log-level=<Enum>
    Set the log level by value or name.
    Choices: any of [0, 10, 20, 30, 40, 50, 'DEBUG', 'INFO', 'WARN', 'ERROR', 'CRITICAL']
    Default: 30
    Equivalent to: [--Application.log_level]
--config=<Unicode>
    Full path of a config file.
    Default: ''
    Equivalent to: [--JupyterApp.config_file]
--disable-addons=<typedtuple-item-1>...
    skip loading `entry_point` for these addons. TODO: should be a dict
    Default: ()
    Equivalent to: [--LiteBuildConfig.disable_addons]
--app-archive=<CPath>
    The app archive to use. env: JUPYTERLITE_APP_ARCHIVE
    Default: traitlets.Undefined
    Equivalent to: [--LiteBuildConfig.app_archive]
--apps=<typedtuple-item-1>...
    the Lite apps to explicitly include in build e.g. lab, retro, repl
    Default: ()
    Equivalent to: [--LiteBuildConfig.apps]
--lite-dir=<CPath>
    The root folder of a JupyterLite project. env: JUPYTERLITE_DIR
    Default: traitlets.Undefined
    Equivalent to: [--LiteBuildConfig.lite_dir]
--contents=<typedtuple-item-1>...
    Contents to add and index
    Default: ()
    Equivalent to: [--LiteBuildConfig.contents]
--ignore-contents=<tuple-item-1>...
    Path regular expressions that should never be included as contents
    Default: ()
    Equivalent to: [--LiteBuildConfig.ignore_contents]
--extra-ignore-contents=<tuple-item-1>...
    Additional path regular expressions that should never be included as
    contents
    Default: ()
    Equivalent to: [--LiteBuildConfig.extra_ignore_contents]
--settings-overrides=<typedtuple-item-1>...
    Specific overrides.json to include
    Default: ()
    Equivalent to: [--LiteBuildConfig.settings_overrides]
--mathjax-dir=<CPath>
    A local path to a complete/sufficient installation of MathJax 2
    Default: traitlets.Undefined
    Equivalent to: [--LiteBuildConfig.mathjax_dir]
--output-dir=<CPath>
    Where to build the JupyterLite site. env: JUPYTERLITE_OUTPUT_DIR
    Default: traitlets.Undefined
    Equivalent to: [--LiteBuildConfig.output_dir]
--output-archive=<CPath>
    Archive to create. env: JUPYTERLITE_OUTPUT_ARCHIVE
    Default: traitlets.Undefined
    Equivalent to: [--LiteBuildConfig.output_archive]
--source-date-epoch=<CInt>
    Trigger reproducible builds, clamping timestamps to this value
    Default: 0
    Equivalent to: [--LiteBuildConfig.source_date_epoch]
--port=<CInt>
    [serve] the port to (insecurely) expose on http://127.0.0.1. env:
    JUPYTERLITE_PORT
    Default: 0
    Equivalent to: [--LiteBuildConfig.port]
--base-url=<Unicode>
    [serve] the prefix to use. env: JUPYTERLITE_BASE_URL
    Default: ''
    Equivalent to: [--LiteBuildConfig.base_url]
--piplite-wheels=<typedtuple-item-1>...
    Local paths or URLs of piplite-compatible wheels to copy and index
    Default: ()
    Equivalent to: [--LiteBuildConfig.piplite_urls]
--pyodide=<Unicode>
    Local path or URL of a pyodide distribution tarball
    Default: ''
    Equivalent to: [--LiteBuildConfig.pyodide_url]

To see all available configurables, use `--help-all`.

Status#

Always safe to run, this command provides an overview of what JupyterLite has been doing.

!jupyter lite status
Hide code cell output 
static:jupyter-lite.json
.  pre_status:static:jupyter-lite.json
    tarball:         jupyterlite-app-0.1.0-beta.14.tgz 8MB
    output:          /tmp/_my_lite_dir_3acidtx1/_output
    lite dir:        /tmp/_my_lite_dir_3acidtx1
    apps:            
    sourcemaps:      True
    unused packages: True
archive:archive
contents:contents
lite:jupyter-lite.json
mathjax:status
mimetypes:jupyter-lite.json
pyodide:pyodide
serve:contents
settings:overrides
translation:translation
.  status:archive:archive
[LiteStatusApp] No archive (yet): _my_lite_dir_3acidtx1-jupyterlite.tgz
.  status:contents:contents
    contents: 0 files
.  status:lite:jupyter-lite.json
[LiteStatusApp]     jupyter-lite.(json|ipynb): 0 files
.  status:mathjax:status
     jupyter-server-mathjax: /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages/jupyter_server_mathjax/static 
     configured MathJax dir: /tmp/_my_lite_dir_3acidtx1/traitlets.Undefined
     effective MathJax dir: /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages/jupyter_server_mathjax/static
.  status:mimetypes:jupyter-lite.json
    filetypes:         26 
.  status:pyodide:pyodide
     URL: None
 archive: []
   cache: 0 files
   local: 0 files
.  status:serve:contents
    url: http://127.0.0.1:8000/
    server: tornado
    headers:
.  status:settings:overrides
    overrides.json: 0
.  status:translation:translation
    translation files: 0 files

List#

Always safe to run, this command provides an overview of what JupyterLite might do.

TODO: improve on default output

!jupyter lite list
Hide code cell output 
static:jupyter-lite.json
archive:archive
contents:contents
lite:jupyter-lite.json
mathjax:status
mimetypes:jupyter-lite.json
pyodide:pyodide
serve:contents
settings:overrides
translation:translation
static:output_dir
static:unpack

federated_extensions:copy:ext:jupyterlab_pygments
mathjax:copy

translation:copy
federated_extensions:patch
mathjax:patch
mimetypes:patch
mathjax:config
pyodide:config
serve:tornado
report:SHA256SUMS
archive:archive:_my_lite_dir_3acidtx1-jupyterlite.tgz
R archive                                                         
R archive:archive:archive:_my_lite_dir_3acidtx1-jupyterlite.tgz   generate a new app archive
R build                                                           
R build:mathjax:copy                                              copy MathJax into the output dir
R build:translation:copy                                          create the translation data
R check                                                           
E check:mathjax:config                                            
E check:pyodide:config                                            
R init                                                            
R init:static:unpack                                              unpack a 'gold master' JupyterLite from jupyterlite-app-0.1.0-beta.14.tgz
R post_archive                                                    
R post_build                                                      
E post_build:federated_extensions:patch                           ensure jupyter-lite.json includes the federated_extensions
E post_build:mathjax:patch                                        ensure jupyter-lite.json includes the mathjax url
R post_build:mimetypes:patch                                      ensure /tmp/_my_lite_dir_3acidtx1/_output/jupyter-lite.json includes the file_types
R post_check                                                      
R post_init                                                       
R post_serve                                                      
R post_status                                                     
R pre_archive                                                     
R pre_archive:report:SHA256SUMS                                   hash all of the files
R pre_build                                                       
R pre_build:federated_extensions:copy:ext:jupyterlab_pygments     
R pre_check                                                       
R pre_init                                                        
R pre_init:static:output_dir                                      clean out the lite directory
R pre_serve                                                       
R pre_status                                                      
R pre_status:static:jupyter-lite.json                             
R serve                                                           
R serve:serve:tornado                                             run server at http://127.0.0.1:8000/ for /tmp/_my_lite_dir_3acidtx1/_output
R status                                                          
R status:archive:archive                                          
R status:contents:contents                                        
R status:lite:jupyter-lite.json                                   
R status:mathjax:status                                           Get information about offline MathJax
R status:mimetypes:jupyter-lite.json                              
R status:pyodide:pyodide                                          
R status:serve:contents                                           
R status:settings:overrides                                       
R status:translation:translation

Init#

Copy all the static data to the --output-dir.

!jupyter lite init
Hide code cell output 
static:jupyter-lite.json
.  pre_status:static:jupyter-lite.json

    tarball:         jupyterlite-app-0.1.0-beta.14.tgz 8MB
    output:          /tmp/_my_lite_dir_3acidtx1/_output
    lite dir:        /tmp/_my_lite_dir_3acidtx1
    apps:            
    sourcemaps:      True
    unused packages: True
archive:archive
contents:contents
lite:jupyter-lite.json
mathjax:status
mimetypes:jupyter-lite.json
pyodide:pyodide
serve:contents
settings:overrides
translation:translation
.  status:archive:archive
[LiteInitApp] No archive (yet): _my_lite_dir_3acidtx1-jupyterlite.tgz
.  status:contents:contents
    contents: 0 files
.  status:lite:jupyter-lite.json
[LiteInitApp]     jupyter-lite.(json|ipynb): 0 files
.  status:mathjax:status
     jupyter-server-mathjax: /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages/jupyter_server_mathjax/static 
     configured MathJax dir: /tmp/_my_lite_dir_3acidtx1/traitlets.Undefined
     effective MathJax dir: /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages/jupyter_server_mathjax/static
.  status:mimetypes:jupyter-lite.json
    filetypes:         26 
.  status:pyodide:pyodide
     URL: None
 archive: []
   cache: 0 files
   local: 0 files
.  status:serve:contents
    url: http://127.0.0.1:8000/
    server: tornado
    headers:
.  status:settings:overrides
    overrides.json: 0
.  status:translation:translation
    translation files: 0 files
static:output_dir
.  pre_init:static:output_dir
static:unpack
.  init:static:unpack

Build#

Copy all the user-authored content to the --output-dir, and applies appropriate changes to e.g. generated Contents API responses.

Special well-known files will be merged appropriately, but generally, files that exist in the user directory will overwrite any existing content.

!jupyter lite build
Hide code cell output 
static:jupyter-lite.json
.  pre_status:static:jupyter-lite.json
    tarball:         jupyterlite-app-0.1.0-beta.14.tgz 8MB
    output:          /tmp/_my_lite_dir_3acidtx1/_output
    lite dir:        /tmp/_my_lite_dir_3acidtx1
    apps:            
    sourcemaps:      True
    unused packages: True
archive:archive
contents:contents
lite:jupyter-lite.json
mathjax:status
mimetypes:jupyter-lite.json
pyodide:pyodide
serve:contents
settings:overrides
translation:translation
.  status:archive:archive
[LiteBuildApp] No archive (yet): _my_lite_dir_3acidtx1-jupyterlite.tgz
.  status:contents:contents
    contents: 0 files
.  status:lite:jupyter-lite.json

[LiteBuildApp]     jupyter-lite.(json|ipynb): 0 files
.  status:mathjax:status
     jupyter-server-mathjax: /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages/jupyter_server_mathjax/static 
     configured MathJax dir: /tmp/_my_lite_dir_3acidtx1/traitlets.Undefined
     effective MathJax dir: /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages/jupyter_server_mathjax/static
.  status:mimetypes:jupyter-lite.json
    filetypes:         26 
.  status:pyodide:pyodide
     URL: None
 archive: []
   cache: 0 files
   local: 0 files
.  status:serve:contents
    url: http://127.0.0.1:8000/
    server: tornado
    headers:
.  status:settings:overrides
    overrides.json: 0
.  status:translation:translation
    translation files: 0 files
static:output_dir
-- pre_init:static:output_dir
static:unpack
-- init:static:unpack

federated_extensions:copy:ext:jupyterlab_pygments
.  pre_build:federated_extensions:copy:ext:jupyterlab_pygments

mathjax:copy

translation:copy
.  build:mathjax:copy

.  build:translation:copy
federated_extensions:patch
mathjax:patch
mimetypes:patch
.  post_build:federated_extensions:patch
.  post_build:mathjax:patch
.  post_build:mimetypes:patch

Serve#

Serve the --output-dir on http://127.0.0.1:{--port=8000}{--base-url=/}.

Warning

This is not a production server. Please consider any of the deployment options before trying to make this something it isn’t.

!jupyter lite serve --help
Hide code cell output 
A Jupyter Application

Options
=======
The options below are convenience aliases to configurable class-options,
as listed in the "Equivalent to" description-line of the aliases.
To see all configurable class-options for some <cmd>, use:
    <cmd> --help-all

--ignore-sys-prefix
    Do not copy anything from sys.prefix
    Equivalent to: [--LiteBuildConfig.ignore_sys_prefix=True]
--no-sourcemaps
    Strip all sourcemaps from applications and extensions
    Equivalent to: [--LiteBuildConfig.no_sourcemaps=True]
--no-unused-shared-packages
    Remove shared packages not used by --apps
    Equivalent to: [--LiteBuildConfig.no_unused_shared_packages=True]
--debug
    set log level to logging.DEBUG (maximize logging output)
    Equivalent to: [--Application.log_level=10]
-y
    Answer yes to any questions instead of prompting.
    Equivalent to: [--JupyterApp.answer_yes=True]
--force
    forget previous runs of task and re-run from the beginning
    Equivalent to: [--LiteTaskApp.force=True]
--log-level=<Enum>
    Set the log level by value or name.
    Choices: any of [0, 10, 20, 30, 40, 50, 'DEBUG', 'INFO', 'WARN', 'ERROR', 'CRITICAL']
    Default: 30
    Equivalent to: [--Application.log_level]
--config=<Unicode>
    Full path of a config file.
    Default: ''
    Equivalent to: [--JupyterApp.config_file]
--disable-addons=<typedtuple-item-1>...
    skip loading `entry_point` for these addons. TODO: should be a dict
    Default: ()
    Equivalent to: [--LiteBuildConfig.disable_addons]
--app-archive=<CPath>
    The app archive to use. env: JUPYTERLITE_APP_ARCHIVE
    Default: traitlets.Undefined
    Equivalent to: [--LiteBuildConfig.app_archive]
--apps=<typedtuple-item-1>...
    the Lite apps to explicitly include in build e.g. lab, retro, repl
    Default: ()
    Equivalent to: [--LiteBuildConfig.apps]
--lite-dir=<CPath>
    The root folder of a JupyterLite project. env: JUPYTERLITE_DIR
    Default: traitlets.Undefined
    Equivalent to: [--LiteBuildConfig.lite_dir]
--contents=<typedtuple-item-1>...
    Contents to add and index
    Default: ()
    Equivalent to: [--LiteBuildConfig.contents]
--ignore-contents=<tuple-item-1>...
    Path regular expressions that should never be included as contents
    Default: ()
    Equivalent to: [--LiteBuildConfig.ignore_contents]
--extra-ignore-contents=<tuple-item-1>...
    Additional path regular expressions that should never be included as
    contents
    Default: ()
    Equivalent to: [--LiteBuildConfig.extra_ignore_contents]
--settings-overrides=<typedtuple-item-1>...
    Specific overrides.json to include
    Default: ()
    Equivalent to: [--LiteBuildConfig.settings_overrides]
--mathjax-dir=<CPath>
    A local path to a complete/sufficient installation of MathJax 2
    Default: traitlets.Undefined
    Equivalent to: [--LiteBuildConfig.mathjax_dir]
--output-dir=<CPath>
    Where to build the JupyterLite site. env: JUPYTERLITE_OUTPUT_DIR
    Default: traitlets.Undefined
    Equivalent to: [--LiteBuildConfig.output_dir]
--output-archive=<CPath>
    Archive to create. env: JUPYTERLITE_OUTPUT_ARCHIVE
    Default: traitlets.Undefined
    Equivalent to: [--LiteBuildConfig.output_archive]
--source-date-epoch=<CInt>
    Trigger reproducible builds, clamping timestamps to this value
    Default: 0
    Equivalent to: [--LiteBuildConfig.source_date_epoch]
--port=<CInt>
    [serve] the port to (insecurely) expose on http://127.0.0.1. env:
    JUPYTERLITE_PORT
    Default: 0
    Equivalent to: [--LiteBuildConfig.port]
--base-url=<Unicode>
    [serve] the prefix to use. env: JUPYTERLITE_BASE_URL
    Default: ''
    Equivalent to: [--LiteBuildConfig.base_url]
--piplite-wheels=<typedtuple-item-1>...
    Local paths or URLs of piplite-compatible wheels to copy and index
    Default: ()
    Equivalent to: [--LiteBuildConfig.piplite_urls]
--pyodide=<Unicode>
    Local path or URL of a pyodide distribution tarball
    Default: ''
    Equivalent to: [--LiteBuildConfig.pyodide_url]

To see all available configurables, use `--help-all`.

HTTP headers#

When working locally, it can be convenient to emulate HTTP headers that would match how a site would work when deployed. As these get rather complicated, the following options are configurable, but only affect jupyter lite serve, such as emulating a “permissive” host with extra_http_headers (which extend the default headers) or http_headers (replacing any default headers):

{
  "LiteBuildConfig": {
    "http_headers": {
      "Access-Control-Allow-Headers": "x-requested-with",
      "Access-Control-Allow-Methods": "POST, GET, OPTIONS",
      "Access-Control-Allow-Origin": "*"
    }
  }
}

Check#

Use all available mechanisms to verify that the build folder conforms to schema, etc.

!jupyter lite check
Hide code cell output 
static:jupyter-lite.json

.  pre_status:static:jupyter-lite.json
    tarball:         jupyterlite-app-0.1.0-beta.14.tgz 8MB
    output:          /tmp/_my_lite_dir_3acidtx1/_output
    lite dir:        /tmp/_my_lite_dir_3acidtx1
    apps:            
    sourcemaps:      True
    unused packages: True
archive:archive
contents:contents
lite:jupyter-lite.json
mathjax:status
mimetypes:jupyter-lite.json
pyodide:pyodide
serve:contents
settings:overrides
translation:translation
.  status:archive:archive
[LiteCheckApp] No archive (yet): _my_lite_dir_3acidtx1-jupyterlite.tgz
.  status:contents:contents
    contents: 0 files
.  status:lite:jupyter-lite.json
[LiteCheckApp]     jupyter-lite.(json|ipynb): 0 files
.  status:mathjax:status
     jupyter-server-mathjax: /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages/jupyter_server_mathjax/static 
     configured MathJax dir: /tmp/_my_lite_dir_3acidtx1/traitlets.Undefined
     effective MathJax dir: /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages/jupyter_server_mathjax/static
.  status:mimetypes:jupyter-lite.json
    filetypes:         26 
.  status:pyodide:pyodide
     URL: None
 archive: []
   cache: 0 files
   local: 0 files
.  status:serve:contents
    url: http://127.0.0.1:8000/
    server: tornado
    headers:
.  status:settings:overrides
    overrides.json: 0
.  status:translation:translation
    translation files: 4 files
static:output_dir
-- pre_init:static:output_dir
static:unpack
-- init:static:unpack

federated_extensions:copy:ext:jupyterlab_pygments
-- pre_build:federated_extensions:copy:ext:jupyterlab_pygments
mathjax:copy

translation:copy
-- build:mathjax:copy
-- build:translation:copy
federated_extensions:patch
mathjax:patch
mimetypes:patch
-- post_build:federated_extensions:patch
-- post_build:mathjax:patch
-- post_build:mimetypes:patch
lite:validate:jupyter-lite.json
lite:validate:lab/jupyter-lite.json
lite:validate:retro/jupyter-lite.json
lite:validate:retro/edit/jupyter-lite.json
lite:validate:retro/tree/jupyter-lite.json
lite:validate:retro/notebooks/jupyter-lite.json
lite:validate:retro/consoles/jupyter-lite.json
lite:validate:repl/jupyter-lite.json
lite:validate:jupyter-lite.ipynb
lite:validate:lab/jupyter-lite.ipynb
lite:validate:retro/jupyter-lite.ipynb
lite:validate:retro/edit/jupyter-lite.ipynb
lite:validate:retro/tree/jupyter-lite.ipynb
lite:validate:retro/notebooks/jupyter-lite.ipynb
lite:validate:retro/consoles/jupyter-lite.ipynb
lite:validate:repl/jupyter-lite.ipynb
mathjax:config
pyodide:config

translation:validate:translation:all.json
.  check:lite:validate:jupyter-lite.json
.  check:lite:validate:lab/jupyter-lite.json
.  check:lite:validate:retro/jupyter-lite.json
.  check:lite:validate:retro/edit/jupyter-lite.json
.  check:lite:validate:retro/tree/jupyter-lite.json
.  check:lite:validate:retro/notebooks/jupyter-lite.json
.  check:lite:validate:retro/consoles/jupyter-lite.json
.  check:lite:validate:repl/jupyter-lite.json
.  check:lite:validate:jupyter-lite.ipynb
.  check:lite:validate:lab/jupyter-lite.ipynb
.  check:lite:validate:retro/jupyter-lite.ipynb
.  check:lite:validate:retro/edit/jupyter-lite.ipynb
.  check:lite:validate:retro/tree/jupyter-lite.ipynb
.  check:lite:validate:retro/notebooks/jupyter-lite.ipynb
.  check:lite:validate:retro/consoles/jupyter-lite.ipynb
.  check:lite:validate:repl/jupyter-lite.ipynb
.  check:mathjax:config
.  check:pyodide:config
.  check:translation:validate:translation:all.json

Archive#

Turn the output directory into a .tgz file. This is usually easier to move around than (sometimes) hundreds of files, and can be used as the baseline for future sites.

This command is relatively expensive, and is skipped for documentation purposes

!jupyter lite archive --help
if not RTD:
    !jupyter lite archive
Hide code cell output 
A Jupyter Application

Options
=======
The options below are convenience aliases to configurable class-options,
as listed in the "Equivalent to" description-line of the aliases.
To see all configurable class-options for some <cmd>, use:
    <cmd> --help-all

--ignore-sys-prefix
    Do not copy anything from sys.prefix
    Equivalent to: [--LiteBuildConfig.ignore_sys_prefix=True]
--no-sourcemaps
    Strip all sourcemaps from applications and extensions
    Equivalent to: [--LiteBuildConfig.no_sourcemaps=True]
--no-unused-shared-packages
    Remove shared packages not used by --apps
    Equivalent to: [--LiteBuildConfig.no_unused_shared_packages=True]
--debug
    set log level to logging.DEBUG (maximize logging output)
    Equivalent to: [--Application.log_level=10]
-y
    Answer yes to any questions instead of prompting.
    Equivalent to: [--JupyterApp.answer_yes=True]
--force
    forget previous runs of task and re-run from the beginning
    Equivalent to: [--LiteTaskApp.force=True]
--log-level=<Enum>
    Set the log level by value or name.
    Choices: any of [0, 10, 20, 30, 40, 50, 'DEBUG', 'INFO', 'WARN', 'ERROR', 'CRITICAL']
    Default: 30
    Equivalent to: [--Application.log_level]
--config=<Unicode>
    Full path of a config file.
    Default: ''
    Equivalent to: [--JupyterApp.config_file]
--disable-addons=<typedtuple-item-1>...
    skip loading `entry_point` for these addons. TODO: should be a dict
    Default: ()
    Equivalent to: [--LiteBuildConfig.disable_addons]
--app-archive=<CPath>
    The app archive to use. env: JUPYTERLITE_APP_ARCHIVE
    Default: traitlets.Undefined
    Equivalent to: [--LiteBuildConfig.app_archive]
--apps=<typedtuple-item-1>...
    the Lite apps to explicitly include in build e.g. lab, retro, repl
    Default: ()
    Equivalent to: [--LiteBuildConfig.apps]
--lite-dir=<CPath>
    The root folder of a JupyterLite project. env: JUPYTERLITE_DIR
    Default: traitlets.Undefined
    Equivalent to: [--LiteBuildConfig.lite_dir]
--contents=<typedtuple-item-1>...
    Contents to add and index
    Default: ()
    Equivalent to: [--LiteBuildConfig.contents]
--ignore-contents=<tuple-item-1>...
    Path regular expressions that should never be included as contents
    Default: ()
    Equivalent to: [--LiteBuildConfig.ignore_contents]
--extra-ignore-contents=<tuple-item-1>...
    Additional path regular expressions that should never be included as
    contents
    Default: ()
    Equivalent to: [--LiteBuildConfig.extra_ignore_contents]
--settings-overrides=<typedtuple-item-1>...
    Specific overrides.json to include
    Default: ()
    Equivalent to: [--LiteBuildConfig.settings_overrides]
--mathjax-dir=<CPath>
    A local path to a complete/sufficient installation of MathJax 2
    Default: traitlets.Undefined
    Equivalent to: [--LiteBuildConfig.mathjax_dir]
--output-dir=<CPath>
    Where to build the JupyterLite site. env: JUPYTERLITE_OUTPUT_DIR
    Default: traitlets.Undefined
    Equivalent to: [--LiteBuildConfig.output_dir]
--output-archive=<CPath>
    Archive to create. env: JUPYTERLITE_OUTPUT_ARCHIVE
    Default: traitlets.Undefined
    Equivalent to: [--LiteBuildConfig.output_archive]
--source-date-epoch=<CInt>
    Trigger reproducible builds, clamping timestamps to this value
    Default: 0
    Equivalent to: [--LiteBuildConfig.source_date_epoch]
--port=<CInt>
    [serve] the port to (insecurely) expose on http://127.0.0.1. env:
    JUPYTERLITE_PORT
    Default: 0
    Equivalent to: [--LiteBuildConfig.port]
--base-url=<Unicode>
    [serve] the prefix to use. env: JUPYTERLITE_BASE_URL
    Default: ''
    Equivalent to: [--LiteBuildConfig.base_url]
--piplite-wheels=<typedtuple-item-1>...
    Local paths or URLs of piplite-compatible wheels to copy and index
    Default: ()
    Equivalent to: [--LiteBuildConfig.piplite_urls]
--pyodide=<Unicode>
    Local path or URL of a pyodide distribution tarball
    Default: ''
    Equivalent to: [--LiteBuildConfig.pyodide_url]

To see all available configurables, use `--help-all`.

But let’s talk about a more reproducible asset.

Hide code cell content 
# we clean out the TMP_DIR for the reproducibility examples
shutil.rmtree(TMP_DIR / "_output", ignore_errors=True)

Reproducible Archives#

🛠️ This feature is a work-in-progress, and should not be relied upon by any production workflows Just Yet.

If --source-date-epoch is given, a number of measures will be taken to try to ensure that the output of jupyter lite archive, an npm-compatible tgz package, always returns a bit-for-bit reproducible build.

The most obvious change is that the modified time of each file “clamped” to that time. Some other changes:

  • file ownership will be reset

  • predictable sorting will be used

  • additional checks will be applied

Note

This is a shortcut for setting the environment variable SOURCE_DATE_EPOCH:

platform

command

Linux
MacOS

export SOURCE_DATE_EPOCH=<a timestamp>

Windows

set SOURCE_DATE_EPOCH=<a timestamp>

Python

os.environ.update(SOURCE_DATE_EPOCH, <a timestamp>)
Hide code cell source 
if not "source_date_epoch" in globals():
    from datetime import datetime

    source_date_epoch = int(datetime.utcnow().timestamp())

print("SOURCE_DATE_EPOCH is", source_date_epoch)

SOURCE_DATE_EPOCH is 1668693223

if not RTD:
    !jupyter lite archive --source-date-epoch {source_date_epoch} --output-archive ./a.tgz

If we clear out our _output…

Hide code cell source 
if not RTD:
    shutil.rmtree(TMP_DIR / "_output", ignore_errors=True)
    pprint.pprint([*TMP_DIR.rglob("*")])

…and rebuild, we should always get the same file.

if not RTD:
    !jupyter lite archive --source-date-epoch {source_date_epoch} --output-archive ./b.tgz
Hide code cell source 
if not RTD:
    a, b = [
        hashlib.sha256((TMP_DIR / f"{x}.tgz").read_bytes()).hexdigest() for x in "ab"
    ]
    print("We built app archives with the SHA256SUMS of:\n", a, "\n", b)
    try:
        assert a == b, "We did not reproducibly build today.\n- {}\n- {}\n\n".format(
            a, b
        )
    except AssertionError as err:
        if shutil.which("diffoscope"):
            print(
                "We did NOT reproducibly build today, checking in with `diffoscope`..."
            )
            !diffoscope a.tgz b.tgz
        print("...but at least we tried REALLY hard!\n")

Miscellaneous#

Merging Contents#

In addition to the default files/ path, provide additional files to show in the File Manager or Tree when JupyterLite launches with --contents, which can be provided multiple times.

Note

  • If --contents is provided, the default value of --contents files will be ignored

  • If given multiple times, and child folder/file names would collide, the last path wins

Hint

For complex file layouts, a jupyter_lite_config.json is highly recommended.

Contents Example#

Given a directory like:

my-lite-dir/
  files/
    README.md
    a.md
  more-files/
    README.md
    b.md

Running jupyter lite build without any arguments will yield:

my-lite-dir/
  _output/
    README.md
    b.md

Whereas jupyter lite build --contents more-files --contents files will yield:

my-lite-dir/
  _output/
    files/
      README.md # this will be from my-lite-dir/files
      a.md
      b.md

And jupyter lite build --contents files --contents more-files will yield:

my-lite-dir/
  _output/
    files/
      README.md # this will be from my-lite-dir/more-files
      a.md
      b.md

conda packages#

While --federated-extensions support the .tar.bz2 created by most conda packages, there are some issues:

  • anaconda.org uses non-standard HTTP headers to S3 buckets to provide packages

  • the conda-forge channel provides all of its builds as GitHub releases, and can be predictably transformed, e.g.

https://anaconda.org/conda-forge/jupyterlab_widgets/1.0.0/download/noarch/jupyterlab_widgets-1.0.0-pyhd8ed1ab_1.tar.bz2
                                                                   |      |
                                                                   |      +---------------------------------------------+
                                                                   v      v                                             v
         https://conda.anaconda.org/conda-forge/noarch/jupyterlab_widgets-1.0.0-pyhd8ed1ab_1.tar.bz2

pyolite wheels#

Prebuilt Lab Extension developers who wish to include wheels for use with pyolite may use this command to pre-index wheels they wish to distribute. This can be useful if a package needs upstream patches, etc.

!jupyter lite pip index --help
Hide code cell output 
index a directory of wheels for piplite into an all.json

Options
=======
The options below are convenience aliases to configurable class-options,
as listed in the "Equivalent to" description-line of the aliases.
To see all configurable class-options for some <cmd>, use:
    <cmd> --help-all

--debug
    set log level to logging.DEBUG (maximize logging output)
    Equivalent to: [--Application.log_level=10]
--show-config
    Show the application's configuration (human-readable format)
    Equivalent to: [--Application.show_config=True]
--show-config-json
    Show the application's configuration (json format)
    Equivalent to: [--Application.show_config_json=True]
--generate-config
    generate default config file
    Equivalent to: [--JupyterApp.generate_config=True]
-y
    Answer yes to any questions instead of prompting.
    Equivalent to: [--JupyterApp.answer_yes=True]
--log-level=<Enum>
    Set the log level by value or name.
    Choices: any of [0, 10, 20, 30, 40, 50, 'DEBUG', 'INFO', 'WARN', 'ERROR', 'CRITICAL']
    Default: 30
    Equivalent to: [--Application.log_level]
--config=<Unicode>
    Full path of a config file.
    Default: ''
    Equivalent to: [--JupyterApp.config_file]

To see all available configurables, use `--help-all`.

pyodide#

Pyodide is a WebAssembly distribution of CPython and powers the pyolite kernel. At nearly 200mb, compressed, a full pyodide distribution includes both the Python interpreter and key anchor packages from the scientific computing stack. Parts of it are fetched as needed by the user’s browser, by default, from the official pyodide CDN.

The --pyodide CLI option (or alternately pyodide_url config option or JUPYTERLITE_PYODIDE_URL environment variable) allows for fetching either a compressed pyodide .bz2, or folder containing such an archive’s contents. This might be from the official pyodide release page, a nightly or PR asset, or otherwise customized build. Once fetched, it is copied to the output folder, and configured.

$\LaTeX$#

If jupyter-server-mathjax is installed, the MathJax 2 assets it provides will be copied and configured during the build. This behavior can be:

  • disabled with --ignore-sys-prefix or --disable-addons mathjax, defaulting to fetching the assets from CDN.

  • overridden with --mathjax-dir <path>, which must be a full folder of a MathJax 2 distribution