or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

client-communication.mdconnection-management.mdindex.mdkernel-management.mdkernel-provisioning.mdkernel-specifications.mdsession-messaging.md
tile.json

tessl/pypi-jupyter-client

Jupyter protocol implementation and client libraries for kernel communication and management

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/jupyter-client@8.6.x

To install, run

npx @tessl/cli install tessl/pypi-jupyter-client@8.6.0

index.mddocs/

Jupyter Client

Jupyter Client provides the reference implementation of the Jupyter protocol and essential client and kernel management APIs for working with Jupyter kernels. It serves as the foundational communication layer between Jupyter frontends (like JupyterLab, Notebook) and computational kernels, handling message passing, kernel lifecycle management, and protocol compliance.

Package Information

  • Package Name: jupyter-client
  • Language: Python
  • Installation: pip install jupyter-client

Core Imports

import jupyter_client

Common patterns for working with kernels:

from jupyter_client import KernelManager, BlockingKernelClient
from jupyter_client import AsyncKernelManager, AsyncKernelClient
from jupyter_client import MultiKernelManager

For connection utilities:

from jupyter_client import find_connection_file, write_connection_file

For kernel launching:

from jupyter_client import launch_kernel

Basic Usage

from jupyter_client import KernelManager

# Create and start a kernel
km = KernelManager()
km.start_kernel()

# Create a client to communicate with the kernel
kc = km.client()
kc.start_channels()

# Execute code
msg_id = kc.execute("print('Hello, World!')")

# Get the result
reply = kc.get_shell_msg()
print(reply['content'])

# Clean up
kc.stop_channels()
km.shutdown_kernel()

Architecture

Jupyter Client is built around several key components:

  • Kernel Management: KernelManager and MultiKernelManager classes handle kernel lifecycle
  • Client Communication: KernelClient classes provide APIs for sending messages to kernels
  • Connection Infrastructure: Connection file management and network setup utilities
  • Provisioning System: Pluggable kernel provisioning with local and remote implementations
  • Protocol Implementation: Complete Jupyter protocol message handling and authentication

The library supports both synchronous (blocking) and asynchronous communication patterns, making it suitable for various integration scenarios from simple scripts to complex distributed systems.

Capabilities

Kernel Management

Single and multi-kernel lifecycle management including starting, stopping, restarting, and monitoring kernels. Supports both synchronous and asynchronous operations.

class KernelManager:
    def start_kernel(self, **kwargs): ...
    def shutdown_kernel(self, now=False, restart=False): ...
    def restart_kernel(self, now=False, **kwargs): ...
    def interrupt_kernel(self): ...
    def is_alive(self): ...
    def client(self, **kwargs) -> BlockingKernelClient: ...

class AsyncKernelManager(KernelManager):
    def client(self, **kwargs) -> AsyncKernelClient: ...

class MultiKernelManager:
    def start_kernel(self, kernel_name=None, **kwargs) -> str: ...
    def shutdown_kernel(self, kernel_id, now=False, restart=False): ...
    def get_kernel(self, kernel_id) -> KernelManager: ...
    def list_kernel_ids(self) -> list: ...

Kernel Management

Client Communication

Kernel communication clients for executing code, sending messages, and receiving results. Provides both blocking and asynchronous interfaces for different usage patterns.

class KernelClient:
    def execute(self, code, silent=False, store_history=True, **kwargs) -> str: ...
    def complete(self, code, cursor_pos=None) -> str: ...
    def inspect(self, code, cursor_pos=None, detail_level=0) -> str: ...
    def history(self, **kwargs) -> str: ...
    def kernel_info(self) -> str: ...
    def is_complete(self, code) -> str: ...
    def shutdown(self, restart=False) -> str: ...
    def start_channels(self, **kwargs): ...
    def stop_channels(self): ...

class BlockingKernelClient(KernelClient):
    def get_shell_msg(self, **kwargs) -> dict: ...
    def get_iopub_msg(self, **kwargs) -> dict: ...
    def wait_for_ready(self, timeout=None): ...
    def is_alive(self) -> bool: ...

