import os, pathlib, tempfile, shutil, atexit, hashlib, pandas
from IPython.display import *
from IPython import get_ipython # needed for `jupyter_execute` because magics?
The jupyter lite (or jupyter-lite) CLI provides tools for lifecycle of combining...
... into a ready-to-deploy (and optionally reproducible) Jupyter sites which require no server.
!pip install jupyterlite
!jupyter lite --version
Some extra features of different addons have additional dependencies.
pip install jupyterlite[contents] # jupyter_server for better contents API
pip install jupyterlite[serve] # tornado for better local preview
pip install jupyterlite[lab] # a known-compatible jupyterlab (entails `contents` and `serve`)
# TODO: [archive] # use libarchive
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())
Some files in your --lite-dir that have special meaning:
| paths | file | if found | |
|---|---|---|---|
../lab./retro |
jupyter-lite.{json,ipynb} |
merge contents with static in _output/{path}/jupyter-lite.{json,ipynb} |
|
../lab./retro |
overrides.json |
merge with static _output/{*}/jupyter-lite.json |
|
./files/ |
* |
copy verbatim to _output/files/* and index in /api/contents |
| 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 |
--app-archive |
an alternate site to base off of | bundled | |
--files |
directory to copy to _output/files/ and available as Contents |
./files |
|
--ignore-files |
patterns that should never be included in /files/ (even if found in lite-dir). |
various | |
--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 |
The CLI provides its own documentation, under --help (or -h).
!jupyter lite --help
Always safe to run, this command provides an overview of what JupyterLite has been doing.
!jupyter lite status
Always safe to run, this command provides an overview of what JupyterLite might do.
TODO: improve on default output
!jupyter lite list
Copy all the static data to the --output-dir.
!jupyter lite init
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
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](./deploying.md) options
before trying to make this something it isn't.
!jupyter lite serve --help
Use all available mechanisms to verify that the build folder conforms to schema, etc.
!jupyter lite check
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.
!jupyter lite archive
But let's talk about a more reproducible asset.
shutil.rmtree(TMP_DIR / "_output")
🛠️ 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:
{note}
This is a shortcut for setting the environment variable `SOURCE_DATE_EPOCH`:
| platform | command |
|------------------|-------------------------------------------------------|
| Linux<br/>MacOS | `export SOURCE_DATE_EPOCH=<a timestamp>` |
| Windows | `set SOURCE_DATE_EPOCH=<a timestamp>` |
| Python | `os.environ.update(SOURCE_DATE_EPOCH, <a timestamp>)` |
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)
!jupyter lite archive --source-date-epoch {source_date_epoch} --output-archive ./a.tgz
If we clear out our _output...
shutil.rmtree(TMP_DIR / "_output")
print(TMP_DIR.rglob("*"))
...and rebuild, we should always get the same file.
!jupyter lite archive --source-date-epoch {source_date_epoch} --output-archive ./b.tgz
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")