Skip to main content

JupyterLite loader for Xeus kernels

Project description

JupyterLite Xeus

Github Actions Status

JupyterLite loader for Xeus kernels

Requirements

  • JupyterLab >= 4.0.0

Install

To install the extension, execute:

pip install jupyterlite_xeus

Usage

From environment.yml

xeus-python kernel

To load a xeus-python kernel with a custom environment, create an environment.yml file with xeus-python and the desired dependencies. Here is an example with numpy as a additional dependency:

name: xeus-lite-wasm
channels:
  - https://repo.mamba.pm/emscripten-forge
  - conda-forge
dependencies:
  - xeus-python
  - numpy

To build JupyterLite, run the following command where environment.yml is the path to the file you just created

jupyter lite build --XeusAddon.environment_file=some_path/to/environment.yml

xeus-lua / xeus-sqlite / xeus-<mylang>

To load a xeus-lua or xeus-sqlite kernel you can do the same as above, just with

dependencies:
  - xeus-lua

or

dependencies:
  - xeus-sqlite

Note that xeus-sqlite and xeus-lua do not support additional dependencies yet. To build JupyterLite, run again:

jupyter lite build --XeusAddon.environment_file=environment.yml

Multiple kernels

To create a deployment with multiple kernels, you can simply add them to the environment.yml file:

name: xeus-lite-wasm
channels:
  - https://repo.mamba.pm/emscripten-forge
  - conda-forge
dependencies:
  - xeus-python
  - xeus-lua
  - xeus-sqlite
  - numpy

From local environment / prefix

When developing a xeus-kernel, it is very useful to be able to test it in JupyterLite without having to publish the kernel to emscripten-forge. Therefore, you can also use a local environment / prefix to build JupyterLite with a custom kernel.

Create a local environment / prefix

This workflow usually starts with creating a local conda environment / prefix for the emscripten-wasm32 platform with all the dependencies required to build your kernel (here we install dependencies for xeus-python).

micromamba create -n xeus-python-dev \
    --platform=emscripten-wasm32 \
    -c https://repo.mamba.pm/emscripten-forge \
    -c conda-forge \
    --yes \
    "python>=3.11" pybind11 nlohmann_json pybind11_json numpy pytest \
    bzip2 sqlite zlib libffi xtl pyjs \
    xeus xeus-lite

Build the kernel

This depends on your kernel, but it will look something like this:

# path to your emscripten emsdk
source $EMSDK_DIR/emsdk_env.sh

WASM_ENV_NAME=xeus-python-dev
WASM_ENV_PREFIX=$MAMBA_ROOT_PREFIX/envs/$WASM_ENV_NAME

# let cmake know where the env is
export PREFIX=$WASM_ENV_PREFIX
export CMAKE_PREFIX_PATH=$PREFIX
export CMAKE_SYSTEM_PREFIX_PATH=$PREFIX

cd /path/to/your/kernel/src
mkdir build_wasm
cd build_wasm
emcmake cmake \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_FIND_ROOT_PATH_MODE_PACKAGE=ON \
    -DCMAKE_INSTALL_PREFIX=$PREFIX \
    ..
emmake make -j8 install

Build the JupyterLite site

You will need to create a new environment with the dependencies to build the JupyterLite site.

# create new environment
micromamba create -n xeus-lite-host \
    jupyterlite-core

# activate the environment
micromamba activate xeus-lite-host

# install jupyterlite_xeus via pip
python -m pip install jupyterlite-xeus

When running jupyter lite build, we pass the prefix option and point it to the local environment / prefix we just created:

jupyter lite build --XeusAddon.prefix=$WASM_ENV_PREFIX

Mounting additional files

To copy additional files and directories into the virtual filesystem of the xeus-lite kernels you can use the --XeusAddon.mount option. Each mount is specified as a pair of paths separated by a colon :. The first path is the path to the file or directory on the host machine, the second path is the path to the file or directory in the virtual filesystem of the kernel.

jupyter lite build \
    --XeusAddon.environment_file=environment.yml \
    --XeusAddon.mounts=/some/path/on/host_machine:/some/path/in/virtual/filesystem

Contributing

Development install from a conda / mamba environment

Create the conda environment with conda/mamba/micromamba (replace micromamba with conda or mamba according to your preference):

micromamba create -f environment-dev.yml -n xeus-lite-dev

Activate the environment:

micromamba activate xeus-lite-dev
python -m pip install -e .   -v --no-build-isolation

Packaging the extension

See RELEASE.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

jupyterlite_xeus-0.2.0a1.tar.gz (250.2 kB view details)

Uploaded Source

Built Distribution

jupyterlite_xeus-0.2.0a1-py3-none-any.whl (44.8 kB view details)

Uploaded Python 3

File details

Details for the file jupyterlite_xeus-0.2.0a1.tar.gz.

File metadata

  • Download URL: jupyterlite_xeus-0.2.0a1.tar.gz
  • Upload date:
  • Size: 250.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.1 CPython/3.11.9

File hashes

Hashes for jupyterlite_xeus-0.2.0a1.tar.gz
Algorithm Hash digest
SHA256 d40c7b0c412765b2ccfce31619ff9ed7ab2190415d08e4577ecd5cb15b9331fc
MD5 7dfb0cd73e10b0dd83ee840d7e5547b6
BLAKE2b-256 a1a20f0576094089a1e4dba748f033d768a080f074b4ebde6c6eb94682baf7f0

See more details on using hashes here.

Provenance

File details

Details for the file jupyterlite_xeus-0.2.0a1-py3-none-any.whl.

File metadata

File hashes

Hashes for jupyterlite_xeus-0.2.0a1-py3-none-any.whl
Algorithm Hash digest
SHA256 bb9e0dc2a3b71a33c5fe02a9b89ca8f9f11ca46f451d95d621dd886006f0f9dc
MD5 fc65041d231acc4e949ceca5988ca5d3
BLAKE2b-256 7d3492d5245da742385f4338bd5d7bf75c9f768de84e601464513cf6c637f4c5

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page