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

{async_kernel-0.20.2 → async_kernel-0.22.0}/.github/workflows/ci.yml

@@ -20,12 +20,12 @@ jobs:
           fetch-depth: 0
 
       - name: Install uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
 
       - name: Type checking with basedpyright
         run: |
           uv sync
-          uvx basedpyright@1.39.8
+          uvx basedpyright@1.39.9
 
   test:
     needs: type-checking
@@ -45,7 +45,7 @@ jobs:
         uses: actions/checkout@v7
 
       - name: Install uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           version-file: "pyproject.toml"
           python-version: ${{ matrix.python-version }}
@@ -71,7 +71,7 @@ jobs:
         if: ${{runner.debug == '1'}}
         timeout-minutes: 3
         run: |
-          uv run pytest -vvl --override-ini=log_cli_level=DEBUG --override-ini=log_cli=true
+          uv run pytest -vvl --override-ini=log_cli_level=DEBUG
 
       - name: Run tests
         if: ${{runner.debug != '1'}}
@@ -87,7 +87,7 @@ jobs:
           fetch-depth: 0
 
       - name: Install uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           version-file: "pyproject.toml"
           python-version: "3.13"
@@ -116,7 +116,7 @@ jobs:
           fetch-depth: 0
 
       - name: Install uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           version-file: "pyproject.toml"
 

{async_kernel-0.20.2 → async_kernel-0.22.0}/.github/workflows/new_release.yml

@@ -31,7 +31,7 @@ jobs:
           fetch-depth: 0
           ref: main
       - name: Install uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           version-file: "pyproject.toml"
 

{async_kernel-0.20.2 → async_kernel-0.22.0}/.github/workflows/pre-commit.yml

@@ -8,7 +8,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
-      - uses: actions/setup-python@v6
+      - uses: actions/setup-python@v7
         with:
           python-version: 3.x
       - uses: pre-commit/action@v3.0.1

{async_kernel-0.20.2 → async_kernel-0.22.0}/.github/workflows/publish-docs.yml

@@ -27,7 +27,7 @@ jobs:
           git config user.email 41898282+github-actions[bot]@users.noreply.github.com
 
       - name: Install uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           version-file: "pyproject.toml"
 

{async_kernel-0.20.2 → async_kernel-0.22.0}/.github/workflows/publish-to-pypi.yml

@@ -31,7 +31,7 @@ jobs:
           # Fetch full history for setuptools-scm
           fetch-depth: 0
           ref: main
-      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           version-file: "pyproject.toml"
 

{async_kernel-0.20.2 → async_kernel-0.22.0}/.pre-commit-config.yaml

@@ -28,15 +28,15 @@ repos:
       - id: check-json5
 
   - repo: https://github.com/python-jsonschema/check-jsonschema
-    rev: 0.37.3
+    rev: 0.38.0
     hooks:
       - id: check-github-workflows
 
   - repo: https://github.com/rbubley/mirrors-prettier
-    rev: v3.8.4
+    rev: v3.9.6
     hooks:
       - id: prettier
-        types_or: [yaml, html, json]
+        types_or: [yaml, html, json, toml]
       - id: prettier
         types_or: [markdown]
         args: ["--tab-width", "4"]
@@ -48,7 +48,7 @@ repos:
         additional_dependencies: [black==23.7.0]
 
   - repo: https://github.com/codespell-project/codespell
-    rev: v2.4.2
+    rev: v2.4.3
     hooks:
       - id: codespell
         args: ["-L", "sur,nd"]
@@ -59,7 +59,7 @@ repos:
       - id: python-use-type-annotations
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.15.19
+    rev: v0.16.3
     hooks:
       - id: ruff-check
         types_or: [python, jupyter]
@@ -68,7 +68,7 @@ repos:
         types_or: [python, jupyter]
 
   - repo: https://github.com/scientific-python/cookie
-    rev: 2026.06.18
+    rev: 2026.08.14
     hooks:
       - id: sp-repo-review
         additional_dependencies: ["repo-review[cli]"]

{async_kernel-0.20.2 → async_kernel-0.22.0}/.vscode/settings.json

