🪐 > Jupyter Kernel Client

Jupyter Kernel Client allows you to connect to live Jupyter Kernels through HTTP and WebSocket.

A Kernel is the process responsible to execute the notebook code.

Jupyter Kernel Client also provides a easy to use interactive Konsole (console for Kernels aka REPL, Read-Evaluate-Print-Loop).

Install

To install the library, run the following command.

pip install jupyter_kernel_client

Jupyter Server Kernel

Check you have a Jupyter Server with ipykernel running somewhere. You can install those packages with the following command.

pip install jupyter-server ipykernel

1. Start a Jupyter Server.

# make jupyter-server
jupyter server --port 8888 --ServerApp.port_retries 0 --IdentityProvider.token MY_TOKEN

2. Launch a IPython REPL in a terminal with ipython (or jupyter console). Execute the following snippet (update the server_url and token if needed).

import os

from platform import node
from jupyter_kernel_client import JupyterKernelClient

with JupyterKernelClient(server_url="http://localhost:8888", token="MY_TOKEN") as kernel:
    code = """import os
from platform import node
print(f"Hey {os.environ.get('USER', 'John Smith')} from {node()}.")
"""
    reply = kernel.execute(code)
    print(reply)
    assert reply["execution_count"] == 1
    assert reply["outputs"] == [
        {
            "output_type": "stream",
            "name": "stdout",
            "text": f"Hey {os.environ.get('USER', 'John Smith')} from {node()}.\n",
        }
    ]
    assert reply["status"] == "ok"

Check the response.

{"execution_count": 1, "outputs": [{"output_type": "stream", "name": "stdout", "text": "Hey echarles from eric.\n"}], "status": "ok"}

Instead of using the kernel client as context manager, you can call the start() and stop() methods.

from jupyter_kernel_client import JupyterKernelClient

kernel = JupyterKernelClient(server_url="http://localhost:8888", token="MY_TOKEN")
kernel.start()
reply = kernel.execute(code)
print(reply)
kernel.stop()

To connect to an existing Jupyter Kernel, first start JupyterLab, open a Notebook with a Kernel and take not of the Kernel ID.

TODO: Document how to get the Kernel ID.

make jupyterlab

You can now connect to the existing Kernel and run code (do not invoke stop).

from jupyter_kernel_client import JupyterKernelClient

kernel = JupyterKernelClient(server_url="http://localhost:8888", kernel_id="83ef59b7-9c78-40bd-8cc2-4447635e7d0b", token="MY_TOKEN")
kernel.start()
reply = kernel.execute("x=1")
print(reply)

Jupyter Konsole

Jupyter Konsole can be used to open a Console to a Kernel.

1. Install the optional dependencies.

pip install jupyter-kernel-client[konsole]

2. Start a Jupyter Server.

# make jupyter-server
jupyter server --port 8888 --ServerApp.port_retries 0 --IdentityProvider.token MY_TOKEN

3. Start the konsole and execute code.

# make jupyter-konsole
jupyter konsole --url http://localhost:8888 --token MY_TOKEN

[KonsoleApp] KernelHttpManager created a new kernel:...
Jupyter Konsole...

In [1]: 1+1
2

Uninstall

To remove the library, execute the following command.

pip uninstall jupyter_kernel_client

Contributing

Development install

# Clone the repo to your local environment
# Change directory to the jupyter_kernel_client directory
# Install package in development mode, this will automatically enable the server extension.
pip install -e ".[konsole,test,lint,typing]"

Running Tests

Install dependencies.

pip install -e ".[test]"

Run the python tests.

pytest

Development uninstall

pip uninstall jupyter_kernel_client

Packaging the library

See RELEASE