Jupyter Client

Warnings

• breaking Jupyter Client 7.0 introduced significant internal API changes for `KernelManager` and `AsyncKernelManager`. Methods like `pre_start_kernel`, `_launch_kernel`, `_kill_kernel`, and `finish_shutdown` had their signatures or return types altered. While primarily affecting subclasses, these changes can impact custom kernel managers.
  Fix: Review the `Migration Guide` in the official documentation for detailed changes if you have custom `KernelManager` or `AsyncKernelManager` subclasses. Adjust method signatures and logic according to the new API.
• breaking With Jupyter Client 7.0, `AsyncKernelClient` methods (e.g., `get_shell_msg`, `get_iopub_msg`, `get_stdin_msg`, `get_control_msg`) no longer accept the `block: bool = True` keyword argument. These methods are now purely asynchronous.
  Fix: For asynchronous operations, remove the `block=True` argument and ensure proper `await` calls within an `asyncio` event loop. For blocking behavior, use `jupyter_client.blocking.BlockingKernelClient`.
• gotcha Reliably receiving all messages from a kernel, especially output streams (IOPub), can be challenging. Developers often miss messages or get stuck in infinite loops if message processing and timeout handling are not robustly implemented.
  Fix: Implement explicit loops to fetch messages with appropriate timeouts (`get_iopub_msg(timeout=...)`) and handle `queue.Empty` exceptions. Continuously poll until an 'idle' status message is received or a specific reply is confirmed. Refer to the quickstart example for a basic pattern.
• gotcha Improper management of kernel lifecycles can lead to zombie processes, leaked resources, or stale connection files. Failing to shut down kernels and stop client channels can consume system resources.
  Fix: Always ensure that `kc.stop_channels()` and `km.shutdown_kernel()` are called, preferably within a `finally` block or context manager, to guarantee proper resource cleanup.

Install

• pip install jupyter-client Install jupyter-client

Imports

• KernelManager

  from jupyter_client import KernelManager

• AsyncKernelManager

  from jupyter_client.manager import AsyncKernelManager

• BlockingKernelClient

  from jupyter_client.blocking import BlockingKernelClient

• find_connection_file

  from jupyter_client import find_connection_file

Quickstart

This quickstart demonstrates how to programmatically start a Jupyter kernel, execute Python code, and capture its output using `jupyter_client`'s blocking API. It initializes a `KernelManager`, obtains a `BlockingKernelClient`, and sends code for execution, then processes the incoming messages until the kernel returns to an idle state. Remember to call `stop_channels()` and `shutdown_kernel()` for proper cleanup.

import time
from jupyter_client import KernelManager
from queue import Empty

def main():
    # Start a Python kernel
    km = KernelManager(kernel_name='python3')
    km.start_kernel()

    # Get a blocking client to interact with the kernel
    kc = km.client(blocking=True)
    kc.start_channels()

    try:
        # Ensure the client is connected and ready
        kc.wait_for_ready(timeout=60)

        # Execute some code
        code = 'print("Hello from Jupyter Kernel!")\na = 10\nprint(f"a is {a}")'
        msg_id = kc.execute(code)

        # Process IOPub messages until execution state is idle or timeout
        while True:
            try:
                msg = kc.get_iopub_msg(timeout=1)
                msg_type = msg['msg_type']
                content = msg['content']

                if msg_type == 'stream' and content['name'] == 'stdout':
                    print(f"[Kernel Output]: {content['text'].strip()}")
                elif msg_type == 'status' and content['execution_state'] == 'idle':
                    print("[Kernel Status]: Idle")
                    break
            except Empty:
                # No messages in queue, continue waiting for idle status
                continue
            except Exception as e:
                print(f"Error receiving IOPub message: {e}")
                break

    finally:
        # Clean up: stop channels and shut down the kernel
        kc.stop_channels()
        km.shutdown_kernel()
        print("Kernel shutdown complete.")

if __name__ == '__main__':
    main()