| Name | jupyterlite-xeus JSON |
| Version |
2.0.0
JSON |
| download |
| home_page | None |
| Summary | JupyterLite loader for Xeus kernels |
| upload_time | 2024-09-10 14:39:23 |
| maintainer | None |
| docs_url | None |
| author | JupyterLite Contributors |
| requires_python | >=3.8 |
| license | BSD 3-Clause License Copyright (c) 2023, JupyterLite Contributors All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# JupyterLite Xeus
[](https://github.com/jupyterlite/xeus/actions/workflows/build.yml)
JupyterLite loader for Xeus kernels
## Requirements
- JupyterLab >= 4.0.0
## Install
To install the extension, execute:
```bash
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:
```yaml
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
```bash
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
```yaml
dependencies:
- xeus-lua
```
or
```yaml
dependencies:
- xeus-sqlite
```
Note that `xeus-sqlite` and `xeus-lua` do not support additional dependencies yet.
To build JupyterLite, run again:
```bash
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:
```yaml
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`).
```bash
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:
```bash
# 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.
```bash
# 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:
```bash
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.
```bash
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):
```bash
micromamba create -f environment-dev.yml -n xeus-lite-dev
```
Activate the environment:
```bash
micromamba activate xeus-lite-dev
```
```bash
python -m pip install -e . -v --no-build-isolation
```
### Packaging the extension
See [RELEASE](RELEASE.md).
Raw data
{
"_id": null,
"home_page": null,
"name": "jupyterlite-xeus",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "JupyterLite Contributors",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/65/ba/18f9f38e7a49e0d65fa4ae3ef0f7893cd54bfc87df6b4e9d58e801b94085/jupyterlite_xeus-2.0.0.tar.gz",
"platform": null,
"description": "# JupyterLite Xeus\n\n[](https://github.com/jupyterlite/xeus/actions/workflows/build.yml)\n\nJupyterLite loader for Xeus kernels\n\n## Requirements\n\n- JupyterLab >= 4.0.0\n\n## Install\n\nTo install the extension, execute:\n\n```bash\npip install jupyterlite_xeus\n```\n\n## Usage\n\n### From environment.yml\n\n#### xeus-python kernel\n\nTo 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:\n\n```yaml\nname: xeus-lite-wasm\nchannels:\n - https://repo.mamba.pm/emscripten-forge\n - conda-forge\ndependencies:\n - xeus-python\n - numpy\n```\n\nTo build JupyterLite, run the following command where `environment.yml` is the path to the file you just created\n\n```bash\njupyter lite build --XeusAddon.environment_file=some_path/to/environment.yml\n```\n\n#### xeus-lua / xeus-sqlite / xeus-\\<mylang\\>\n\nTo load a `xeus-lua` or `xeus-sqlite` kernel you can\ndo the same as above, just with\n\n```yaml\ndependencies:\n - xeus-lua\n```\n\nor\n\n```yaml\ndependencies:\n - xeus-sqlite\n```\n\nNote that `xeus-sqlite` and `xeus-lua` do not support additional dependencies yet.\nTo build JupyterLite, run again:\n\n```bash\njupyter lite build --XeusAddon.environment_file=environment.yml\n```\n\n#### Multiple kernels\n\nTo create a deployment with multiple kernels, you can simply add them to the `environment.yml` file:\n\n```yaml\nname: xeus-lite-wasm\nchannels:\n - https://repo.mamba.pm/emscripten-forge\n - conda-forge\ndependencies:\n - xeus-python\n - xeus-lua\n - xeus-sqlite\n - numpy\n```\n\n### From local environment / prefix\n\nWhen 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.\n\n#### Create a local environment / prefix\n\nThis 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`).\n\n```bash\nmicromamba create -n xeus-python-dev \\\n --platform=emscripten-wasm32 \\\n -c https://repo.mamba.pm/emscripten-forge \\\n -c conda-forge \\\n --yes \\\n \"python>=3.11\" pybind11 nlohmann_json pybind11_json numpy pytest \\\n bzip2 sqlite zlib libffi xtl pyjs \\\n xeus xeus-lite\n```\n\n#### Build the kernel\n\nThis depends on your kernel, but it will look something like this:\n\n```bash\n# path to your emscripten emsdk\nsource $EMSDK_DIR/emsdk_env.sh\n\nWASM_ENV_NAME=xeus-python-dev\nWASM_ENV_PREFIX=$MAMBA_ROOT_PREFIX/envs/$WASM_ENV_NAME\n\n# let cmake know where the env is\nexport PREFIX=$WASM_ENV_PREFIX\nexport CMAKE_PREFIX_PATH=$PREFIX\nexport CMAKE_SYSTEM_PREFIX_PATH=$PREFIX\n\ncd /path/to/your/kernel/src\nmkdir build_wasm\ncd build_wasm\nemcmake cmake \\\n -DCMAKE_BUILD_TYPE=Release \\\n -DCMAKE_FIND_ROOT_PATH_MODE_PACKAGE=ON \\\n -DCMAKE_INSTALL_PREFIX=$PREFIX \\\n ..\nemmake make -j8 install\n```\n\n#### Build the JupyterLite site\n\nYou will need to create a new environment with the dependencies to build the JupyterLite site.\n\n```bash\n# create new environment\nmicromamba create -n xeus-lite-host \\\n jupyterlite-core\n\n# activate the environment\nmicromamba activate xeus-lite-host\n\n# install jupyterlite_xeus via pip\npython -m pip install jupyterlite-xeus\n```\n\nWhen running `jupyter lite build`, we pass the `prefix` option and point it to the local environment / prefix we just created:\n\n```bash\njupyter lite build --XeusAddon.prefix=$WASM_ENV_PREFIX\n```\n\n### Mounting additional files\n\nTo copy additional files and directories into the virtual filesystem of the xeus-lite kernels you can use the `--XeusAddon.mount` option.\nEach 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.\n\n```bash\njupyter lite build \\\n --XeusAddon.environment_file=environment.yml \\\n --XeusAddon.mounts=/some/path/on/host_machine:/some/path/in/virtual/filesystem\n```\n\n## Contributing\n\n### Development install from a conda / mamba environment\n\nCreate the conda environment with `conda`/`mamba`/`micromamba` (replace `micromamba` with `conda` or `mamba` according to your preference):\n\n```bash\nmicromamba create -f environment-dev.yml -n xeus-lite-dev\n```\n\nActivate the environment:\n\n```bash\nmicromamba activate xeus-lite-dev\n```\n\n```bash\npython -m pip install -e . -v --no-build-isolation\n```\n\n### Packaging the extension\n\nSee [RELEASE](RELEASE.md).\n",
"bugtrack_url": null,
"license": "BSD 3-Clause License Copyright (c) 2023, JupyterLite Contributors All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.",
"summary": "JupyterLite loader for Xeus kernels",
"version": "2.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/jupyterlite/xeus/issues",
"Homepage": "https://github.com/jupyterlite/xeus",
"Repository": "https://github.com/jupyterlite/xeus.git"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "36ef73bef6cbf87a751d0b39af6206915d7faf0097010ac3d0af3ec45dd017ab",
"md5": "9b5feacc727f6cc6073d0257004ac0e6",
"sha256": "d99ba4314d9b071330958828f19a4d898ab0e34183b1bc93d866417710158629"
},
"downloads": -1,
"filename": "jupyterlite_xeus-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9b5feacc727f6cc6073d0257004ac0e6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 68531,
"upload_time": "2024-09-10T14:39:20",
"upload_time_iso_8601": "2024-09-10T14:39:20.571319Z",
"url": "https://files.pythonhosted.org/packages/36/ef/73bef6cbf87a751d0b39af6206915d7faf0097010ac3d0af3ec45dd017ab/jupyterlite_xeus-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "65ba18f9f38e7a49e0d65fa4ae3ef0f7893cd54bfc87df6b4e9d58e801b94085",
"md5": "5f0e5b602418e8689877b378040dce12",
"sha256": "cc04e7637faf6aab544dd3d7b4d41cb46e941f7a4f450352c937c32a461a8e0c"
},
"downloads": -1,
"filename": "jupyterlite_xeus-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "5f0e5b602418e8689877b378040dce12",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 273179,
"upload_time": "2024-09-10T14:39:23",
"upload_time_iso_8601": "2024-09-10T14:39:23.394235Z",
"url": "https://files.pythonhosted.org/packages/65/ba/18f9f38e7a49e0d65fa4ae3ef0f7893cd54bfc87df6b4e9d58e801b94085/jupyterlite_xeus-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-10 14:39:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jupyterlite",
"github_project": "xeus",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "jupyterlite-xeus"
}