class AsyncKernelClient(KernelClient):
    async def get_shell_msg(self, **kwargs) -> dict: ...
    async def get_iopub_msg(self, **kwargs) -> dict: ...
    async def wait_for_ready(self, timeout=None): ...
    async def is_alive(self) -> bool: ...

Client Communication

Connection Management

Connection file handling, port management, and network configuration for kernel connections. Includes utilities for SSH tunneling and connection discovery.

def write_connection_file(fname=None, shell_port=0, iopub_port=0, 
                         stdin_port=0, hb_port=0, control_port=0, 
                         ip='', key=b'', transport='tcp', **kwargs) -> tuple: ...

def find_connection_file(filename='kernel-*.json', path=None) -> str: ...

def tunnel_to_kernel(connection_info, sshserver, sshkey=None) -> tuple: ...

class ConnectionFileMixin:
    def load_connection_file(self, connection_file=None): ...
    def get_connection_info(self, session=False) -> dict: ...
    def cleanup_connection_file(self): ...

Connection Management

Kernel Provisioning

Pluggable kernel provisioning system for starting kernels in different environments. Supports local subprocess provisioning and extensible remote provisioning.

class KernelProvisionerBase:
    @property
    def has_process(self) -> bool: ...
    async def poll(self) -> int | None: ...
    async def wait(self) -> int | None: ...
    async def send_signal(self, signum): ...
    async def kill(self, restart=False): ...
    async def terminate(self, restart=False): ...
    async def launch_kernel(self, cmd, **kwargs) -> dict: ...

class LocalProvisioner(KernelProvisionerBase):
    # Local subprocess implementation
    ...

class KernelProvisionerFactory:
    def create_provisioner_instance(self, kernel_id, kernel_spec, parent): ...
    def get_provisioner_entries(self) -> dict: ...

Kernel Provisioning

Session and Messaging

Jupyter protocol message handling, serialization, authentication, and session management. Provides complete protocol implementation with signing and security features.

class Session:
    def msg(self, msg_type, content=None, parent=None, **kwargs) -> dict: ...
    def sign(self, msg_list) -> bytes: ...
    def serialize(self, msg, ident=None) -> list: ...
    def deserialize(self, msg_list, content=True, copy=True) -> dict: ...
    def send(self, socket, msg_or_type, content=None, **kwargs): ...
    def recv(self, socket, mode=0, content=True, copy=True) -> dict: ...
    def clone(self) -> Session: ...

def msg_header(msg_id, msg_type, username, session, **kwargs) -> dict: ...
def extract_header(msg_or_header) -> dict: ...

Session and Messaging

Kernel Specifications

Kernel specification discovery, installation, and management. Handles kernel.json files and kernel discovery across system and user directories.

class KernelSpec:
    @classmethod
    def from_resource_dir(cls, resource_dir) -> KernelSpec: ...
    def to_dict(self) -> dict: ...
    def to_json(self) -> str: ...

class KernelSpecManager:
    def find_kernel_specs(self) -> dict: ...
    def get_kernel_spec(self, kernel_name) -> KernelSpec: ...
    def get_all_specs(self) -> dict: ...
    def install_kernel_spec(self, source_dir, kernel_name=None, **kwargs) -> str: ...
    def remove_kernel_spec(self, name) -> str: ...

def find_kernel_specs() -> dict: ...
def get_kernel_spec(kernel_name) -> KernelSpec: ...
def install_kernel_spec(source_dir, **kwargs) -> str: ...

Kernel Specifications

Types

# Connection information dictionary
KernelConnectionInfo = Dict[str, Union[int, str, bytes]]

# Version information
from jupyter_client import __version__, version_info
from jupyter_client import protocol_version, protocol_version_info

# Exception types
class DuplicateKernelError(Exception): ...
class NoSuchKernel(KeyError): ...
class InvalidPortNumber(Exception): ...