Metadata-Version: 2.4
Name: jupyterlite-pyodide-kernel
Version: 0.8.0a2
Summary: Python kernel for JupyterLite powered by Pyodide
Project-URL: Homepage, https://jupyterlite-pyodide-kernel.readthedocs.io
Project-URL: Documentation, https://jupyterlite-pyodide-kernel.readthedocs.io
Project-URL: Source, https://github.com/jupyterlite/pyodide-kernel
Project-URL: Issues, https://github.com/jupyterlite/pyodide-kernel/issues
Project-URL: PyPI, https://pypi.org/project/jupyterlite-pyodide-kernel
Author: JupyterLite Contributors
License-Expression: BSD-3-Clause
License-File: LICENSE
Keywords: browser,jupyter,jupyterlab,jupyterlite,notebook,pyodide
Classifier: Framework :: Jupyter
Classifier: Framework :: Jupyter :: JupyterLab
Classifier: Framework :: Jupyter :: JupyterLab :: 4
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Requires-Dist: jupyterlite-core<0.9.0,>=0.8.0a0
Requires-Dist: pkginfo
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: hatch; extra == 'dev'
Requires-Dist: jupyterlab<4.7.0,>=4.6.0a2; extra == 'dev'
Provides-Extra: docs
Requires-Dist: ipywidgets<9,>=8.1.3; extra == 'docs'
Requires-Dist: jupyter-server-mathjax; extra == 'docs'
Requires-Dist: jupyterlab-language-pack-fr-fr; extra == 'docs'
Requires-Dist: jupyterlab-language-pack-zh-cn; extra == 'docs'
Requires-Dist: libarchive-c; extra == 'docs'
Requires-Dist: myst-parser; extra == 'docs'
Requires-Dist: pydata-sphinx-theme; extra == 'docs'
Requires-Dist: sphinx-copybutton; extra == 'docs'
Provides-Extra: lint
Requires-Dist: ruff>=0.3.0; extra == 'lint'
Provides-Extra: lock
Requires-Dist: pyodide-lock[uv]<0.2.0,>=0.1.2; extra == 'lock'
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-console-scripts>=1.4.0; extra == 'test'
Requires-Dist: pytest-cov<7; extra == 'test'
Requires-Dist: pytest-html; extra == 'test'
Description-Content-Type: text/markdown

# jupyterlite-pyodide-kernel

