async-kernel 0.13.2__tar.gz → 0.14.0__tar.gz

{async_kernel-0.13.2 → async_kernel-0.14.0}/CHANGELOG.md

@@ -5,6 +5,42 @@ 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.14.0] - 2026-03-24
+
+### <!-- 0 --> 🏗️ Breaking changes
+
+- Rename loop to host and Loop to Hosts [#370](https://github.com/fleming79/async-kernel/pull/370)
+
+### <!-- 5 --> 📝 Documentation
+
+- Update event loop documentation. [#372](https://github.com/fleming79/async-kernel/pull/372)
+
+- Update readme [#371](https://github.com/fleming79/async-kernel/pull/371)
+
+## [0.13.3] - 2026-03-23
+
+### <!-- 0 --> 🏗️ Breaking changes
+
+- Housekeeping [#365](https://github.com/fleming79/async-kernel/pull/365)
+
+- General maintenance [#361](https://github.com/fleming79/async-kernel/pull/361)
+
+### <!-- 6 --> 🌀 Miscellaneous
+
+- Prepare for release v0.13.3 [#369](https://github.com/fleming79/async-kernel/pull/369)
+
+- Minor SingleConsumerAsyncQueue optimization. [#368](https://github.com/fleming79/async-kernel/pull/368)
+
+- Fixtest_command_start_kernel_enable_matplotlib [#367](https://github.com/fleming79/async-kernel/pull/367)
+
+- Substitute control thread for shell-hidden thread and limit subshell handler to execute_requests [#366](https://github.com/fleming79/async-kernel/pull/366)
+
+- Refactor ZMQKernelInterface [#364](https://github.com/fleming79/async-kernel/pull/364)
+
+- Simplify CommManager and Comm - the Kernel is now Fixed [#363](https://github.com/fleming79/async-kernel/pull/363)
+
+- Access kernel from shell where it is available for AsyncDisplayPublisher and KernelMagics [#362](https://github.com/fleming79/async-kernel/pull/362)
+
 ## [0.13.2] - 2026-03-15
 
 ### <!-- 0 --> 🏗️ Breaking changes
@@ -21,6 +57,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### <!-- 6 --> 🌀 Miscellaneous
 
+- Prepare for release v0.13.2 [#360](https://github.com/fleming79/async-kernel/pull/360)
+
 - Prevent signal interrupt when the debugger is paused [#359](https://github.com/fleming79/async-kernel/pull/359)
 
 - Pre-commit and uv.lock update [#358](https://github.com/fleming79/async-kernel/pull/358)
@@ -999,6 +1037,8 @@ 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.14.0]: https://github.com/fleming79/async-kernel/compare/v0.13.3..v0.14.0
+[0.13.3]: https://github.com/fleming79/async-kernel/compare/v0.13.2..v0.13.3
 [0.13.2]: https://github.com/fleming79/async-kernel/compare/v0.13.1..v0.13.2
 [0.13.1]: https://github.com/fleming79/async-kernel/compare/v0.13.0..v0.13.1
 [0.13.0]: https://github.com/fleming79/async-kernel/compare/v0.12.5..v0.13.0

{async_kernel-0.13.2 → async_kernel-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: async-kernel
-Version: 0.13.2
+Version: 0.14.0
 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
@@ -71,6 +71,7 @@ The kernel provides two external interfaces:
 ## Highlights
 
 - [IPython shell](https://ipython.readthedocs.io/en/stable/overview.html#enhanced-interactive-python-shell)
+    - top-level await ('asyncio' or 'trio' backend) in cells
 - [anyio](https://pypi.org/project/anyio/) compatible asynchronous backend ([`asyncio`](https://docs.python.org/3/library/asyncio.html) (default) or [`trio`](https://pypi.org/project/trio/))
 - [aiologic](https://aiologic.readthedocs.io/latest/) thread-safe synchronisation primitives
 - [Backend agnostic multi-thread / multi-event loop management](https://fleming79.github.io/async-kernel/latest/reference/caller/#async_kernel.caller.Caller)
@@ -85,9 +86,8 @@ The kernel provides two external interfaces:
 - [Debugger client](https://jupyterlab.readthedocs.io/en/latest/user/debugger.html#debugger)
 
 [^1]:
-    A gui (_host_) enabled kernel runs a gui event loop with the asynchronous backend
-    running as guest. The host must be set before the kernel is started. This was a
-    deliberate design choice to to ensure good performance and reliability.
+    A gui (_host_) enabled kernel interface starts a gui's mainloop (host) which starts
+    the backend as a guest, then finally the Kernel is started.
 
 [^2]:
     The asyncio implementation of `start_guest_run` was written by
@@ -105,24 +105,40 @@ Another problem exists when an asynchronous execute request awaits a result that
 via a kernel message - this will cause a deadlock because the message will be stuck in the queue behind
 the _blocking_ execute request[^5].
 
-async-kernel handles messages according to the channel, message type and subshell id. So widget com message
+async-kernel handles messages according to the channel and message type. So widget com message
 will get processed in a separate queue to an execute request. Further detail is given in the [concurrency notebook](https://fleming79.github.io/async-kernel/latest/notebooks/concurrency/), a Jupyterlite version is available [here](https://fleming79.github.io/echo-kernel/).
 
 #### Example
 
-Try the following using a standard kernel and then try it with async-kernel.
+Make a blocking call in a Jupyter lab notebook or console.
 
 ```python
-# Make the shell thread busy
+# Make the shell's thread busy
 import time
 
 time.sleep(1e6)
 ```
 
-Try the following in another cell:
+While the above is _blocking_ (the kernel is _busy_).
 
-- code completion (`tab`)
-- docstring (`shift tab`)
+```python
+dir()  # try code completion (tab) or view the docstring (shift tab)
+```
+
+Interrupt the kernel.
+
+It also works for awaitables.
+
+```python
+import ipywidgets as ipw
+from aiologic import Event
+
+b = ipw.Button(description="Click me")
+event = Event()
+b.on_click(lambda _: event.set())
+display(b)
+await event
+```
 
 [^5]:
     IPyKernel _solves_ this issue specifically for widgets by using the concept of
@@ -165,11 +181,11 @@ The kernel can be started with a gui event loop as the _host_ and the _backend_
 
 ```bash
 # tk
-async-kernel -a async-tk --interface.loop=tk
+async-kernel -a async-tk --interface.host=tk
 
 # qt
 pip install PySide6-Essentials
-async-kernel -a async-qt --interface.loop=qt
+async-kernel -a async-qt --interface.host=qt
 ```
 
 #### trio backend
@@ -177,11 +193,11 @@ async-kernel -a async-qt --interface.loop=qt
 ```bash
 pip install trio
 # tk
-async-kernel -a async-tk --interface.loop=tk --interface.backend=trio
+async-kernel -a async-tk --interface.host=tk --interface.backend=trio
 
 # qt
 pip install PySide6-Essentials
-async-kernel -a async-qt --interface.loop=qt --interface.backend=trio
+async-kernel -a async-qt --interface.host=qt --interface.backend=trio
 ```
 
 For further detail about kernel spec customisation see [command line and kernel configuration](https://fleming79.github.io/async-kernel/latest/usage/commands/).

{async_kernel-0.13.2 → async_kernel-0.14.0}/README.md

@@ -22,6 +22,7 @@ The kernel provides two external interfaces:
 ## Highlights
 
 - [IPython shell](https://ipython.readthedocs.io/en/stable/overview.html#enhanced-interactive-python-shell)
+    - top-level await ('asyncio' or 'trio' backend) in cells
 - [anyio](https://pypi.org/project/anyio/) compatible asynchronous backend ([`asyncio`](https://docs.python.org/3/library/asyncio.html) (default) or [`trio`](https://pypi.org/project/trio/))
 - [aiologic](https://aiologic.readthedocs.io/latest/) thread-safe synchronisation primitives
 - [Backend agnostic multi-thread / multi-event loop management](https://fleming79.github.io/async-kernel/latest/reference/caller/#async_kernel.caller.Caller)
@@ -36,9 +37,8 @@ The kernel provides two external interfaces:
 - [Debugger client](https://jupyterlab.readthedocs.io/en/latest/user/debugger.html#debugger)
 
 [^1]:
-    A gui (_host_) enabled kernel runs a gui event loop with the asynchronous backend
-    running as guest. The host must be set before the kernel is started. This was a
-    deliberate design choice to to ensure good performance and reliability.
+    A gui (_host_) enabled kernel interface starts a gui's mainloop (host) which starts
+    the backend as a guest, then finally the Kernel is started.
 
 [^2]:
     The asyncio implementation of `start_guest_run` was written by
@@ -56,24 +56,40 @@ Another problem exists when an asynchronous execute request awaits a result that
 via a kernel message - this will cause a deadlock because the message will be stuck in the queue behind
 the _blocking_ execute request[^5].
 
-async-kernel handles messages according to the channel, message type and subshell id. So widget com message
+async-kernel handles messages according to the channel and message type. So widget com message
 will get processed in a separate queue to an execute request. Further detail is given in the [concurrency notebook](https://fleming79.github.io/async-kernel/latest/notebooks/concurrency/), a Jupyterlite version is available [here](https://fleming79.github.io/echo-kernel/).
 
 #### Example
 
-Try the following using a standard kernel and then try it with async-kernel.
+Make a blocking call in a Jupyter lab notebook or console.
 
 ```python
-# Make the shell thread busy
+# Make the shell's thread busy
 import time
 
 time.sleep(1e6)
 ```
 
-Try the following in another cell:
+While the above is _blocking_ (the kernel is _busy_).
 
-- code completion (`tab`)
-- docstring (`shift tab`)
+```python
+dir()  # try code completion (tab) or view the docstring (shift tab)
+```
+
+Interrupt the kernel.
+
+It also works for awaitables.
+
+```python
+import ipywidgets as ipw
+from aiologic import Event
+
+b = ipw.Button(description="Click me")
+event = Event()
+b.on_click(lambda _: event.set())
+display(b)
+await event
+```
 
 [^5]:
     IPyKernel _solves_ this issue specifically for widgets by using the concept of
@@ -116,11 +132,11 @@ The kernel can be started with a gui event loop as the _host_ and the _backend_
 
 ```bash
 # tk
-async-kernel -a async-tk --interface.loop=tk
+async-kernel -a async-tk --interface.host=tk
 
 # qt
 pip install PySide6-Essentials
-async-kernel -a async-qt --interface.loop=qt
+async-kernel -a async-qt --interface.host=qt
 ```
 
 #### trio backend
@@ -128,11 +144,11 @@ async-kernel -a async-qt --interface.loop=qt
 ```bash
 pip install trio
 # tk
-async-kernel -a async-tk --interface.loop=tk --interface.backend=trio
+async-kernel -a async-tk --interface.host=tk --interface.backend=trio
 
 # qt
 pip install PySide6-Essentials
-async-kernel -a async-qt --interface.loop=qt --interface.backend=trio
+async-kernel -a async-qt --interface.host=qt --interface.backend=trio
 ```
 
 For further detail about kernel spec customisation see [command line and kernel configuration](https://fleming79.github.io/async-kernel/latest/usage/commands/).

{async_kernel-0.13.2 → async_kernel-0.14.0}/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.13.2'
-__version_tuple__ = version_tuple = (0, 13, 2)
+__version__ = version = '0.14.0'
+__version_tuple__ = version_tuple = (0, 14, 0)
 
 __commit_id__ = commit_id = None

{async_kernel-0.13.2 → async_kernel-0.14.0}/docs/notebooks/caller.ipynb

@@ -34,7 +34,7 @@
    "id": "2",
    "metadata": {},
    "source": [
-    "A `Caller` instance can can be started with one gui as a host to one backend started as a guest. \n",
+    "A `Caller` instance can be started with one gui as a host to one backend started as a guest. \n",
     "A second backend can also be started in the same thread with or without a host gui event loop.\n",
     "Potentially the same thread could have up to:\n",
     "\n",

{async_kernel-0.13.2 → async_kernel-0.14.0}/docs/notebooks/concurrency.ipynb

@@ -13,18 +13,32 @@
    "source": [
     "# Concurrent message handling (notebook)\n",
     "\n",
-    "async-kernel provides a separate message handler for each:\n",
+    "async-kernel is capable of concurrent message handling. It provides a separate message handler for each channel and msg_type.\n",
     "\n",
-    "- channel\n",
-    "- msg_type\n",
-    "- subshell_id\n",
+    "As messages are received they are queued for execution by the message handler.\n",
     "\n",
-    "As messages are received they are queued for execution by the message handler using `queue_call` on a `Caller`. \n",
+    "## Callers\n",
+    "\n",
+    "async-kernel provides two `Callers` for the _shell_ and _control_ channels. The shell's `Caller` is \n",
+    "associated with the thread where the kernel is started, normally this is the _MainThread_. \n",
+    "In CPython, the `Caller` for the _control_ channel is started as a child of the shell caller with \n",
+    "it's own thread and asynchronous backend ('asyncio' or 'trio').\n",
+    "\n",
+    "## ZMQ message handling (CPython)\n",
+    "\n",
+    "The kernel interface also starts two additional threads dedicated to receive the messages on \n",
+    "the  _shell_ and _control_ channels, the specific function call is `session.recv(socket, mode=zmq.BLOCKY, copy=False)`. \n",
+    "\n",
+    "Each thread blocks until a new message is received on the zmq socket. When a message is received, \n",
+    "the kernel's `message_handler` is called with detail of the message (Job), the channel and a function\n",
+    "that is to be used to send the response corresponding to the message. The `message_handler` obtains \n",
+    "the dedicated handler according to the `message_type`, `run_mode`, `channel` and `subshell_id` and \n",
+    "schedules execution of the dedicated message handler in `Caller's` thread. \n",
     "\n",
     "## Shell messaging\n",
     "\n",
-    "Both `execute_request` and `com_msg` are run in the shell's thread (normally the MainThread).\n",
-    "All other messages on the shell channel are run in a separate _hidden thread_ \"Shell-hidden\".\n",
+    "Both `execute_request` and `com_msg` are always run in the shell's thread (normally the _MainThread_).\n",
+    "All other messages on the shell channel are run in the control thread.\n",
     "\n",
     "## Control messaging\n",
     "\n",

async_kernel-0.14.0/docs/reference/event_loop.md

@@ -0,0 +1,9 @@
+::: async_kernel.event_loop.run
+
+::: async_kernel.event_loop.tk_host.TkHost
+options:
+show_root_heading: true
+
+::: async_kernel.event_loop.qt_host.QtHost
+options:
+show_root_heading: true

{async_kernel-0.13.2 → async_kernel-0.14.0}/docs/usage/commands.md

@@ -31,7 +31,7 @@ The kernel spec looks like this:
         "--start_interface=async_kernel.interface.start_kernel_zmq_interface",
         "--kernel_name=async",
         "--backend=trio",
-        "--loop=tk"
+        "--host=tk"
     ],
     "env": {},
     "display_name": "Async python tk trio",
@@ -53,8 +53,8 @@ A single kernel spec is created in the folder `<sys.prefix>/share/jupyter/kernel
 - display_name: 'async'
 - backend: `asyncio`
 - backend_options: `{'use_uvloop':True}` if uvloop or winloop is installed
-- loop: `None`
-- loop_options: `None`
+- host: `None`
+- host_options: `None`
 
 The kernel spec can be updated by adding a kernel spec with the same name ('async').
 
@@ -63,8 +63,8 @@ The kernel spec can be updated by adding a kernel spec with the same name ('asyn
 There are two supported backends 'asyncio' and 'trio'.
 
 In CPython the [backend][async_kernel.typing.Backend] is started using [anyio.run][].
-The type of backend can be specified at the attribute [`interface.backend`][async_kernel.interface.BaseKernelInterface.backend].
-The backend_options can be specified at the attribute [`interface.backend_options'][async_kernel.interface.zmq.ZMQKernelInterface.backend_options].
+The type of backend can be specified at the attribute [interface.backend][async_kernel.interface.BaseKernelInterface.backend].
+The backend_options can be specified at the attribute [interface.backend_options][async_kernel.interface.zmq.ZMQKernelInterface.backend_options].
 Options can be written as a literal python string.
 
 ```console
@@ -78,7 +78,7 @@ searches for the kernel specs.
 
 The path where the kernel spec is installed/deleted can also be specified by either `prefix` or `folder`.
 
-**options**
+**Options**
 
 - prefix (optional): the prefix to use with `PREFIX/share/jupyter/kernels` (defaults is [sys.prefix][]).
 - folder (optional) the full path to the `kernels` folder.
@@ -110,39 +110,39 @@ Below are some example kernel specs for host and backend kernel specs.
 
 ```console
 # tk host asyncio backend
-async-kernel -a async-tk --interface.loop=tk
+async-kernel -a async-tk --interface.host=tk
 
 # tk host trio backend
-async-kernel -a async-tk --interface.loop=tk --backend=trio
+async-kernel -a async-tk --interface.host=tk --backend=trio
 ```
 
 ### qt
 
 ```console
 # qt host asyncio backend
-async-kernel -a async-qt --interface.loop=qt
+async-kernel -a async-qt --interface.host=qt
 
 # qt host trio backend
-async-kernel -a async-qt-trio --interface.loop=qt --interface.backend=trio
+async-kernel -a async-qt-trio --interface.host=qt --interface.backend=trio
 
-# PySide6 is default.  You can specify a different module via `loop_options`
-async-kernel -a async-qt --interface.loop=qt --interface.loop_options={'module':'PySide2'}
+# PySide6 is default.  You can specify a different module via `host_options`
+async-kernel -a async-qt --interface.host=qt --interface.host_options={'module':'PySide2'}
 ```
 
-## Loop options
+## Host options
 
-Options can be provided to configure how a loop loads. There are only a few options available
+Options can be provided to configure how a host loads. There are only a few options available
 at present.
 
 - `host_class' `[type[Host| str]]` : A customised subclass of a [Host][async_kernel.event_loop.run.Host]
   or a dotted import path to the customised Host.
-- `'module': The module name on which to base the event loop. (Only applies to 'qt').
+- `'module': The module name on which to base the event loop. (Only applies to [qt][async_kernel.event_loop.qt_host.QtHost]).
 
 ## Backend options
 
 Options can be provided for how the backend is started.
 
-- With a (gui) loop: Options for `start_guest_run`
+- With a (gui) host: Options for `start_guest_run`
     - [trio.lowlevel.start_guest_run][]
     - asyncio
         - host_uses_signal_set_wakeup_fd
@@ -151,11 +151,11 @@ Options can be provided for how the backend is started.
         - task_factory,
         - context,
         - debug,
-- Without a (gui) loop: `backend_options` in [anyio.run][]
+- Without a (gui) host: `backend_options` in [anyio.run][]
 
 ```console
 # If uvloop is installed it will be used by default. You can do this to disable it.
-async-kernel -a async "--interface.loop_options={'use_uvloop':False}"
+async-kernel -a async "--interface.host_options={'use_uvloop':False}"
 ```
 
 ### Custom arguments

{async_kernel-0.13.2 → async_kernel-0.14.0}/pyproject.toml

@@ -95,8 +95,8 @@ dev = [
   {include-group = "test"},
 ]
 gui = [
-    "matplotlib>=3.10.8",
     "pyside6-essentials>=6.10.2",
+    {include-group = "docs"},
 ]
 
 [tool.hatch.version]