jellycell.run.kernel

Subprocess Jupyter kernel wrapper (spec §2.5).

Thin wrapper around :class:jupyter_client.KernelManager + BlockingKernelClient. Subprocess only — in-process is a premature optimization and a footgun.

Module Contents

Classes

CellExecution	Structured result of executing one cell’s source.
Kernel	A subprocess Jupyter kernel, usable as a context manager.

API

class jellycell.run.kernel.CellExecution

Structured result of executing one cell’s source.

status: str

‘ok’

"ok" or "error".

outputs: list[dict[str, Any]]

‘field(…)’

Normalized iopub outputs (see :func:parse_iopub_message).

execution_count: int | None

None

class jellycell.run.kernel.Kernel(kernel_name: str = 'python3')

A subprocess Jupyter kernel, usable as a context manager.

Initialization

start() → None

Spawn the subprocess and wait for it to become ready.

stop() → None

Shut down the kernel subprocess. Idempotent.

is_alive() → bool

Return True if the kernel subprocess is still running.

Thin wrapper over :meth:KernelManager.is_alive so callers don’t have to reach into private attributes. Used after a timeout to distinguish a hung kernel (alive but not responding) from a dead one (crashed, OOM-killed).

interrupt() → None

Send a SIGINT to the kernel to break out of a running cell.

Used by the Runner after a wall-clock timeout so the kernel can be reused without shutting it down; on Linux this is a real SIGINT, on Windows it’s a CTRL_C_EVENT via the jupyter-client shim. No-op if the kernel isn’t alive.

execute(source: str, *, timeout: float = 600.0) → jellycell.run.kernel.CellExecution

Run source in the kernel; return structured outputs.

Accumulates iopub messages until the kernel reports idle or the wall-clock timeout elapses. On timeout, returns status=error with a synthetic error output whose evalue carries diagnostics about what messages we did / didn’t see — helps distinguish a genuine long-running cell from a hung kernel (CI flake). Does NOT wait for the kernel to finish; the caller may want to

Meth:

interrupt or :meth:stop it.