async-kernel 0.22.0__tar.gz → 0.22.1__tar.gz

{async_kernel-0.22.0 → async_kernel-0.22.1}/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.22.1] - 2026-08-18
+
+### <!-- 0 --> 🏗️ Breaking changes
+
+- Update zmq_poll docstrings. [#567](https://github.com/fleming79/async-kernel/pull/567)
+
+### <!-- 5 --> 📝 Documentation
+
+- ZMQPoll typing and doc fixes. [#568](https://github.com/fleming79/async-kernel/pull/568)
+
+### <!-- 6 --> 🌀 Miscellaneous
+
+- Refactor create_interface_messge_callback_handler to only use one connection [#569](https://github.com/fleming79/async-kernel/pull/569)
+
 ## [0.22.0] - 2026-08-17
 
 ### <!-- 0 --> 🏗️ Breaking changes
@@ -37,6 +51,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### <!-- 6 --> 🌀 Miscellaneous
 
+- Prepare for release v0.22.0 [#566](https://github.com/fleming79/async-kernel/pull/566)
+
 - Bump uv from 0.11.32 to 0.12.4 [#562](https://github.com/fleming79/async-kernel/pull/562)
 
 - Bump astral-sh/setup-uv from 9.0.0 to 10.0.1 in the actions group [#559](https://github.com/fleming79/async-kernel/pull/559)
@@ -1529,6 +1545,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Bump the actions group across 1 directory with 2 updates [#3](https://github.com/fleming79/async-kernel/pull/3)
 
+[0.22.1]: https://github.com/fleming79/async-kernel/compare/v0.22.0..v0.22.1
 [0.22.0]: https://github.com/fleming79/async-kernel/compare/v0.21.0..v0.22.0
 [0.21.0]: https://github.com/fleming79/async-kernel/compare/v0.20.2..v0.21.0
 [0.20.2]: https://github.com/fleming79/async-kernel/compare/v0.20.1..v0.20.2

{async_kernel-0.22.0 → async_kernel-0.22.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: async-kernel
-Version: 0.22.0
+Version: 0.22.1
 Summary: A concurrent python kernel for Jupyter supporting AnyIO, AsyncIO and Trio.
 Project-URL: Homepage, https://fleming79.github.io/async-kernel
 Project-URL: Documentation, https://fleming79.github.io/async-kernel

{async_kernel-0.22.0 → async_kernel-0.22.1}/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.22.0'
-__version_tuple__ = version_tuple = (0, 22, 0)
+__version__ = version = '0.22.1'
+__version_tuple__ = version_tuple = (0, 22, 1)
 
 __commit_id__ = commit_id = None

{async_kernel-0.22.0 → async_kernel-0.22.1}/src/async_kernel/caller.py

@@ -949,6 +949,7 @@ class Caller:
                 pass
         except IndexError:
             caller = self.get()
+            caller._name = f"async-kernel worker of {self.id}"
         pen = caller.call_soon(func, *args, **kwargs)
         pen.add_done_callback(_to_thread_on_done)
         return pen

{async_kernel-0.22.0 → async_kernel-0.22.1}/src/async_kernel/event_loop/zmq_poll.py

@@ -14,7 +14,7 @@ from typing import TYPE_CHECKING, Any, Literal, Self
 import zmq
 from aiologic import BinarySemaphore, BusyResourceError
 from typing_extensions import override
-from zmq.backend import zmq_poll
+from zmq.backend import zmq_poll as _zmq_poll
 
 from async_kernel import Caller, utils
 from async_kernel.common import Fixed
@@ -144,19 +144,30 @@ class ZMQPollSocket(zmq.sugar.Socket[bytes]):
             self.zmq_poll.execute(super().unsubscribe, topic)
 
 
-T_key = tuple[Any | ZMQPollSocket, int]
+T_key = tuple[ZMQPollSocket, int]
 
 
 class ZMQPoll:
     """A [zmq_poll](https://libzmq.readthedocs.io/en/latest/zmq_poll.html) based event loop.
 
-    This event loop is synchronous and is intended for quick message dispatch to separate threads
-    for handling. It provides thread-safe execution and manages its own custom sockets which use
-    the same executor for setting attributes and calling methods.
+    When a `(socket, flags) -> handler` mapping context manager is used [ZMQPoll.event_handler][]
+    `handler` is called with the socket and event when the event occurs on the socket. The
+    callback occurs in the zmq poll thread. [async_kernel.caller.Caller][] is recommended to
+    to scheduling code execution in different threads.
+
+    Only [ZMQPollSocket][] sockets created using the [ZMQPoll.socket][] factory function are
+    allowed.
+
+    The methods [ZMQPoll.execute][] and the async version [ZMQPoll.aexecute][] are provided
+    to executed code in the zmq_poll thread, which is useful when creating and configuring
+    sockets to reduce thread switching.
     """
 
     stopped: Fixed[Self, ProtectedPending] = Fixed(ProtectedPending)
+    """Set when the poll thread event has stopped."""
+
     sockets: Fixed[Self, set[ZMQPollSocket]] = Fixed(set)
+    """The sockets currently registered with this instance."""
 
     def __init__(self) -> None:
 
@@ -235,7 +246,7 @@ class ZMQPoll:
                 sock.recv()
 
             def do_execute() -> None:
-                """Execute pending items added by the `execute` and `execute_async` methods."""
+                """Execute pending items added by the `execute` and `aexecute` methods."""
                 while execute:
                     md = (pen := execute.popleft()).metadata
                     try:
@@ -244,15 +255,16 @@ class ZMQPoll:
                         pen.set_exception(e)
                     del pen
 
-            send = context.socket(zmq.SocketType.PAIR)
-            wake = context.socket(zmq.SocketType.PAIR)
+            send: ZMQPollSocket = context.socket(zmq.SocketType.PAIR)  # pyright: ignore[reportAssignmentType]
+            wake: ZMQPollSocket = context.socket(zmq.SocketType.PAIR)  # pyright: ignore[reportAssignmentType]
             addr = "inproc://async_kernel_zmq_poller_wake"
             sockets = None
             handlers[(wake, zmq.POLLIN)] = on_wake
 
             with context, wake, send, wake.bind(addr), send.connect(addr):
+                k: T_key
                 c: tuple[int, Callable] | None
-                started.set_result(send)  # pyright: ignore[reportArgumentType]
+                started.set_result(send)
                 # The main loop polls the handler keys for events in a loop.
                 # It will block until an event occurs.
                 try:
@@ -263,9 +275,9 @@ class ZMQPoll:
                             do_execute()
                             continue
                         try:
-                            for k in zmq_poll(sockets, timeout=-1):
+                            for k in _zmq_poll(sockets, timeout=-1):  # pyright: ignore[reportAssignmentType]
                                 try:
-                                    handlers[k](*k)  # pyright: ignore[reportArgumentType]
+                                    handlers[k](*k)
                                 except KeyError:
                                     sockets = None
                                 except SystemExit:
@@ -317,6 +329,7 @@ class ZMQPoll:
         self.log.debug("ZMQPoll event loop started")
 
     def validate_socket(self, sock: ZMQPollSocket | Any) -> ZMQPollSocket:
+        """Check `sock` is correctly registered."""
         if sock not in self.sockets:
             msg = f"Invalid socket detected! {sock=}"
             raise ValueError(msg)
@@ -334,7 +347,7 @@ class ZMQPoll:
         return self.validate_socket(self.execute(self._zmq_context.socket, socket_type))
 
     def execute(self, func: Callable[P, T], /, *args: P.args, **kwargs: P.kwargs) -> T:
-        """Execute `func` in the thread waiting for the result synchronously."""
+        """Execute `func` in the 'zmq_poll' thread waiting for the result synchronously."""
         if hasattr(self, "thread"):
             if threading.current_thread() is self.thread:
                 return func(*args, **kwargs)
@@ -346,17 +359,17 @@ class ZMQPoll:
                 finally:
                     pen.metadata.clear()
                     del pen
-        msg = f"Unable to execute {func=} in {self}. Execution is only support while in context."
+        msg = f"Unable to execute {func=} in {self}. Execution is only supported while in context."
         raise RuntimeError(msg)
 
-    async def execute_async(self, func: Callable[P, T], /, *args: P.args, **kwargs: P.kwargs) -> T:
-        """Execute `func` in the thread waiting for the result asynchronously."""
+    async def aexecute(self, func: Callable[P, T], /, *args: P.args, **kwargs: P.kwargs) -> T:
+        """Execute `func` in the 'zmq_poll' thread waiting for the result asynchronously."""
         if hasattr(self, "thread"):
             self._execute.append(pen := Pending[T](func=func, args=args, kwargs=kwargs))
             if not self.stopped.done():
                 self._wake()
                 return await pen
-        msg = f"Unable to execute {func=} in {self}. Execution is only support while in context."
+        msg = f"Unable to execute {func=} in {self}. Execution is only supported while in context."
         raise RuntimeError(msg)
 
     @contextmanager
@@ -370,14 +383,12 @@ class ZMQPoll:
         count: tuple[int, Callable[[], Any]] | None = None,
         canceller: Callable[[], Any] | NoValue | None = NoValue,
     ) -> Generator[None, Any, None]:
-        """A context manager where `handler` is called with the event number when it occurs for `sock`.
+        """A context manager where `handler` is called in the 'zmq_poll' thread with the event number when it occurs for `sock`.
 
-        Only one `handler` is allowed per `(socket, flags)` combination. If this context manager is entered
-        inside a caller managed task (call_soon, etc) and the ZMQPoll is stopped, the associated pending
-        will be cancelled.
+        Only one `handler` is allowed per `(socket, flags)` combination.
 
         Args:
-            sock: A zmq socket or a IO style object with a `fileno`.
+            sock: A registered [ZMQPollSocket][].
             handler: A handler to handle the event. The handler is called inside the
                 zmq_poll thread. Thread-safe primitives must be used by the handler such
                 as [async_kernel.caller.Caller.call_soon][],[async_kernel.caller.Caller.queue_call][], etc.
@@ -388,12 +399,16 @@ class ZMQPoll:
                 The callback could be an `event.set` to release the context.
             canceller: A callback to use on the event the poll is stopped. The default cancellation
                 behavior is to cancel the pending returned by [async_kernel.caller.Caller.current_pending][].
-                Set to None to disable cancellation support. This is fine when this context manager is inside
-                the context of this object.
+                Set to `None` to disable cancellation support. This is safe when this context manager is
+                inside the context of this instance.
+
+        Raises:
+            BusyResourceError: If the `(sock, flags)` combination is already in use.
+            RuntimeError: If the default canceller can not be created.
 
         Tip:
-            The handler is called inside a dedicated thread which may have been marked using
-            [async_kernel.utils.mark_thread_pydev_do_not_trace][] which disables debug breakpoints.
+            The zmq_poll thread normally disables debugging in the zmq_poll thread so inserting breakpoints
+            in the event handler may interfere with debugging.
         """
         assert not self.stopped.done()
         if canceller is NoValue:

{async_kernel-0.22.0 → async_kernel-0.22.1}/src/async_kernel/interface/base.py

@@ -184,9 +184,6 @@ class Interface(StartStopTask, Application, Generic[T_shell_co]):
     _connections: tuple[Connection[Self], ...] = ()
     """The connections to the interface for messaging."""
 
-    iopub_send_first_connection_only = traitlets.Bool(False).tag(config=True)
-    """Send iopub messages on the first connection only."""
-
     _connections_lock = Fixed(BinarySemaphore)
 
     shell: Fixed[Self, T_shell_co] = Fixed(lambda c: c["owner"].kernel.main_shell)
@@ -226,10 +223,6 @@ class Interface(StartStopTask, Application, Generic[T_shell_co]):
 
         return IPShell
 
-    @traitlets.default("iopub_send_first_connection_only")
-    def _default_iopub_send_first_connection_only(self) -> bool:
-        return sys.platform == "emscripten"
-
     @classmethod
     @override
     def initialized(cls) -> bool:
@@ -490,8 +483,6 @@ class Interface(StartStopTask, Application, Generic[T_shell_co]):
         for c in self._connections:
             try:
                 c.iopub_send(msg_type, content, metadata=metadata, parent=parent, ident=ident, buffers=buffers)
-                if self.iopub_send_first_connection_only:
-                    break
             except Exception as e:
                 self.log.exception("iopub_send failed for connection %r", c, exc_info=e)
 

{async_kernel-0.22.0 → async_kernel-0.22.1}/src/async_kernel/interface/callable.py

@@ -79,38 +79,39 @@ def create_interface_messge_callback_handler(
     pack_unpack: tuple[Callable[[Message], T], Callable[[T], Message]] = (pack_json_str, unpack_json),
 ) -> Callable[[T, BuffersType], None]:
     ""
-    cache: dict[str, Connection] = {}
+    conn: Connection | None = None
     lock = BinarySemaphore()
     session_calls = set()
     pack, unpack = pack_unpack
 
     def handle_msg(packed_msg: T, buffers: BuffersType | None = None) -> None:
         """Handle a packed message."""
+        nonlocal conn
         msg: Message = unpack(packed_msg)
         msg["buffers"] = [] if buffers is None else buffers
         session: str = msg["header"]["session"]
         session_calls.add(session)
-        conn: Connection | None
 
-        if (conn := cache.get(session)) is None or conn.stopping.done():
+        if conn is None:
             with lock:
-                if (conn := cache.get(session)) is None or conn.stopping.done():
+                if conn is None:
                     conn = Connection(interface.caller, session_id=session)
 
-                    def transmit_msg(msg: Message, ident: list[bytes]) -> None:
+                    def transmit_msg(msg: Message, ident: list[bytes], conn=conn) -> None:
                         """Pack and send a message."""
-                        # `ident` is not sent.
+                        # Jupyterlite
+                        if parent := msg["parent_header"]:
+                            msg["header"]["session"] = parent["session"]
+
                         buffers: BuffersType = msg.pop("buffers")  # pyright: ignore[reportAssignmentType]
                         reply = send(pack(msg), buffers, blocking_reply := msg["channel"] == Channel.stdin)
                         if blocking_reply:
-                            conn.handle_incoming_msg(unpack(reply), [conn.bsession])
+                            conn.handle_incoming_msg(unpack(reply), [])
 
                     conn.transmit_msg = transmit_msg
                     conn.stopped.add_done_callback(lambda _: delattr(conn, "transmit_msg"))
                     conn.start()
-                    conn.stopping.add_done_callback(lambda _: cache.pop(session))
 
-                    cache[session] = conn
-        conn.handle_incoming_msg(msg, [conn.bsession])
+        conn.handle_incoming_msg(msg, [])
 
     return handle_msg

{async_kernel-0.22.0 → async_kernel-0.22.1}/src/async_kernel/messaging/base.py

@@ -74,9 +74,6 @@ class BaseMessage(StartStopTask, LoggingConfigurable, MessageProtocol):
     session_id: Fixed[Self, str] = Fixed(lambda c: c["owner"]._session_id)
     """Used to identify this object as the `session` in a message header."""
 
-    bsession: Fixed[Self, bytes] = Fixed[Self, bytes](lambda c: c["owner"].session_id.encode())
-    """Used to identfiy this object as the origin of a message."""
-
     _pending_messages: Fixed[Self, dict[str, PendingMessage[Any]]] = Fixed(dict)
     """A mapping of the `msg_id` of message requests to the pending that is resolved with a reply."""
 
@@ -201,6 +198,13 @@ class Connection(HasInterface[T_interface_co], BaseMessage, Generic[T_interface_
 
     @override
     def handle_incoming_msg(self, msg: Message, ident: list[bytes]) -> None:
+        """The handler for  messages received on this connection.
+
+        Args:
+            msg: A new message.
+            ident: A list of bytes to route a reply message back to the origin. This can
+                be an empty list when there is only one connection, such as [LocalClient][].
+        """
         if msg["header"]["msg_type"].endswith("_reply"):
             self.handle_reply(msg)
         else:

{async_kernel-0.22.0 → async_kernel-0.22.1}/src/async_kernel/messaging/zmq.py

@@ -211,7 +211,7 @@ class ZMQConnection(ZMQMessage, Connection[T_interface_co], Generic[T_interface_
                 self._sockets[channel] = socket
                 socket.bind(addr)
 
-        await self.zmq_poll.execute_async(bind_sockets)
+        await self.zmq_poll.aexecute(bind_sockets)
 
     @override
     def connection_info(self) -> str:
@@ -277,7 +277,7 @@ class ZMQClient(BaseClient[T_interface_co], ZMQMessage, Generic[T_interface_co])
                 self._sockets[channel] = socket
             return socket
 
-        return await self.zmq_poll.execute_async(open_socket)
+        return await self.zmq_poll.aexecute(open_socket)
 
     async def _establish_connection(self, timeout: float | None) -> None:
         # Wait for welcome

{async_kernel-0.22.0 → async_kernel-0.22.1}/tests/test_callable_interface.py

@@ -35,9 +35,7 @@ async def test_start_kernel_callable_interface(anyio_backend: Backend):
         messages.append(msg)
         return None
 
-    callable_interface = await start_kernel_callable_interface(
-        send=from_interface, stopped=stopped.set, settings={"Interface.iopub_send_first_connection_only": True}
-    )
+    callable_interface = await start_kernel_callable_interface(send=from_interface, stopped=stopped.set)
     interface = Interface.instance()
     async with LocalClient().start() as client:
         await client.kernel_info()

{async_kernel-0.22.0 → async_kernel-0.22.1}/tests/test_eventloop_zmq_poll.py

@@ -158,15 +158,15 @@ class Test_zmq_Poll:
 
     async def test_poll_execute_states(self, caller: Caller):
         zmq_poll = ZMQPoll()
-        match = "Execution is only support while in context"
+        match = "Unable to execute"
         # Pre-running
         with pytest.raises(RuntimeError, match=match):
             zmq_poll.execute(lambda: 1 + 1)
         with pytest.raises(RuntimeError, match=match):
-            await zmq_poll.execute_async(lambda: 1 + 1)
+            await zmq_poll.aexecute(lambda: 1 + 1)
         # Running
         with zmq_poll:
-            assert (await zmq_poll.execute_async(lambda: 1 + 1)) == 2
+            assert (await zmq_poll.aexecute(lambda: 1 + 1)) == 2
             assert (zmq_poll.execute(lambda: 1 + 1)) == 2
         with pytest.raises(RuntimeError, match="stopped"), zmq_poll:
             None  # noqa: B018  # pyright: ignore[reportUnusedExpression]
@@ -174,11 +174,11 @@ class Test_zmq_Poll:
         with pytest.raises(RuntimeError, match=match):
             assert zmq_poll.execute(threading.current_thread) is zmq_poll.thread
         with pytest.raises(RuntimeError, match=match):
-            assert await zmq_poll.execute_async(threading.current_thread) is zmq_poll.thread
+            assert await zmq_poll.aexecute(threading.current_thread) is zmq_poll.thread
 
     async def test_poll_socket_states(self, caller: Caller):
         zmq_poll = ZMQPoll()
-        match = "Execution is only support while in context"
+        match = "Unable to execute"
         # Pre-running
         with pytest.raises(RuntimeError, match=match):
             zmq_poll.socket(zmq.SocketType.DEALER)