Add bootstrapCode config option

[juntyr]

The new bootstrapCode extension config option allows JupyterLite hosts to run custom Python code before the kernel starts. This should help downstream projects with the commonly wanted feature of "running code before the first cell".

Related to #88

[github-actions]

👈 Try it on ReadTheDocs

[juntyr]

ping @jtpio

[jtpio]

Thanks @juntyr.

Having it implemented via such option sounds like a fine approach.

Also when there is something to help better see the logs (jupyterlite/jupyterlite#1498), it will be easier for users to troubleshoot issues if something goes wrong with this extra bootstrapCode.

[bollwyvl]

Again, this is a feature that also does not exist in JupyterLab, and for which there are user space extensions.

For "pre-installing" packages, there are also other approaches such as jupyterlite-pyodide-lock, which put everything known packages into pyodide-lock.json such that they will be imported automatically.

[juntyr]

Again, this is a feature that also does not exist in JupyterLab, and for which there are user space extensions.

Could you please point towards one? If there’s an existing extension that can do that I’d be very happy to use it and close this PR.

For "pre-installing" packages, there are also other approaches such as jupyterlite-pyodide-lock, which put everything known packages into pyodide-lock.json such that they will be imported automatically.

That just preloads them, but doesn’t run them. What this PR tries to provide is a way to run custom code during bootstrap, which is not yet possible otherwise (as far as I know). At the moment, I have to use some very hacky patches to IPython to get some code to run after the interpreter is setup but before the user gains control. This is very valuable for applying behind-the-scenes magic that the user doesn’t need to see.

[bollwyvl]

Here is a discourse discussion with more context (and related links at the bottom):

https://discourse.jupyter.org/t/setting-initialization-cells-for-jupyterlab/13345

[juntyr]

Are any of these solutions not tied to notebooks? I’m looking for something that can be configured by the host of JupyterLite, not something that needs to be configured by the notebook author

[juntyr]

I found that this can be done using IPython startup scripts or extensions. See https://stackoverflow.com/questions/32438235/ipython-notebook-default-initialization-python-code, https://modelpredict.com/how-to-write-reliable-scripts-ipython/, https://stackoverflow.com/questions/48803339/modifying-jupyter-notebook-in-init-code, and https://emscripten.org/docs/porting/files/packaging_files.html#modifying-file-locations-in-the-virtual-file-system

[jtpio]

@juntyr would you still like to document your approach, for example in https://jupyterlite.readthedocs.io/en/stable/howto/index.html#configuring-the-pyodide-kernel? So it can be useful to other people too.

[juntyr]

Right now the approach requires controlling the Pyodide build, as I need to make emscripten embed the IPython config files into the filesystem. The rest is already documented by https://modelpredict.com/how-to-write-reliable-scripts-ipython/, I just copied its code.

So in the end we have:

1. I now have an assets folder in my Pyodide fork here https://github.com/climet-eu/pyodide/tree/058717a2b1311b9efbd3166e5c5ff35a12d75bf6/assets, which contains files that should be included in the filesystem
2. I modified Pyodide's Makefile to embed the folder here https://github.com/climet-eu/pyodide/blob/058717a2b1311b9efbd3166e5c5ff35a12d75bf6/Makefile#L129
3. The asset folder contains an ipython_config.py file that adds the extensions here https://github.com/climet-eu/pyodide/blob/058717a2b1311b9efbd3166e5c5ff35a12d75bf6/assets/home/pyodide/.ipython/profile_default/ipython_config.py
4. The extension, which can be a file in the same assets folder, exposes the following interface

def load_ipython_extension(ip):
    # do stuff here