> A Python kernel for [JupyterLite](https://jupyterlite.rtfd.io) powered by
> [Pyodide](https://pyodide.org),

[![ci-badge]][ci] [![lite-badge]][lite] [![docs-badge]][docs]

[ci-badge]: https://github.com/jupyterlite/pyodide-kernel/workflows/Build/badge.svg
[lite-badge]: https://jupyterlite.rtfd.io/en/latest/_static/badge.svg
[lite]: https://jupyterlite-pyodide-kernel.rtfd.io/en/latest/_static
[ci]: https://github.com/jupyterlite/pyodide-kernel/actions?query=branch%3Amain
[docs-badge]:
  https://readthedocs.org/projects/jupyterlite-pyodide-kernel/badge/?version=latest
[docs]: https://jupyterlite-pyodide-kernel.readthedocs.io/en/latest/?badge=latest

## Install

To install the Pyodide kernel labextension and the CLI addons for `jupyter lite`, run:

```bash
pip install jupyterlite-pyodide-kernel
```

or with `conda`, `mamba`, `micromamba`, etc.

```bash
conda install -c conda-forge jupyterlite-pyodide-kernel
```

> For more options see the [development install](#development-install) or [contributing
> guide][contrib].

### Optional Features

#### Lock

Install the `[lock]` extra for compatible versions of [`pyodide-lock`][pyodide-lock] and
[`uv`][uv], used to add local or PyPI packages and their import name and dependency
information to the Pyodide lockfile:

- from PyPI: `jupyterlite-pyodide-kernel[lock]`
- from `conda-forge`: `jupyterlite-pyodide-kernel-with-lock`

[pyodide-lock]: https://pypi.org/project/pyodide-lock
[uv]: https://pypi.org/project/uv

### Compatibility

#### With Jupyter

| status | `jupyterlite-pyodide-kernel` | `jupyterlite-core` |  `jupyterlab`  |   `notebook`   |  `retrolab`  |
| :----: | :--------------------------: | :----------------: | :------------: | :------------: | :----------: |
| stable |           `0.8.*`            |    `>=0.8,<0.9`    | `>=4.6.0,<4.7` | `>=7.6.0,<7.7` |      -       |
| stable |           `0.7.*`            |    `>=0.7,<0.8`    | `>=4.5.0,<4.6` | `>=7.5.0,<7.6` |      -       |
| stable |           `0.6.*`            |    `>=0.6,<0.7`    | `>=4.4.3,<4.5` | `>=7.4.3,<7.5` |      -       |
| stable |           `0.5.*`            |    `>=0.5,<0.6`    | `>=4.3.0,<4.4` | `>=7.3.0,<7.4` |      -       |
| stable |           `0.4.*`            |    `>=0.4,<0.5`    | `>=4.2.0,<4.3` | `>=7.2.0,<7.3` |      -       |
| stable |           `0.3.*`            |    `>=0.3,<0.4`    | `>=4.1.1,<4.2` | `>=7.1.0,<7.2` |      -       |
| stable |           `0.2.*`            |    `>=0.2,<0.3`    | `>=4.0.7,<4.1` | `>=7.0.5,<7.1` |      -       |
| stable |           `0.1.*`            |    `>=0.1,<0.2`    |  `>=3.5,<3.6`  |       -        | `>=0.3,<0.4` |

Installing the matching version of JupyterLab with your package manager can help ensure
matching labextension assets and kernel dependencies, even though this kernel does not
yet work in a full, `jupyter_server`-hosted client such as JupyterLab or Notebook.

#### With Pyodide

| `jupyterlite-pyodide-kernel` | `pyodide` | `python` | `emscripten` | `pyodide-lock` |    `uv`    |
| :--------------------------: | :-------: | :------: | :----------: | :------------: | :--------: |
|      `>=0.1.0,<=0.1.1`       | `0.23.*`  | `3.10.*` |   `3.1.29`   |                |            |
|      `>=0.1.2,<=0.2.1`       | `0.24.*`  | `3.10.*` |   `3.1.45`   |                |            |
|      `>=0.2.2,<=0.2.3`       | `0.25.*`  | `3.11.*` |   `3.1.46`   |                |            |
|      `>=0.3.*,<=0.4.0`       | `0.25.*`  | `3.11.*` |   `3.1.46`   |                |            |
|      `>=0.4.*,<=0.4.6`       | `0.26.*`  | `3.12.*` |   `3.1.58`   |                |            |
|      `>=0.4.7,<=0.5.0`       | `0.27.*`  | `3.12.*` |   `3.1.58`   |                |            |
|      `>=0.5.0,<=0.6.0`       | `0.27.*`  | `3.12.*` |   `3.1.58`   |                |            |
|      `>=0.6.0,<=0.7.0`       | `0.27.*`  | `3.12.*` |   `3.1.58`   |                |            |
|      `>=0.7.0,<=0.8.0`       | `0.29.*`  | `3.13.*` |   `4.0.9`    |                |            |
|      `>=0.8.0,<=0.9.0`       | `0.29.*`  | `3.13.*` |   `4.0.9`    | `>=0.1.2,<0.2` | `>=0.9.27` |

> **Note**: the Emscripten version is strict down to the patch version.

## Usage

Once installed, building a JupyterLite site will include a kernel which uses the full
Pyodide CDN distribution:

```bash
jupyter lite build
```

The build configuration of the Pyodide distribution, the kernel, and package import
behavior can be configured in `jupyter_lite_config.json`. Some features can be
configured with CLI aliases and flags. See the full current list by running:

```bash
jupyter lite --help
```

This should show something like the following:

<details><summary>... for configuring the Pyodide distribution</summary>

```bash
  --pyodide=<Unicode>
      Local path or URL of a pyodide distribution tarball
      Default: ''
      Equivalent to: [--PyodideAddon.pyodide_url]
```

</details>

<details><summary>... adding extra wheels, installable at runtime with <code>%pip</code></summary>

```bash
  --piplite-wheels=<typedtuple-item-1>...
      Local paths or URLs of piplite-compatible wheels to copy and index
      Default: ()
      Equivalent to: [--PipliteAddon.piplite_urls]
```

</details>

<details><summary>.... patching the Pyodide lockfile for automatically imported packages</summary>

```bash
# flags
--pyodide-lock
    Use pyodide-lock and uv to customize pyodide-lock.json
    Equivalent to: [--PyodideLockAddon.enabled=True]
--pyodide-lock-no-constrain-extensions
    Add ``LiteBuildConfig.federated_extensions`` to constraints
    Equivalent to: [--PyodideLockAddon.constrain_extensions=False]

# options
--pyodide-lock-url=<Unicode>
    URL of a remote pyodide-lock.json:
    https://cdn.jsdelivr.net/pyodide/v0.29.3/full/pyodide-lock.json
    Default: ''
    Equivalent to: [--PyodideLockAddon.pyodide_lock_url]
--pyodide-lock-wheels=<typedtuple-item-1>...
    paths to local wheels or folders to include in pyodide-lock.json
    Default: ()
    Equivalent to: [--PyodideLockAddon.wheels]
--pyodide-lock-constraints=<typedtuple-item-1>...
    PEP-508 specs for Python packages to lock only if required in pyodide-
    lock.json; may include ``-r/--requirements`` and  ``-g/--group`` relative to
    ``lite_dir``
    Default: ()
    Equivalent to: [--PyodideLockAddon.constraints]
--pyodide-lock-lite-constraints=<Unicode>
    path relative to ``lite_dir`` to a ``requirements.txt``-style file with
    versions of all `none-any.whl` packages from pyodide-lock.json written if
    missing, otherwise added to ``constraints`` and left unchanged
    Default: ''
    Equivalent to: [--PyodideLockAddon.lite_constraints_file]
--pyodide-lock-specs=<typedtuple-item-1>...
    PEP-508 specs for Python packages to include in pyodide-lock.json; may
    include ``-r/--requirements`` and ``-g/--group`` relative to ``lite_dir``
    Default: ()
    Equivalent to: [--PyodideLockAddon.specs]
--pyodide-lock-excludes=<typedtuple-item-1>...
    extra Python package names to exclude from pyodide-lock.json
    Default: ()
    Equivalent to: [--PyodideLockAddon.excludes_extra]
--pyodide-lock-prefetch=<typedtuple-item-1>...
    extra Python package names from pyodide-lock.json to prefetch while
    initializing Pyodide
    Default: ()
    Equivalent to: [--PyodideLockAddon.prefetch_extra]
```

</details>

## Learn more

⚠️ The documentation for advanced configuration is available from the main JupyterLite
documentation site:

- [configuring]
- [command line interface][cli]

[configuring]:
  https://jupyterlite.readthedocs.io/en/latest/howto/index.html#configuring-the-python-environment
[cli]: https://jupyterlite.readthedocs.io/en/latest/reference/cli.html

## Uninstall

To remove the extension, run:

```bash
pip uninstall jupyterlite-pyodide-kernel  # or however you installed it
```

## Prerelease Versions

To install pre-release versions with `pip`:

```bash
pip install --upgrade --pre jupyterlite-pyodide-kernel
```

Or, similarly for the `conda` ecosystem, for `alpha` packages:

```bash
conda install \
  -c conda-forge/label/jupyterlite_core_alpha \
  -c conda-forge/label/jupyterlite_pyodide_kernel_alpha \
  -c conda-forge \
  jupyterlite-pyodide-kernel
```

> Note: `_beta` and `_rc` packages would follow a similar channel naming convention

## Development Install

Below is an short overview of getting up and running quickly. Please see the
[contributing guide][contrib] for full details.

### Development Requirements

**Recommended** a Python virtual environment provided by a tool of choice, e.g. one of:

- `virtualenv`
- `mamba`
- `conda`

Ensure the local development environment has:

- `git`
- `nodejs 22`
- `python >=3.8`

### Development Quick Start

```bash
git clone https://github.com/jupyterlite/pyodide-kernel
cd pyodide-kernel
npm run quickstart
```

Then, serve the built demo site, documentation, and test reports with Python's built-in
HTTP server:

```bash
jlpm serve
```

[contrib]: https://github.com/jupyterlite/pyodide-kernel/blob/main/CONTRIBUTING.md
