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.yaml

xeus-python kernel

To load a xeus-python kernel with a custom environment, create an environment.yaml 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.yaml is the path to the file you just created

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

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.yaml

Multiple kernels

To create a deployment with multiple kernels, you can simply add them to the environment.yaml 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.yaml \
    --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.1.3.tar.gz (278.0 kB view details)

Uploaded Source

Built Distribution

jupyterlite_xeus-0.1.3-py3-none-any.whl (47.8 kB view details)

Uploaded Python 3

File details

Details for the file jupyterlite_xeus-0.1.3.tar.gz.

File metadata

  • Download URL: jupyterlite_xeus-0.1.3.tar.gz
  • Upload date:
  • Size: 278.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/4.0.2 CPython/3.11.7

File hashes

Hashes for jupyterlite_xeus-0.1.3.tar.gz
Algorithm Hash digest
SHA256 ba231709ac7fa403c1a208967169d75f9ba9f433263c4ab1434e19e489a2973e
MD5 67a44ff012dd797fc43007506d000984
BLAKE2b-256 013be95e4cba293dd92ae54d6c7a2c9ec3085f342007d26fb3a4ff69e47f4577

See more details on using hashes here.

Provenance

File details

Details for the file jupyterlite_xeus-0.1.3-py3-none-any.whl.

File metadata

File hashes

Hashes for jupyterlite_xeus-0.1.3-py3-none-any.whl
Algorithm Hash digest
SHA256 0a7094988290573c78b4de518bd8382a2900422b8611c44685668d749c6d2a5c
MD5 9e240b87a1069533c140e892f29fa293
BLAKE2b-256 b236c61774d0f508a685ab1b3c06e0f1d5be73705e8620004b5a59247bc2edf4

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