@@ -18,5 +18,8 @@
     "tag:yaml.org,2002:python/object/apply:pymdownx.slugs.slugify mapping"
   ],
   "spellright.language": ["en"],
-  "spellright.documentTypes": ["markdown", "plaintext"]
+  "spellright.documentTypes": ["markdown", "plaintext"],
+  "[toml]": {
+    "editor.defaultFormatter": "tamasfe.even-better-toml"
+  }
 }

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

@@ -5,7 +5,115 @@ 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.20.2] - 2026-06-29
+## [0.22.0] - 2026-08-17
+
+### <!-- 0 --> 🏗️ Breaking changes
+
+- Major interface refactoring, new features and capabilities [#538](https://github.com/fleming79/async-kernel/pull/538)
+
+### <!-- 1 --> 🚀 Features
+
+- Add ShieldedTask. [#553](https://github.com/fleming79/async-kernel/pull/553)
+
+- Change caller async context manager to be first in last out, intermediate contexts are not managed. [#549](https://github.com/fleming79/async-kernel/pull/549)
+
+- Add ProtectedPending to prevent accidental propagation of cancellation of a cancelled waiter. [#546](https://github.com/fleming79/async-kernel/pull/546)
+
+- Add cancellation support in ZMQPoll. [#541](https://github.com/fleming79/async-kernel/pull/541)
+
+- Rename Poll to ZMQPoll and add ZMQPollSocket [#539](https://github.com/fleming79/async-kernel/pull/539)
+
+- Caller async context management changes [#537](https://github.com/fleming79/async-kernel/pull/537)
+
+- Split BaseInterface into BaseMessageApplication [#536](https://github.com/fleming79/async-kernel/pull/536)
+
+### <!-- 2 --> 🐛 Fixes
+
+- Fix heartbeat [#532](https://github.com/fleming79/async-kernel/pull/532)
+
+### <!-- 5 --> 📝 Documentation
+
+- Use Ruff lint pydocstyle [#531](https://github.com/fleming79/async-kernel/pull/531)
+
+### <!-- 6 --> 🌀 Miscellaneous
+
+- 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)
+
+- Pre-commit autoupdate and update uv.lock. [#565](https://github.com/fleming79/async-kernel/pull/565)
+
+- Fix pyright type hinting of NoValue. [#564](https://github.com/fleming79/async-kernel/pull/564)
+
+- Rename ShieldedTask to StartStopTask. [#557](https://github.com/fleming79/async-kernel/pull/557)
+
+- More features fro ShieldedTask. [#556](https://github.com/fleming79/async-kernel/pull/556)
+
+- Compatibility fix with ipython. [#555](https://github.com/fleming79/async-kernel/pull/555)
+
+- Change ShieldedTask to use set_task_function to set the function and caller to avoid clashing when used as a mixin. [#554](https://github.com/fleming79/async-kernel/pull/554)
+
+- Refactor Pending._set_done. [#552](https://github.com/fleming79/async-kernel/pull/552)
+
+- Refactor Pending._set_done. [#551](https://github.com/fleming79/async-kernel/pull/551)
+
+- Improve Caller auto shutdown support [#550](https://github.com/fleming79/async-kernel/pull/550)
+
+- Make Caller a bit safer for shutdown where it's context is held inside a pending task. [#548](https://github.com/fleming79/async-kernel/pull/548)
+
+- Improve caller shutdown management and tests [#547](https://github.com/fleming79/async-kernel/pull/547)
+
+- Bump astral-sh/setup-uv from 8.3.2 to 9.0.0 in the actions group [#544](https://github.com/fleming79/async-kernel/pull/544)
+
+- ZMQPoll support multiple context entry and re-entry. [#545](https://github.com/fleming79/async-kernel/pull/545)
+
+- Improve kernel shutdown. [#543](https://github.com/fleming79/async-kernel/pull/543)
+
+- More Messge types and general fixes. [#542](https://github.com/fleming79/async-kernel/pull/542)
+
+- Improve ZMQPollSocket autoclose. [#540](https://github.com/fleming79/async-kernel/pull/540)
+
+- Fix the ident of input request messages. [#535](https://github.com/fleming79/async-kernel/pull/535)
+
+- Bump the actions group with 2 updates [#533](https://github.com/fleming79/async-kernel/pull/533)
+
+- Improve uv magic. [#534](https://github.com/fleming79/async-kernel/pull/534)
+
+## [0.21.0] - 2026-07-19
+
+### <!-- 1 --> 🚀 Features
+
+- Add print_concat to concatenate print statements into a single string when 'file' is not specified. [#522](https://github.com/fleming79/async-kernel/pull/522)
+
+- Added PollZMQ - a thread based zmq poller callback registry. [#515](https://github.com/fleming79/async-kernel/pull/515)
+
+- Support loop_factory as an importable path. [#514](https://github.com/fleming79/async-kernel/pull/514)
+
+### <!-- 6 --> 🌀 Miscellaneous
+
+- Prepare for release v0.21.0 [#530](https://github.com/fleming79/async-kernel/pull/530)
+
+- Poll maintenance [#529](https://github.com/fleming79/async-kernel/pull/529)
+
+- Add threadsafe option to Poll.socket [#528](https://github.com/fleming79/async-kernel/pull/528)
+
+- Update lock files and pre-commit and basedpyright. [#527](https://github.com/fleming79/async-kernel/pull/527)
+
+- Kernel updates - handle external kernel interrupt. [#526](https://github.com/fleming79/async-kernel/pull/526)
+
+- Add docstrings for Poll [#525](https://github.com/fleming79/async-kernel/pull/525)
+
+- Bump astral-sh/setup-uv from 8.2.0 to 8.3.0 in the actions group [#518](https://github.com/fleming79/async-kernel/pull/518)
+
+- Change PollZMQ to Poll and move to event_loop/zmq_poll.py. [#524](https://github.com/fleming79/async-kernel/pull/524)
+
+- Add more log messages when running pytest from the command line. [#523](https://github.com/fleming79/async-kernel/pull/523)
+
+- Move OutStream from kernel.py to outstream.py [#521](https://github.com/fleming79/async-kernel/pull/521)
+
+- Refactor Caller. [#520](https://github.com/fleming79/async-kernel/pull/520)
+
+## [0.20.2] - 2026-06-30
 
 ### <!-- 5 --> 📝 Documentation
 
@@ -13,6 +121,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### <!-- 6 --> 🌀 Miscellaneous
 
+- Prepare for release v0.20.2 [#512](https://github.com/fleming79/async-kernel/pull/512)
+
 - Avoid attribute error in Comm.publish_msg in case the parent is gc before the object. [#511](https://github.com/fleming79/async-kernel/pull/511)
 
 - Update uv.lock and pre-commit-config.yaml [#510](https://github.com/fleming79/async-kernel/pull/510)
@@ -1419,6 +1529,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.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
 [0.20.1]: https://github.com/fleming79/async-kernel/compare/v0.20.0..v0.20.1
 [0.20.0]: https://github.com/fleming79/async-kernel/compare/v0.19.2..v0.20.0

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: async-kernel
-Version: 0.20.2
+Version: 0.22.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
@@ -36,7 +36,7 @@ Requires-Python: >=3.11
 Requires-Dist: aiologic>=0.17.0
 Requires-Dist: anyio>=4.12
 Requires-Dist: comm>=0.2
-Requires-Dist: ipython>=9.0
+Requires-Dist: ipython>=9.16.1
 Requires-Dist: jupyter-client>=8.9.1; sys_platform != 'emscripten'
 Requires-Dist: jupyter-core>=5.9.1
 Requires-Dist: matplotlib-inline>0.1
@@ -62,22 +62,24 @@ Description-Content-Type: text/markdown
 
 ![logo-svg](https://github.com/user-attachments/assets/6781ec08-94e9-4640-b8f9-bb07a08e9587)
 
-async-kernel is a Python kernel for [Jupyter](https://docs.jupyter.org/en/latest/projects/kernels.html#kernels-programming-languages)
-that provides concurrent message handling via an asynchronous backend (asyncio or trio).
+async-kernel provides Python [Jupyter](https://docs.jupyter.org/en/latest/projects/kernels.html#kernels-programming-languages) kernels and clients
+compatible with CPython (Jupyter & VS code) and Pyodide (Jupyterlite).
 
-The kernel provides two external interfaces:
+The kernel interface supports multiple connections including:
 
-1. Direct ZMQ socket messaging via a configuration file and kernel spec - (Jupyter, VS Code, etc).
-2. An experimental callback style interface (Jupyterlite).
+1. Messaging via ZMQ sockets (Jupyter, VS Code, etc).
+2. Same-process local client enabling (Jupyterlite) and user access.
 
 ## Highlights
 
+- Built using [aiologic](https://aiologic.readthedocs.io/latest/) thread-safe synchronisation primitives.
+- The [`Caller`](https://fleming79.github.io/async-kernel/latest/reference/caller/#async_kernel.caller.Caller)
+  class provides a powerful but simple interface for cross-thread code execution in asyncio and trio
+  backends, with guest event loop support built in.
+- A zmq poll event loop for thread-safe zmq sockets.
 - [IPython shell](https://ipython.readthedocs.io/en/stable/overview.html#enhanced-interactive-python-shell)
     - top-level await ('asyncio' or 'trio' backend) in cells
     - async magic function support 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)
 - Per-subshell user_ns
 - GUI event loops [^1]
     - [x] inline
@@ -88,6 +90,8 @@ The kernel provides two external interfaces:
   [Jupyterlite](https://github.com/jupyterlite/jupyterlite) (try it online [here](https://fleming79.github.io/echo-kernel/) 👈)
     - `%pip install` magic (using micropip)
 - [Debugger client](https://jupyterlab.readthedocs.io/en/latest/user/debugger.html#debugger)
+- Local client.
+- ZMQ client.
 
 [^1]:
     A gui (_host_) enabled kernel interface starts a gui's mainloop (host) which starts
@@ -100,55 +104,6 @@ The kernel provides two external interfaces:
 
 [^3]: trio's [start_guest_run](https://trio.readthedocs.io/en/stable/reference-lowlevel.html#trio.lowlevel.start_guest_run).
 
-### Avoid deadlocks
-
-The standard (synchronous) kernel implementation processes messages sequentially irrespective
-of the message type. The problem being that long running execute requests make the kernel non-responsive.
-
-Another problem exists when an asynchronous execute request awaits a result that is delivered
-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 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
-
-Make a blocking call in a Jupyter lab notebook or console.
-
-```python
-# Make the shell's thread busy
-import time
-
-time.sleep(1e6)
-```
-
-While the above is _blocking_ (the kernel is _busy_).
-
-```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
-    'widget coms over subshells'. Widget messages arrive in a different thread which on
-    occasion can cause unexpected behaviour, especially when using asynchronous libraries.
-
 ## Installation
 
 ```bash

{async_kernel-0.20.2 → async_kernel-0.22.0}/README.md

@@ -11,22 +11,24 @@
 
 ![logo-svg](https://github.com/user-attachments/assets/6781ec08-94e9-4640-b8f9-bb07a08e9587)
 
-async-kernel is a Python kernel for [Jupyter](https://docs.jupyter.org/en/latest/projects/kernels.html#kernels-programming-languages)
-that provides concurrent message handling via an asynchronous backend (asyncio or trio).
+async-kernel provides Python [Jupyter](https://docs.jupyter.org/en/latest/projects/kernels.html#kernels-programming-languages) kernels and clients
+compatible with CPython (Jupyter & VS code) and Pyodide (Jupyterlite).
 
-The kernel provides two external interfaces:
+The kernel interface supports multiple connections including:
 
-1. Direct ZMQ socket messaging via a configuration file and kernel spec - (Jupyter, VS Code, etc).
-2. An experimental callback style interface (Jupyterlite).
+1. Messaging via ZMQ sockets (Jupyter, VS Code, etc).
+2. Same-process local client enabling (Jupyterlite) and user access.
 
 ## Highlights
 
+- Built using [aiologic](https://aiologic.readthedocs.io/latest/) thread-safe synchronisation primitives.
+- The [`Caller`](https://fleming79.github.io/async-kernel/latest/reference/caller/#async_kernel.caller.Caller)
+  class provides a powerful but simple interface for cross-thread code execution in asyncio and trio
+  backends, with guest event loop support built in.
+- A zmq poll event loop for thread-safe zmq sockets.
 - [IPython shell](https://ipython.readthedocs.io/en/stable/overview.html#enhanced-interactive-python-shell)
     - top-level await ('asyncio' or 'trio' backend) in cells
     - async magic function support 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)
 - Per-subshell user_ns
 - GUI event loops [^1]
     - [x] inline
@@ -37,6 +39,8 @@ The kernel provides two external interfaces:
   [Jupyterlite](https://github.com/jupyterlite/jupyterlite) (try it online [here](https://fleming79.github.io/echo-kernel/) 👈)
     - `%pip install` magic (using micropip)
 - [Debugger client](https://jupyterlab.readthedocs.io/en/latest/user/debugger.html#debugger)
+- Local client.
+- ZMQ client.
 
 [^1]:
     A gui (_host_) enabled kernel interface starts a gui's mainloop (host) which starts
@@ -49,55 +53,6 @@ The kernel provides two external interfaces:
 
 [^3]: trio's [start_guest_run](https://trio.readthedocs.io/en/stable/reference-lowlevel.html#trio.lowlevel.start_guest_run).
 
-### Avoid deadlocks
-
-The standard (synchronous) kernel implementation processes messages sequentially irrespective
-of the message type. The problem being that long running execute requests make the kernel non-responsive.
-
-Another problem exists when an asynchronous execute request awaits a result that is delivered
-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 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
-
-Make a blocking call in a Jupyter lab notebook or console.
-
-```python
-# Make the shell's thread busy
-import time
-
-time.sleep(1e6)
-```
-
-While the above is _blocking_ (the kernel is _busy_).
-
-```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
-    'widget coms over subshells'. Widget messages arrive in a different thread which on
-    occasion can cause unexpected behaviour, especially when using asynchronous libraries.
-
 ## Installation
 
 ```bash

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

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

{async_kernel-0.20.2 → async_kernel-0.22.0}/docs/notebooks/caller.ipynb

@@ -13,9 +13,9 @@
    "source": [
     "# Caller: A backend agnostic executor (notebook)\n",
     "\n",
-    "_This notebook has the Python dependencies: `trio`, `matplotlib`_\n",
+    "_This notebook uses `trio` in some cells._\n",
     "\n",
-    "`Caller` is a thread-local class that coordinates the execution of functions and coroutines in the event loop of a `asyncio` or `trio` backend."
+    "`Caller` is a thread-local object that coordinates the execution of functions and coroutines in the event loop of an `asyncio` or `trio` backend."
    ]
   },
   {
@@ -36,13 +36,13 @@
    "source": [
     "A `Caller` instance can be started with one gui as a host to one backend started as a guest. \n",
     "\n",
-    "A second backend can also be started in the same thread with or without a host gui event loop.\n",
+    "A second backend can also be started in the same thread/caller with or without a host gui event loop.\n",
     "Potentially the same thread could have up to:\n",
     "\n",
     "- One host gui event loop (`tk`, `qt`, `...`)\n",
     "- Two asynchronous backends (`asyncio`, `trio`)\n",
     "\n",
-    "It should be noted that gui's generally assume/require their mainloop runs in the main thread."
+    "It should be noted that gui's generally assume/require that their mainloop runs in the main thread."
    ]
   },
   {
@@ -74,7 +74,7 @@
    "id": "5",
    "metadata": {},
    "source": [
-    "There are two caller instances associated with the Kernel:\n",
+    "There are two caller instances associated with the kernel interface:\n",
     "\n",
     "- Shell: The caller for the shell channel (normally the MainThread).\n",
     "- Control: The caller for the control channel (a child of the shell)."
@@ -109,12 +109,11 @@
    "source": [
     "## Modifiers\n",
     "\n",
-    "There are four modifiers that determine which instance is returned when calling `Caller`.\n",
+    "There are three modifiers that can change the instance that is returned when calling `Caller`.\n",
     "\n",
     "- `CurrentThread` (default): Access the caller that belongs to the current thread (or context with Pyodide).\n",
     "- `MainThread`: Access main thread for the Caller.\n",
-    "- `NewThread`: Create a new thread.\n",
-    "- `manual`: Manually create a new instance for the current thread (must be started manually)."
+    "- `NewThread`: Create a new thread."
    ]
   },
   {
@@ -186,9 +185,11 @@
    "source": [
     "## Caller.get\n",
     "\n",
-    "`Caller.get` is a method to get an instance of a `Caller` by name, passing the same name will return the same caller on subsequent calls.\n",
-    "The same [options](#caller-creation-options) for creation of a new `Caller` can be specified. Calling `caller.get()` with no `name` will always return a\n",
-    "new instance of a `Caller`."
+    "`Caller.get` is a method to obtain a _child_ instance of a `Caller` by name. \n",
+    "Passing the same name on the same caller will return the same child caller on subsequent calls.\n",
+    "The same [options](#caller-creation-options) for creation of a new `Caller` can be specified. \n",
+    "Calling `caller.get()` with no `name` will always return a new instance of a `Caller`. All children\n",
+    "of a caller will stop when the parent stops."
    ]
   },
   {
@@ -319,7 +320,7 @@
     "\n",
     "### Caller.queue_call\n",
     "\n",
-    "This method is used extensively by the kernel for message handling. Each time the `queue_call` is called with the same function the function and call arguments are appended to a queue. On the first call a task is started in the backend to process the queue as items are added. The task remains alive until the function is deleted or the queue is stopped. Any exceptions that occur are logged."
+    "This method is used extensively by the kernel for message handling. Each time the `queue_call` is called with the same function, the function and call arguments are appended to a queue. On the first call a task is started in the backend to process the queue as items are added. The task remains alive until the function is deleted or the queue is stopped. Any exceptions that occur are logged."
    ]
   },
   {
@@ -338,7 +339,7 @@
     "def f(n):\n",
     "    float(n)\n",
     "    done.down()\n",
-    "    print(done)\n",
+    "    print(done.value, \"Pending id:\", id(Caller.current_pending()))\n",
     "\n",
     "\n",
     "for i in range(N):\n",
@@ -413,13 +414,11 @@
     "import random\n",
     "import time\n",
     "\n",
-    "import anyio\n",
     "import ipywidgets as ipw\n",
     "\n",
     "outputs = {}\n",
     "stop = ipw.RadioButtons(value=None, options=[\"Stop\"])\n",
     "box = ipw.VBox([stop])\n",
-    "await anyio.sleep(0.2)\n",
     "display(box)\n",
     "\n",
     "\n",
@@ -476,13 +475,14 @@
    "source": [
     "## Caller.create_pending_group\n",
     "\n",
-    "A `PendingGroup` is an asynchronous context manager for for `Pending`. All pending that 'opt-in' when created are added to the pending group (`Caller` methods that return `Pending` 'opt-in').\n",
+    "A `PendingGroup` is an asynchronous context manager for `Pending`. All pending that 'opt-in' when created are added to the pending group (`Caller` methods that return `Pending` 'opt-in').\n",
     "\n",
     "The `PendingGroup` has different modes:\n",
     "\n",
-    "- 0: Ignore cancellation of pending.\n",
+    "- 0: Ignore cancellation of pending, if any pending is cancelled - exit quietly.\n",
     "- 1: Cancel if any pending is cancelled - raise PendingCancelled on exit.\n",
-    "- 2: Cancel if any pending is cancelled - exit quietly."
+    "- 2: Cancel if any pending is cancelled - exit quietly.\n",
+    "- 3: Ignore cancellation of pending, if any pending is cancelled - raise PendingCancelled on exit."
    ]
   },
   {