CLI#
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.9/site-packages (0.1.0b10)
Requirement already satisfied: doit in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from jupyterlite) (0.33.1)
Requirement already satisfied: entrypoints in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from jupyterlite) (0.4)
Requirement already satisfied: jupyter_core>=4.7 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from jupyterlite) (4.10.0)
Requirement already satisfied: traitlets in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from jupyter_core>=4.7->jupyterlite) (5.3.0)
Requirement already satisfied: pyinotify in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from doit->jupyterlite) (0.9.6)
Requirement already satisfied: cloudpickle in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from doit->jupyterlite) (2.1.0)
0.1.0b10
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]
Requirement already satisfied: jupyterlite[all] in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (0.1.0b10)
Requirement already satisfied: jupyter_core>=4.7 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from jupyterlite[all]) (4.10.0)
Requirement already satisfied: doit in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from jupyterlite[all]) (0.33.1)
Requirement already satisfied: entrypoints in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from jupyterlite[all]) (0.4)
Collecting jupyterlab<4,>=3.0
Downloading jupyterlab-3.4.3-py3-none-any.whl (8.8 MB)
?25l 0.0/8.8 MB ? eta -:--:--
━ 0.3/8.8 MB 9.3 MB/s eta 0:00:01
━━━━━━━━━━━ 2.4/8.8 MB 35.5 MB/s eta 0:00:01
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 7.1/8.8 MB 68.0 MB/s eta 0:00:01
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╸ 8.7/8.8 MB 75.7 MB/s eta 0:00:01
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 8.8/8.8 MB 56.3 MB/s eta 0:00:00
?25h
Requirement already satisfied: jupyterlab_server<3,>=2.8.1 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from jupyterlite[all]) (2.14.0)
Requirement already satisfied: jupyter-server-mathjax>=0.2.3 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from jupyterlite[all]) (0.2.5)
Requirement already satisfied: tornado>=6.1 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from jupyterlite[all]) (6.1)
Requirement already satisfied: pkginfo in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from jupyterlite[all]) (1.8.3)
Requirement already satisfied: jupyter_server in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from jupyterlite[all]) (1.18.0)
Requirement already satisfied: jsonschema>=3 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from jupyterlite[all]) (4.6.1)
Requirement already satisfied: attrs>=17.4.0 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from jsonschema>=3->jupyterlite[all]) (21.4.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.9/site-packages (from jsonschema>=3->jupyterlite[all]) (0.18.1)
Requirement already satisfied: traitlets in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from jupyter_core>=4.7->jupyterlite[all]) (5.3.0)
Requirement already satisfied: anyio<4,>=3.1.0 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from jupyter_server->jupyterlite[all]) (3.6.1)
Requirement already satisfied: jinja2 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/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.9/site-packages (from jupyter_server->jupyterlite[all]) (0.14.1)
Requirement already satisfied: nbformat>=5.2.0 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from jupyter_server->jupyterlite[all]) (5.4.0)
Requirement already satisfied: jupyter-client>=6.1.12 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from jupyter_server->jupyterlite[all]) (7.3.4)
Requirement already satisfied: terminado>=0.8.3 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from jupyter_server->jupyterlite[all]) (0.15.0)
Requirement already satisfied: packaging in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from jupyter_server->jupyterlite[all]) (21.3)
Requirement already satisfied: pyzmq>=17 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from jupyter_server->jupyterlite[all]) (23.2.0)
Requirement already satisfied: Send2Trash in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from jupyter_server->jupyterlite[all]) (1.8.0)
Requirement already satisfied: websocket-client in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from jupyter_server->jupyterlite[all]) (1.3.3)
Requirement already satisfied: nbconvert>=6.4.4 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from jupyter_server->jupyterlite[all]) (6.5.0)
Requirement already satisfied: argon2-cffi in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from jupyter_server->jupyterlite[all]) (21.3.0)
Collecting nbclassic~=0.2
Downloading nbclassic-0.3.7-py3-none-any.whl (13 kB)
Requirement already satisfied: ipython in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from jupyterlab<4,>=3.0->jupyterlite[all]) (8.4.0)
Requirement already satisfied: importlib-metadata>=3.6 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from jupyterlab_server<3,>=2.8.1->jupyterlite[all]) (4.11.4)
Requirement already satisfied: requests in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/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.9/site-packages (from jupyterlab_server<3,>=2.8.1->jupyterlite[all]) (2.10.3)
Requirement already satisfied: json5 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from jupyterlab_server<3,>=2.8.1->jupyterlite[all]) (0.9.5)
Requirement already satisfied: cloudpickle in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from doit->jupyterlite[all]) (2.1.0)
Requirement already satisfied: pyinotify in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from doit->jupyterlite[all]) (0.9.6)
Requirement already satisfied: sniffio>=1.1 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from anyio<4,>=3.1.0->jupyter_server->jupyterlite[all]) (1.2.0)
Requirement already satisfied: idna>=2.8 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from anyio<4,>=3.1.0->jupyter_server->jupyterlite[all]) (3.3)
Requirement already satisfied: zipp>=0.5 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from importlib-metadata>=3.6->jupyterlab_server<3,>=2.8.1->jupyterlite[all]) (3.8.0)
Requirement already satisfied: MarkupSafe>=2.0 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from jinja2->jupyter_server->jupyterlite[all]) (2.1.1)
Requirement already satisfied: nest-asyncio>=1.5.4 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from jupyter-client>=6.1.12->jupyter_server->jupyterlite[all]) (1.5.5)
Requirement already satisfied: python-dateutil>=2.8.2 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from jupyter-client>=6.1.12->jupyter_server->jupyterlite[all]) (2.8.2)
Collecting notebook<7
Downloading notebook-6.4.12-py3-none-any.whl (9.9 MB)
?25l 0.0/9.9 MB ? eta -:--:--
━━━━━━━━━━━━━━━━━ 4.3/9.9 MB 131.1 MB/s eta 0:00:01
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 8.9/9.9 MB 129.9 MB/s eta 0:00:01
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╸ 9.9/9.9 MB 132.4 MB/s eta 0:00:01
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 9.9/9.9 MB 84.3 MB/s eta 0:00:00
?25h
Collecting notebook-shim>=0.1.0
Downloading notebook_shim-0.1.0-py3-none-any.whl (13 kB)
Requirement already satisfied: bleach in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from nbconvert>=6.4.4->jupyter_server->jupyterlite[all]) (5.0.1)
Requirement already satisfied: pandocfilters>=1.4.1 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from nbconvert>=6.4.4->jupyter_server->jupyterlite[all]) (1.5.0)
Requirement already satisfied: mistune<2,>=0.8.1 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from nbconvert>=6.4.4->jupyter_server->jupyterlite[all]) (0.8.4)
Requirement already satisfied: nbclient>=0.5.0 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from nbconvert>=6.4.4->jupyter_server->jupyterlite[all]) (0.5.13)
Requirement already satisfied: tinycss2 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from nbconvert>=6.4.4->jupyter_server->jupyterlite[all]) (1.1.1)
Requirement already satisfied: pygments>=2.4.1 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from nbconvert>=6.4.4->jupyter_server->jupyterlite[all]) (2.12.0)
Requirement already satisfied: jupyterlab-pygments in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from nbconvert>=6.4.4->jupyter_server->jupyterlite[all]) (0.2.2)
Requirement already satisfied: beautifulsoup4 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from nbconvert>=6.4.4->jupyter_server->jupyterlite[all]) (4.11.1)
Requirement already satisfied: defusedxml in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from nbconvert>=6.4.4->jupyter_server->jupyterlite[all]) (0.7.1)
Requirement already satisfied: fastjsonschema in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from nbformat>=5.2.0->jupyter_server->jupyterlite[all]) (2.15.3)
Requirement already satisfied: ptyprocess in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/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.9/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.9/site-packages (from babel->jupyterlab_server<3,>=2.8.1->jupyterlite[all]) (2022.1)
Requirement already satisfied: jedi>=0.16 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from ipython->jupyterlab<4,>=3.0->jupyterlite[all]) (0.18.1)
Requirement already satisfied: setuptools>=18.5 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from ipython->jupyterlab<4,>=3.0->jupyterlite[all]) (62.6.0)
Requirement already satisfied: pexpect>4.3 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from ipython->jupyterlab<4,>=3.0->jupyterlite[all]) (4.8.0)
Requirement already satisfied: backcall in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from ipython->jupyterlab<4,>=3.0->jupyterlite[all]) (0.2.0)
Requirement already satisfied: prompt-toolkit!=3.0.0,!=3.0.1,<3.1.0,>=2.0.0 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from ipython->jupyterlab<4,>=3.0->jupyterlite[all]) (3.0.30)
Requirement already satisfied: stack-data in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from ipython->jupyterlab<4,>=3.0->jupyterlite[all]) (0.3.0)
Requirement already satisfied: decorator in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from ipython->jupyterlab<4,>=3.0->jupyterlite[all]) (5.1.1)
Requirement already satisfied: matplotlib-inline in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from ipython->jupyterlab<4,>=3.0->jupyterlite[all]) (0.1.3)
Requirement already satisfied: pickleshare in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from ipython->jupyterlab<4,>=3.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.9/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.9/site-packages (from requests->jupyterlab_server<3,>=2.8.1->jupyterlite[all]) (2.1.0)
Requirement already satisfied: urllib3<1.27,>=1.21.1 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from requests->jupyterlab_server<3,>=2.8.1->jupyterlite[all]) (1.26.9)
Requirement already satisfied: certifi>=2017.4.17 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from requests->jupyterlab_server<3,>=2.8.1->jupyterlite[all]) (2022.6.15)
Requirement already satisfied: parso<0.9.0,>=0.8.0 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from jedi>=0.16->ipython->jupyterlab<4,>=3.0->jupyterlite[all]) (0.8.3)
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.9/site-packages (from notebook<7->nbclassic~=0.2->jupyterlab<4,>=3.0->jupyterlite[all]) (6.15.0)
Requirement already satisfied: wcwidth in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from prompt-toolkit!=3.0.0,!=3.0.1,<3.1.0,>=2.0.0->ipython->jupyterlab<4,>=3.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.9/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.9/site-packages (from argon2-cffi-bindings->argon2-cffi->jupyter_server->jupyterlite[all]) (1.15.0)
Requirement already satisfied: soupsieve>1.2 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from beautifulsoup4->nbconvert>=6.4.4->jupyter_server->jupyterlite[all]) (2.3.1)
Requirement already satisfied: webencodings in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from bleach->nbconvert>=6.4.4->jupyter_server->jupyterlite[all]) (0.5.1)
Requirement already satisfied: pure-eval in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from stack-data->ipython->jupyterlab<4,>=3.0->jupyterlite[all]) (0.2.2)
Requirement already satisfied: executing in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from stack-data->ipython->jupyterlab<4,>=3.0->jupyterlite[all]) (0.8.3)
Requirement already satisfied: asttokens in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from stack-data->ipython->jupyterlab<4,>=3.0->jupyterlite[all]) (2.0.5)
Requirement already satisfied: pycparser in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from cffi>=1.0.1->argon2-cffi-bindings->argon2-cffi->jupyter_server->jupyterlite[all]) (2.21)
Requirement already satisfied: psutil in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from ipykernel->notebook<7->nbclassic~=0.2->jupyterlab<4,>=3.0->jupyterlite[all]) (5.9.1)
Requirement already satisfied: debugpy>=1.0 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/site-packages (from ipykernel->notebook<7->nbclassic~=0.2->jupyterlab<4,>=3.0->jupyterlite[all]) (1.6.0)
Installing collected packages: ipython-genutils, notebook, notebook-shim, nbclassic, jupyterlab
Successfully installed ipython-genutils-0.2.0 jupyterlab-3.4.3 nbclassic-0.3.7 notebook-6.4.12 notebook-shim-0.1.0
Quick Start#
Once installed, one can get to a locally-hosted, empty JupyterLite site with:
jupyter lite serve
This will:
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.
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_lsqzrc30
Well-known Files#
Some files in your --lite-dir that have special meaning:
look in path… |
… for file named |
… and if found |
|---|---|---|
|
|
merge with static in |
|
|
merge with static in |
|
|
copy verbatim to |
|
|
copy verbatim to |
|
|
copy verbatim to |
See more about merging contents.
Usage#
Common Parameters#
parameter |
description |
default |
environment variable |
|---|---|---|---|
|
configuration and content for the site |
current working directory |
|
|
where the hostable site will be created |
|
|
|
a cache directory for downloads |
|
|
|
disable a specific addon by entrypoint name |
||
|
an alternate site to base off of |
bundled |
|
|
directory to copy to |
|
|
|
patterns that should never be included in |
various |
|
|
the path to the archive |
|
|
|
port on |
|
|
|
the URL prefix to include before the site |
|
|
|
optionally enable additional reproducible build measures (best-effort!) |
|
|
|
paths to folders, |
||
|
don’t copy any contents, such as install labextensions, from |
|
|
|
additional settings overrides to enable |
||
|
additional wheels to make available |
||
|
the path or URL of a pyodide distribution (or .bz2 archive) |
|
|
|
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
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]
--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
static:jupyter-lite.json
. pre_status:static:jupyter-lite.json
tarball: jupyterlite-app-0.1.0-beta.10.tgz 8MB
output: /tmp/_my_lite_dir_lsqzrc30/_output
lite dir: /tmp/_my_lite_dir_lsqzrc30
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_lsqzrc30-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.9/site-packages/jupyter_server_mathjax/static
configured MathJax dir: /tmp/_my_lite_dir_lsqzrc30/traitlets.Undefined
effective MathJax dir: /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/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
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_lsqzrc30-jupyterlite.tgz
R archive
R archive:archive:archive:_my_lite_dir_lsqzrc30-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.10.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_lsqzrc30/_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_lsqzrc30/_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
static:jupyter-lite.json
. pre_status:static:jupyter-lite.json
tarball: jupyterlite-app-0.1.0-beta.10.tgz 8MB
output: /tmp/_my_lite_dir_lsqzrc30/_output
lite dir: /tmp/_my_lite_dir_lsqzrc30
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_lsqzrc30-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.9/site-packages/jupyter_server_mathjax/static
configured MathJax dir: /tmp/_my_lite_dir_lsqzrc30/traitlets.Undefined
effective MathJax dir: /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/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
static:jupyter-lite.json
. pre_status:static:jupyter-lite.json
tarball: jupyterlite-app-0.1.0-beta.10.tgz 8MB
output: /tmp/_my_lite_dir_lsqzrc30/_output
lite dir: /tmp/_my_lite_dir_lsqzrc30
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_lsqzrc30-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.9/site-packages/jupyter_server_mathjax/static
configured MathJax dir: /tmp/_my_lite_dir_lsqzrc30/traitlets.Undefined
effective MathJax dir: /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/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
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]
--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
static:jupyter-lite.json
. pre_status:static:jupyter-lite.json
tarball: jupyterlite-app-0.1.0-beta.10.tgz 8MB
output: /tmp/_my_lite_dir_lsqzrc30/_output
lite dir: /tmp/_my_lite_dir_lsqzrc30
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_lsqzrc30-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.9/site-packages/jupyter_server_mathjax/static
configured MathJax dir: /tmp/_my_lite_dir_lsqzrc30/traitlets.Undefined
effective MathJax dir: /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.9/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
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]
--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.
# 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 |
|
Windows |
|
Python |
|
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 1656664557
if not RTD:
!jupyter lite archive --source-date-epoch {source_date_epoch} --output-archive ./a.tgz
If we clear out our _output…
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
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
--contentsis provided, the default value of--contents fileswill be ignoredIf 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.orguses non-standard HTTP headers to S3 buckets to provide packagesthe
conda-forgechannel 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
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-prefixor--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