jupyasyncclient

jupyasyncclient is an async Python client for running code on Jupyter kernels. It connects to servers that implement the standard kernels API, including rustygate, jupygate, and jupyter_server.

Kernel creation, interruption, restart, and deletion use HTTP. Each client exchanges messages over one websocket. Sends await the websocket transport. The client does not depend on zmq or tornado.

Three classes provide jupyter_client-style interfaces:

• JupyAsyncKernelClient manages one kernel’s lifecycle, channels, and messages.
• JupyAsyncKernelManager starts and stops one kernel and creates clients for it.
• JupyAsyncMultiKernelManager manages multiple kernels. ensure_kernel('some-key') returns the live kernel registered under that key or starts one.

The core notebook builds the client bottom-up and demonstrates every method against a live server. The managers are HTTP wrappers in plain modules. Two other notebooks cover gateway APIs:

• term demonstrates JupyAsyncTerminalClient for gateway-hosted terminals.
• files builds JupyAsyncFilesClient and JupyAsyncCellsClient over the files and cells APIs. It includes apply_ops for updating a local view from a kernel’s change broadcasts.

JupyAsyncCellsClient.view returns selected cells with the current notebook path and requested metadata. cells returns the selected cell list. Both accept a filename or a kernel binding through the client constructor.

Install

pip install jupyasyncclient

You also need a kernel server. These examples use rustygate serving ipymini kernels. The test suite also runs against a stock jupyter_server.

Use

The client’s execute, complete, inspect, history, kernel_info, and wait_for_ready methods follow their jupyter_client namesakes. Choose how to receive execution results:

• execute sends without waiting for a reply.
• reply awaits one execute_reply.
• run collects every message caused by an execution.

Every inbound message also reaches the on_jmsg callback once, in receive order, after request routing. The callback can be synchronous or asynchronous. The reader awaits it before taking the next message. Do not await replies on the same websocket from the callback. JmsgQueues provides queues for applications that need to pull the same messages instead.

Every protocol *_request type is callable by name and returns an awaitable for its reply. This includes subshell requests. New protocol messages do not require a client release.

Messages are standard Jupyter dictionaries with a channel key. The server handles zmq-specific behaviour, including sync-send edge consumption, slow-joiner subscriptions, and socket identity.

import asyncio
from rustygate.tools import start_gateway

g = start_gateway()
g

<Gateway http://127.0.0.1:60487 pid=47781 up>

start_new_server_kernel starts a kernel and returns its manager and a ready client. This example uses a single jmsg queue for iopub and stdin messages:

km, kc = await start_new_server_kernel(g.url)
qs = JmsgQueues(kc, queues=('jmsg',), merge=dict(iopub='jmsg', stdin='jmsg'))
rep = await kc.reply("print('hello'); 6*7", timeout=30)
rep['content']['status']

'ok'

Kernel output arrives on the iopub channel. Read the stream message from the queue:

m = await qs.jmsg_for('stream', timeout=15)
m['content']['text']

'hello\n'

Calling input() in the kernel produces an input_request on the stdin channel. Answer with the client’s input method. It sets the reply’s parent to the request:

fut = asyncio.ensure_future(kc.reply("name = input('who? ')", timeout=30))
prompt = await qs.jmsg_for('input_request', timeout=15)
kc.input('Jeremy')
(await fut)['content']['status']

'ok'

Call protocol requests by name and await their replies. This example creates and deletes a JEP 91 subshell:

sub = (await kc.create_subshell(timeout=15))['content']['subshell_id']
rep = await kc.reply('40+2', timeout=30, subshell_id=sub)
await kc.delete_subshell(sub, timeout=15)
rep['content']['status']

'ok'

Use the multimanager to keep a kernel for each named task. Repeated calls to ensure_kernel with the same key reuse its live kernel:

mkm = JupyAsyncMultiKernelManager(g.url)
k1 = await mkm.ensure_kernel('analysis')
k2 = await mkm.ensure_kernel('analysis')
k1 == k2

True

await kc.aclose()
await km.shutdown_kernel()
await mkm.shutdown_all()

Pass token=... to any of the three classes when the server requires a bearer token. HTTP requests send it in the Authorization header. Websocket connections send it as a query parameter.