Client (Notebook)¶

A client communicates with a kernel either locally in the same process, or remotely using sockets. The interface provides connections to the kernel, to which a client can connect.

LocalClient¶

A local client can be used in the same process to communicate with the kernel. A local client is used in JupyterLite to pass comms to the Jupyterfrontend. It may also be convenient to use a LocalClient for running tests.

In [2]:

# task
# We run this code block as a task to avoid deadlock as the client execute would be queued behind this request.
from async_kernel.messaging import LocalClient

async with LocalClient().start() as client:
    reply = await client.execute("a=1+1", user_expressions={"a": "a"})
reply

# task # We run this code block as a task to avoid deadlock as the client execute would be queued behind this request. from async_kernel.messaging import LocalClient async with LocalClient().start() as client: reply = await client.execute("a=1+1", user_expressions={"a": "a"}) reply

Out[2]:

{'channel': <Channel.shell: 'shell'>,
 'header': {'date': datetime.datetime(2026, 9, 18, 5, 14, 42, 796930, tzinfo=datetime.timezone.utc),
  'msg_id': '5e17f686-1c72-447e-b3cc-252baa29d82d',
  'msg_type': 'execute_reply',
  'session': '0d3723f6-c898-40dc-b658-f119de4cbdcf',
  'username': '',
  'version': '5.5'},
 'parent_header': {'date': datetime.datetime(2026, 9, 18, 5, 14, 42, 792864, tzinfo=datetime.timezone.utc),
  'msg_id': 'bff9e0cb-7482-4384-9e5c-7e9b3eb2b8fd',
  'msg_type': <MsgType.execute_request: 'execute_request'>,
  'session': '0d3723f6-c898-40dc-b658-f119de4cbdcf',
  'username': '',
  'version': '5.5'},
 'content': {'status': 'ok',
  'execution_count': 2,
  'user_expressions': {'a': {'status': 'ok',
    'data': {'text/plain': '2'},
    'metadata': {}}}},
 'metadata': {},
 'buffers': []}

ZMQClient¶

A ZMQClient communicates using zmq sockets meaning it can communicate with a kernel on the network.

Let's start a new kernel and get the kernel info.

In [3]:

from async_kernel.messaging.zmq import ZMQClient

client = ZMQClient()
async with client.subprocess_kernel(name="my_kernel"):
    reply = await client.kernel_info()
reply

from async_kernel.messaging.zmq import ZMQClient client = ZMQClient() async with client.subprocess_kernel(name="my_kernel"): reply = await client.kernel_info() reply

Out[3]:

{'header': {'msg_id': '8005f634-46e6-46a4-b676-b5d5af17d542_2780_7',
  'msg_type': 'kernel_info_reply',
  'username': 'runner',
  'session': '8005f634-46e6-46a4-b676-b5d5af17d542',
  'date': datetime.datetime(2026, 9, 18, 5, 14, 43, 176335, tzinfo=tzutc()),
  'version': '5.5'},
 'msg_id': '8005f634-46e6-46a4-b676-b5d5af17d542_2780_7',
 'msg_type': 'kernel_info_reply',
 'parent_header': {'msg_id': '9d7a7672-a49b-4403-9b3d-69b1e0e36a5d_2765_2',
  'msg_type': 'kernel_info_request',
  'username': 'runner',
  'session': '9d7a7672-a49b-4403-9b3d-69b1e0e36a5d',
  'date': datetime.datetime(2026, 9, 18, 5, 14, 43, 175777, tzinfo=tzutc()),
  'version': '5.5'},
 'metadata': {},
 'content': {'status': 'ok',
  'kernel_name': 'my_kernel',
  'protocol_version': '5.5',
  'implementation': 'async-kernel',
  'implementation_version': '0.23.1',
  'language_info': {'name': 'python',
   'version': '3.12.3',
   'mimetype': 'text/x-python',
   'codemirror_mode': {'name': 'ipython', 'version': 3},
   'pygments_lexer': 'ipython3',
   'nbconvert_exporter': 'python',
   'file_extension': '.py'},
  'banner': "Python 3.12.3 (main, Jul 15 2026, 23:46:41) [GCC 13.3.0]\nasync-kernel v0.23.1 name='my_kernel' backend='asyncio' host=None\nIPython shell 9.17.1\nTip: You can change the editing mode of IPython to behave more like vi, or emacs.\n",
  'help_links': [{'text': 'Async Kernel Reference ',
    'url': 'https://fleming79.github.io/async-kernel/'},
   {'text': 'IPython Reference',
    'url': 'https://ipython.readthedocs.io/en/stable/'},
   {'text': 'IPython magic Reference',
    'url': 'https://ipython.readthedocs.io/en/stable/interactive/magics.html'},
   {'text': 'Matplotlib ipympl Reference',
    'url': 'https://matplotlib.org/ipympl/'},
   {'text': 'Matplotlib Reference',
    'url': 'https://matplotlib.org/contents.html'}],
  'debugger': True,
  'supported_features': ['kernel subshells', 'debugger']},
 'buffers': [],
 'channel': <Channel.shell: 'shell'>}