click-async-plugins 0.7.3__tar.gz

click_async_plugins-0.7.3/.github/workflows/python-package.yml

@@ -0,0 +1,88 @@
+name: Style and unit tests
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  test-and-build:
+    name: Setup test & build environment
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.13", "3.14"]
+
+    steps:
+      - name: Check out the source
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install .
+          pip install .[dev]
+
+      - name: Style and formatting (ruff)
+        run: |
+          ruff check .
+
+      - name: Unit and integration tests (pytest)
+        run: |
+          pytest
+
+      - name: Mypy Check
+        uses: jpetrucciani/mypy-check@master
+        with:
+          python_version: ${{ matrix.python-version }}
+          requirements: ". .[dev]"
+
+      - name: Upgrade pip
+        run: |
+          python3 -m pip install --upgrade pip
+
+      - name: Install pypa/build
+        run: python3 -m pip install build --user
+
+      - name: Build a binary wheel and a source tarball
+        run: python3 -m build
+
+      - name: Store the distribution packages
+        uses: actions/upload-artifact@v5
+        with:
+          name: dist-${{ matrix.python-version }}
+          path: dist/
+
+  publish-to-pypi:
+    name: Publish module to PyPI
+    # if: startsWith(github.ref, 'refs/tags/')  # only publish to PyPI on tag pushes
+    needs:
+      - test-and-build
+    runs-on: ubuntu-latest
+    environment: pypi
+    # name: pypi
+    # url: https://pypi.org/p/click-async-plugins
+    permissions:
+      id-token: write
+    strategy:
+      matrix:
+        python-version: ["3.13"]
+
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v6
+        with:
+          name: dist-${{ matrix.python-version }}
+          path: dist/
+
+      - name: Push to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

click_async_plugins-0.7.3/.gitignore

@@ -0,0 +1,8 @@
+__pycache__
+/.direnv
+.envrc
+/.mypy_cache
+/.ruff_cache
+.coverage
+.*.sw?
+/dist

click_async_plugins-0.7.3/.pre-commit-config.yaml

@@ -0,0 +1,20 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.19.1
+    hooks:
+      - id: mypy
+        additional_dependencies:
+          - click
+          - pytest
+          - pytest-asyncio
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.6
+    hooks:
+      - id: ruff-check
+        args: [--show-fixes]
+      - id: ruff-format
+        args: [--diff]
+
+fail_fast: true

click_async_plugins-0.7.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 martin f. krafft
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

click_async_plugins-0.7.3/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: click-async-plugins
+Version: 0.7.3
+Summary: An architecture to easily run asyncio tasks from Click
+Author-email: "martin f. krafft" <click-async-plugins@pobox.madduck.net>
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.12
+Requires-Dist: click
+Provides-Extra: dev
+Requires-Dist: coverage; extra == 'dev'
+Requires-Dist: ipdb; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest-ruff; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+[![Style and unit tests badge](https://github.com/madduck/click-async-plugins/actions/workflows/python-package.yml/badge.svg)](https://github.com/madduck/click-async-plugins/actions/workflows/python-package.yml)
+
+# click-async-plugins
+
+This is a proof-of-concept of a Python [asyncio](https://docs.python.org/3/library/asyncio.html) plugin architecture based on
+[click](https://click.palletsprojects.com/).
+
+Instead of writing [functions that make up sub-commands](https://click.palletsprojects.com/en/stable/commands-and-groups/#basic-group-example), you write asynchronous "lifespan functions" (`AsyncGenerator`), like this one:
+
+```Python
+@cli_core.plugin_command
+@click.option("--sleep", type=click.FloatRange(min=0.01), default=1)
+async def myplugin(sleep: float) -> PluginLifespan:
+
+    # code to set things up goes here
+
+    async def long_running_task(*, sleep: float):
+        # task initialisation can happen here
+
+        try:
+            while True:
+                await asyncio.sleep(sleep)
+
+        finally:
+            # code to clean up the task goes here
+            pass
+
+    yield long_running_task(sleep=sleep)
+
+    # code to tear things down goes here
+```
+
+Multiple such plugins can be defined/added to `core` (see the [demo code](https://github.com/madduck/click-async-plugins/blob/main/demo.py)). These plugins will all have their setup code called in turn. If, after setup, a plugin yields a coroutine (e.g. a long-running task), this task is scheduled with the main event loop, but this is optional, and tasks that yield nothing (`None`) will just sleep until program termination. Upon termination, the plugins' teardown code is invoked (in reverse order).
+
+Here's what the demo code logs to the console. Two plugins are invoked. The first counts down from 3 each second, and notifies subscribers of each number. The second plugin — "echo" — just listens for updates from the "countdown" task and echoes them.
+
+```raw
+$ python demo.py countdown --from 3 echo --immediately
+DEBUG:root:Setting up task for 'echo'
+DEBUG:root:Setting up task for 'countdown'
+DEBUG:root:Scheduling task for 'echo'
+DEBUG:root:Waiting for update to 'countdown'…
+DEBUG:root:Scheduling task for 'countdown'
+INFO:root:Counting down… 3
+DEBUG:root:Notifying subscribers of update to 'countdown'…
+INFO:root:Countdown currently at 3
+DEBUG:root:Waiting for update to 'countdown'…
+INFO:root:Counting down… 2
+DEBUG:root:Notifying subscribers of update to 'countdown'…
+INFO:root:Countdown currently at 2
+DEBUG:root:Waiting for update to 'countdown'…
+INFO:root:Counting down… 1
+DEBUG:root:Notifying subscribers of update to 'countdown'…
+INFO:root:Countdown currently at 1
+DEBUG:root:Waiting for update to 'countdown'…
+INFO:root:Finished counting down
+^C
+DEBUG:root:Task for 'echo' cancelled
+DEBUG:root:Terminating…
+DEBUG:root:Lifespan over for countdown
+DEBUG:root:Lifespan over for echo
+DEBUG:root:Finished.
+```
+
+I hope you get the idea. If you need more input, take a look at look at
+[tptools' tpsrv CLI](https://github.com/madduck/tptools/tree/main/tpsrv), which
+I was developing when I factored out this code.
+
+There's also a "debug" plugin included, which allows interaction with the CLI as
+its running via key presses. Hit `?` to get an overview of commands available.
+
+Looking forward to your feedback.
+
+Oh, and if someone wanted to turn this into a proper package with tests and everything, I think it could be published to pip/pypy. I need to stop shaving this yak now, though.
+
+© 2025 martin f. krafft <<click-async-plugins@pobox.madduck.net>>

click_async_plugins-0.7.3/README.md

@@ -0,0 +1,76 @@
+[![Style and unit tests badge](https://github.com/madduck/click-async-plugins/actions/workflows/python-package.yml/badge.svg)](https://github.com/madduck/click-async-plugins/actions/workflows/python-package.yml)
+
+# click-async-plugins
+
+This is a proof-of-concept of a Python [asyncio](https://docs.python.org/3/library/asyncio.html) plugin architecture based on
+[click](https://click.palletsprojects.com/).
+
+Instead of writing [functions that make up sub-commands](https://click.palletsprojects.com/en/stable/commands-and-groups/#basic-group-example), you write asynchronous "lifespan functions" (`AsyncGenerator`), like this one:
+
+```Python
+@cli_core.plugin_command
+@click.option("--sleep", type=click.FloatRange(min=0.01), default=1)
+async def myplugin(sleep: float) -> PluginLifespan:
+
+    # code to set things up goes here
+
+    async def long_running_task(*, sleep: float):
+        # task initialisation can happen here
+
+        try:
+            while True:
+                await asyncio.sleep(sleep)
+
+        finally:
+            # code to clean up the task goes here
+            pass
+
+    yield long_running_task(sleep=sleep)
+
+    # code to tear things down goes here
+```
+
+Multiple such plugins can be defined/added to `core` (see the [demo code](https://github.com/madduck/click-async-plugins/blob/main/demo.py)). These plugins will all have their setup code called in turn. If, after setup, a plugin yields a coroutine (e.g. a long-running task), this task is scheduled with the main event loop, but this is optional, and tasks that yield nothing (`None`) will just sleep until program termination. Upon termination, the plugins' teardown code is invoked (in reverse order).
+
+Here's what the demo code logs to the console. Two plugins are invoked. The first counts down from 3 each second, and notifies subscribers of each number. The second plugin — "echo" — just listens for updates from the "countdown" task and echoes them.
+
+```raw
+$ python demo.py countdown --from 3 echo --immediately
+DEBUG:root:Setting up task for 'echo'
+DEBUG:root:Setting up task for 'countdown'
+DEBUG:root:Scheduling task for 'echo'
+DEBUG:root:Waiting for update to 'countdown'…
+DEBUG:root:Scheduling task for 'countdown'
+INFO:root:Counting down… 3
+DEBUG:root:Notifying subscribers of update to 'countdown'…
+INFO:root:Countdown currently at 3
+DEBUG:root:Waiting for update to 'countdown'…
+INFO:root:Counting down… 2
+DEBUG:root:Notifying subscribers of update to 'countdown'…
+INFO:root:Countdown currently at 2
+DEBUG:root:Waiting for update to 'countdown'…
+INFO:root:Counting down… 1
+DEBUG:root:Notifying subscribers of update to 'countdown'…
+INFO:root:Countdown currently at 1
+DEBUG:root:Waiting for update to 'countdown'…
+INFO:root:Finished counting down
+^C
+DEBUG:root:Task for 'echo' cancelled
+DEBUG:root:Terminating…
+DEBUG:root:Lifespan over for countdown
+DEBUG:root:Lifespan over for echo
+DEBUG:root:Finished.
+```
+
+I hope you get the idea. If you need more input, take a look at look at
+[tptools' tpsrv CLI](https://github.com/madduck/tptools/tree/main/tpsrv), which
+I was developing when I factored out this code.
+
+There's also a "debug" plugin included, which allows interaction with the CLI as
+its running via key presses. Hit `?` to get an overview of commands available.
+
+Looking forward to your feedback.
+
+Oh, and if someone wanted to turn this into a proper package with tests and everything, I think it could be published to pip/pypy. I need to stop shaving this yak now, though.
+
+© 2025 martin f. krafft <<click-async-plugins@pobox.madduck.net>>

click_async_plugins-0.7.3/click_async_plugins/__init__.py

@@ -0,0 +1,31 @@
+from .command import plugin
+from .core import cli_core, runner
+from .group import plugin_group
+from .itc import ITC
+from .typedefs import PluginFactory, PluginLifespan
+from .util import (
+    CliContext,
+    create_plugin_task,
+    pass_clictx,
+    react_to_data_update,
+    run_plugins,
+    run_tasks,
+    setup_plugins,
+)
+
+__all__ = [
+    "CliContext",
+    "cli_core",
+    "create_plugin_task",
+    "ITC",
+    "pass_clictx",
+    "plugin",
+    "PluginFactory",
+    "plugin_group",
+    "PluginLifespan",
+    "react_to_data_update",
+    "runner",
+    "run_plugins",
+    "run_tasks",
+    "setup_plugins",
+]

click_async_plugins-0.7.3/click_async_plugins/command.py

@@ -0,0 +1,26 @@
+from collections.abc import Callable
+from contextlib import asynccontextmanager
+from functools import partial, wraps
+from typing import Any
+
+import click
+
+from .typedefs import PluginFactory, PluginLifespan
+
+
+class PluginCommand(click.Command):
+    def invoke(self, ctx: click.Context) -> PluginFactory | None:
+        if (callback := self.callback) is None:
+            return None
+
+        @wraps(callback)
+        def wrapper(*args: list[Any], **kwargs: dict[str, Any]) -> PluginFactory:
+            lifespan_manager = asynccontextmanager(partial(callback, *args, **kwargs))
+            lifespan_manager.__name__ = callback.__name__
+            return lifespan_manager
+
+        return ctx.invoke(wrapper, **ctx.params)
+
+
+def plugin(fn: Callable[..., PluginLifespan]) -> PluginCommand:
+    return click.command(cls=PluginCommand)(fn)

click_async_plugins-0.7.3/click_async_plugins/core.py

@@ -0,0 +1,20 @@
+import asyncio
+
+import click
+
+from click_async_plugins.itc import ITC
+
+from .group import plugin_group
+from .typedefs import PluginFactory
+from .util import CliContext, run_plugins
+
+
+@plugin_group
+@click.pass_context
+def cli_core(ctx: click.Context) -> None:
+    ctx.obj = CliContext(itc=ITC())
+
+
+@cli_core.result_callback()
+def runner(plugin_factories: list[PluginFactory]) -> None:
+    asyncio.run(run_plugins(plugin_factories))

click_async_plugins-0.7.3/click_async_plugins/debug.py

@@ -0,0 +1,211 @@
+# needed < 3.14 so that annotations aren't evaluated
+from __future__ import annotations
+
+import asyncio
+import datetime
+import logging
+import os
+import sys
+from collections.abc import AsyncGenerator, Callable
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from functools import partial
+from typing import Any, Coroutine, cast
+
+from click_async_plugins.util import CliContext
+
+from . import PluginLifespan, pass_clictx, plugin
+
+logger = logging.getLogger(__name__)
+
+
+def puts(s: str) -> None:
+    print(s, file=sys.stderr)
+
+
+def echo_newline(_: CliContext) -> str:
+    """Outputs a new line"""
+    return ""
+
+
+def terminal_block(_: CliContext) -> str:
+    """Outputs a couple of newlines and the current time"""
+    return f"{'\n' * 8}The time is now: {datetime.datetime.now().isoformat(sep=' ')}\n"
+
+
+def _name_for_coro(coro: Coroutine[Any, Any, Any] | None) -> str:
+    if coro is None:
+        return str(None)
+
+    for attr in ("__qualname__", "__name__"):
+        if (ret := getattr(coro, attr, None)) is not None:
+            return cast(str, ret)
+
+    return "(unknown)"
+
+
+def debug_info(clictx: CliContext) -> str:
+    """Prints debugging information on tasks and CliContext"""
+    ret = "*** BEGIN DEBUG INFO: ***\n"
+    ret += "Tasks:\n"
+    for i, task in enumerate(asyncio.all_tasks(asyncio.get_event_loop()), 1):
+        coro = task.get_coro()
+        ret += (
+            f"  {i:02n}  {task.get_name():32s}  "
+            f"state={task._state.lower():8s}  "
+            f"coro={_name_for_coro(coro)}\n"
+        )
+    ret += "CliContext:\n"
+    maxlen = max([len(k) for k in clictx.__dict__.keys()])
+    for attr, value in clictx.__dict__.items():
+        ret += f"  {attr:>{maxlen}s} = {value!r}\n"
+    return ret + "*** END DEBUG INFO: ***"
+
+
+_LOGLEVELS = {
+    logging.DEBUG: "DEBUG",
+    logging.INFO: "INFO",
+    logging.WARN: "WARN",
+    logging.ERROR: "ERROR",
+    logging.CRITICAL: "CRITICAL",
+}
+
+
+def adjust_loglevel(_: CliContext, change: int) -> str | None:
+    """Adjusts the log level"""
+    rootlogger = logging.getLogger()
+    newlevel = rootlogger.getEffectiveLevel() + change
+    if newlevel < logging.DEBUG or newlevel > logging.CRITICAL:
+        return None
+
+    rootlogger.setLevel(newlevel)
+    return f"Log level now at {_LOGLEVELS[rootlogger.getEffectiveLevel()]}"
+
+
+@dataclass
+class KeyAndFunc[ContextT: CliContext]:
+    key: str
+    func: Callable[[ContextT], str | None]
+
+
+type KeyCmdMapType[ContextT: CliContext] = dict[int, KeyAndFunc[ContextT]]
+
+
+def print_help[ContextT: CliContext](
+    _: ContextT, key_to_cmd: KeyCmdMapType[ContextT]
+) -> str:
+    ret = "Keys I know about for debugging:\n"
+    for keyfunc in key_to_cmd.values():
+        ret += f"  {keyfunc.key:5s} {keyfunc.func.__doc__}\n"
+    return ret + "  ?     Print this message"
+
+
+async def getch() -> AsyncGenerator[str]:
+    try:
+        import fcntl
+        import termios
+        import tty
+
+        fd = sys.stdin.fileno()
+        termios_saved = termios.tcgetattr(fd)
+        fnctl_flags = fcntl.fcntl(sys.stdin, fcntl.F_GETFL)
+
+        try:
+            logger.debug("Configuring stdin for raw input")
+            tty.setcbreak(fd)
+            fcntl.fcntl(sys.stdin, fcntl.F_SETFL, fnctl_flags | os.O_NONBLOCK)
+
+            while True:
+                yield sys.stdin.read(1)
+
+        except asyncio.CancelledError:
+            pass
+
+        finally:
+            logger.debug("Restoring stdin")
+            termios.tcsetattr(fd, termios.TCSADRAIN, termios_saved)
+            fcntl.fcntl(sys.stdin, fcntl.F_SETFL, fnctl_flags)
+
+    except ImportError:
+        pass
+
+    try:
+        import msvcrt
+
+        while True:
+            if msvcrt.kbhit():  # type: ignore[attr-defined]
+                yield msvcrt.getch()  # type: ignore[attr-defined]
+
+            else:
+                await asyncio.sleep(0.1)
+
+    except ImportError as exc:
+        raise NotImplementedError from exc
+
+
+async def _monitor_stdin[ContextT: CliContext](
+    clictx: ContextT,
+    key_to_cmd: KeyCmdMapType[ContextT],
+    *,
+    puts: Callable[[str], Any] = puts,
+) -> None:
+    try:
+        async for ch in getch():
+            if len(ch) == 0:
+                await asyncio.sleep(0.1)
+                continue
+
+            if (key := ord(ch)) == 0x3F:
+                puts(print_help(clictx, key_to_cmd))
+
+            elif (keyfunc := key_to_cmd.get(key)) is not None and callable(
+                keyfunc.func
+            ):
+                # TODO: enable async functions
+                if (ret := keyfunc.func(clictx)) is not None:
+                    puts(ret)
+
+            else:
+                logger.debug(f"Ignoring character 0x{key:02x} on stdin")
+
+    except NotImplementedError:
+        logger.warning("The 'debug' plugin does not work on this platform")
+        return None
+
+
+@asynccontextmanager
+async def monitor_stdin_for_debug_commands[ContextT: CliContext](
+    clictx: CliContext,
+    *,
+    key_to_cmd: KeyCmdMapType[ContextT] | None = None,
+    puts: Callable[[str], Any] = puts,
+) -> PluginLifespan:
+    key_to_cmd = key_to_cmd or {}
+
+    increase_loglevel = partial(adjust_loglevel, change=-10)
+    increase_loglevel.__doc__ = "Increase the logging level"
+    decrease_loglevel = partial(adjust_loglevel, change=10)
+    decrease_loglevel.__doc__ = "Decrease the logging level"
+
+    map = {
+        0xA: KeyAndFunc(r"\n", echo_newline),
+        0xD: KeyAndFunc(r"\n", echo_newline),
+        0x1B: KeyAndFunc("<Esc>", terminal_block),
+        0x4: KeyAndFunc("^D", debug_info),
+        0x2B: KeyAndFunc("+", increase_loglevel),
+        0x2D: KeyAndFunc("-", decrease_loglevel),
+        **key_to_cmd,
+    }
+    yield _monitor_stdin(clictx, map, puts=puts)
+
+
+@plugin
+@pass_clictx
+async def debug(clictx: CliContext) -> PluginLifespan:
+    """Monitor stdin for keypresses to trigger debugging functions
+
+    Press '?' to get a list of possible keys.
+    """
+
+    async with monitor_stdin_for_debug_commands(clictx) as task:
+        yield task

click_async_plugins-0.7.3/click_async_plugins/group.py

@@ -0,0 +1,16 @@
+from collections.abc import Callable
+from typing import cast
+
+import click
+
+from .command import PluginCommand
+from .typedefs import PluginLifespan
+
+
+class PluginGroup(click.Group):
+    def plugin_command(self, fn: Callable[..., PluginLifespan]) -> PluginCommand:
+        return cast(PluginCommand, self.command(cls=PluginCommand)(fn))
+
+
+def plugin_group(fn: Callable[..., None]) -> PluginGroup:
+    return click.group(cls=PluginGroup, chain=True)(fn)

click_async_plugins-0.7.3/click_async_plugins/itc.py

@@ -0,0 +1,89 @@
+import asyncio
+import logging
+import time
+from collections import defaultdict
+from collections.abc import AsyncGenerator
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class ITC:
+    def __init__(self) -> None:
+        self._events: dict[str, list[asyncio.Event]] = defaultdict(list[asyncio.Event])
+        self._objects: dict[str, Any] = {}
+
+    def __repr__(self) -> str:
+        ret = f"{self.__class__.__name__}("
+        i = 0
+        for i, (key, obj) in enumerate(self._objects.items()):
+            ret = (
+                f"{ret}{'\n' if i == 0 else ''}       "
+                f"{key}={obj!r} "
+                f"({len(self._events[key])} listeners)\n"
+            )
+        return f"{ret}{'    ' if i > 0 else ''})"
+
+    def set(self, key: str, obj: Any) -> None:
+        self._objects[key] = obj
+        self.fire(key)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self._objects.get(key, default)
+
+    def fire(self, key: str) -> None:
+        logger.debug(f"Notifying subscribers of update to '{key}'…")
+        for event in self._events.get(key) or []:
+            event.set()
+
+    async def updates(
+        self,
+        key: str,
+        *,
+        yield_immediately: bool = True,
+        timeout: float | None = None,
+        at_most_every: float | None = None,
+        yield_for_no_value: Any | None = None,
+    ) -> AsyncGenerator[Any | None]:
+        at_most_every = 0 if at_most_every is None else at_most_every
+
+        if timeout is not None and timeout <= 0:
+            logger.warning("Updates timeout <= 0, disabling timeout…")
+            timeout = None
+
+        if timeout is not None and timeout < at_most_every:
+            logger.warning("timeout < at_most_every makes no sense, adjusting…")
+            timeout = at_most_every
+
+        event = asyncio.Event()
+        self._events[key].append(event)
+
+        if yield_immediately:
+            yield self._objects.get(key, yield_for_no_value)
+
+        try:
+            timestamp = 0.0
+            while True:
+                logger.debug(f"Waiting for update to '{key}'…")
+                try:
+                    async with asyncio.timeout(timeout):
+                        await event.wait()
+                except TimeoutError:
+                    logger.debug(f"Timeout after {timeout}s")
+
+                if (waitremain := timestamp + at_most_every - time.monotonic()) > 0:
+                    logger.debug(f"Too early, sleeping for {waitremain:.02f}s")
+                    await asyncio.sleep(waitremain)
+
+                yield self._objects.get(key, yield_for_no_value)
+                event.clear()
+                timestamp = time.monotonic()
+
+        finally:
+            self._events[key].remove(event)
+
+    def has_subscribers(self, key: str) -> bool:
+        return len(self._events.get(key, [])) > 0
+
+    def knows_about(self, key: str) -> bool:
+        return key in self._objects

click_async_plugins-0.7.3/click_async_plugins/typedefs.py

@@ -0,0 +1,7 @@
+from collections.abc import AsyncGenerator, Callable, Coroutine
+from typing import AsyncContextManager
+
+type PluginTask = Coroutine[None, None, None]
+type PluginLifespan = AsyncGenerator[PluginTask | None]
+type Plugin = AsyncContextManager[PluginTask | None]
+type PluginFactory = Callable[..., Plugin]

click_async_plugins-0.7.3/click_async_plugins/util.py

@@ -0,0 +1,127 @@
+import asyncio
+import logging
+from collections.abc import AsyncGenerator, Callable, Coroutine
+from contextlib import AsyncExitStack
+from dataclasses import dataclass
+from functools import partial, update_wrapper
+from typing import Any, Never
+
+import click
+
+from .itc import ITC
+from .typedefs import PluginFactory, PluginTask
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class CliContext:
+    itc: ITC
+
+
+pass_clictx = click.make_pass_decorator(CliContext)
+
+
+@dataclass
+class TaskWithName:
+    task: PluginTask | None
+    name: str
+
+
+async def sleep_forever(sleep: float = 1, *, forever: bool = True) -> Never | None:
+    while await asyncio.sleep(sleep, forever):
+        pass
+    return None
+
+
+def create_plugin_task[T](
+    task: TaskWithName,
+    *,
+    create_task_fn: Callable[..., asyncio.Task[T]] = asyncio.create_task,
+) -> asyncio.Task[T]:
+    async def task_wrapper() -> None:
+        try:
+            if asyncio.iscoroutine(task.task):
+                logger.debug(f"Scheduling task for '{task.name}'")
+                await task.task
+
+            else:
+                logger.debug(f"Waiting until programme termination for '{task.name}'")
+                await sleep_forever(3600)
+
+        except asyncio.CancelledError:
+            logger.debug(f"Task for '{task.name}' cancelled")
+
+    if task.task is not None:
+        task_wrapper = update_wrapper(task_wrapper, task.task)  # type: ignore[arg-type]
+    else:
+        task_wrapper = update_wrapper(task_wrapper, sleep_forever)
+
+    return create_task_fn(task_wrapper(), name=task.name)
+
+
+def _get_name(plugin_factory: PluginFactory) -> str:
+    # if plugin_factory is e.g. a functools.partial instance, get at the actual
+    # function, but if not, then set func to the factory
+    func = getattr(plugin_factory, "func", None) or plugin_factory
+
+    if (nameattr := getattr(func, "__name__", None)) is not None:
+        return str(nameattr)
+
+    return str(func)
+
+
+async def setup_plugins(
+    plugin_factories: list[PluginFactory],
+    *args: Any,
+    stack: AsyncExitStack,
+    **kwargs: Any,
+) -> list[TaskWithName]:
+    tasks: list[TaskWithName] = []
+    for plugin_factory in plugin_factories:
+        plugin_fn = plugin_factory(*args, **kwargs)
+        name = _get_name(plugin_factory)
+        logger.debug(f"Setting up task for '{name}'")
+        task = await stack.enter_async_context(plugin_fn)
+        tasks.append(TaskWithName(task=task, name=name))
+
+    return tasks
+
+
+async def run_tasks(tasks: list[TaskWithName]) -> None:
+    try:
+        async with asyncio.TaskGroup() as tg:
+            plugin_task = partial(create_plugin_task, create_task_fn=tg.create_task)
+            for task in tasks:
+                plugin_task(task)
+
+    except* asyncio.CancelledError:
+        pass
+
+    finally:
+        logger.debug("Terminating…")
+
+
+async def run_plugins(
+    plugin_factories: list[PluginFactory], *args: Any, **kwargs: Any
+) -> None:
+    async with AsyncExitStack() as stack:
+        tasks = await setup_plugins(plugin_factories, *args, stack=stack, **kwargs)
+        await run_tasks(tasks)
+
+    logger.debug("Finished.")
+
+
+type UpdateCallbackType[T] = Callable[[T], Coroutine[None, None, None]]
+
+
+async def react_to_data_update[T](
+    updates_gen: AsyncGenerator[T], *, callback: UpdateCallbackType[T]
+) -> None:
+    try:
+        async for update in updates_gen:
+            if update is not None:
+                await callback(update)
+
+    except asyncio.CancelledError:
+        pass

click_async_plugins-0.7.3/demo.py

@@ -0,0 +1,74 @@
+import asyncio
+import logging
+
+import click
+
+from click_async_plugins import (
+    CliContext,
+    PluginLifespan,
+    cli_core,
+    pass_clictx,
+    plugin,
+)
+from click_async_plugins.debug import debug
+
+logging.basicConfig(level=logging.DEBUG)
+logger = logging.getLogger()
+logging.getLogger("asyncio").setLevel(logging.WARNING)
+
+
+@cli_core.plugin_command
+@click.option(
+    "--from",
+    "-f",
+    "start",
+    type=click.IntRange(min=1),
+    default=3,
+    help="Count down from this number",
+)
+@click.option(
+    "--sleep", "-s", type=float, default=1, help="Sleep this long between counts"
+)
+@pass_clictx
+async def countdown(
+    clictx: CliContext, start: int = 3, sleep: float = 1
+) -> PluginLifespan:
+    async def counter(start: int, sleep: float) -> None:
+        cur = start
+        while cur > 0:
+            logger.info(f"Counting down… {cur}")
+            clictx.itc.set("countdown", cur)
+            cur = await asyncio.sleep(sleep, cur - 1)
+
+        logger.info("Finished counting down")
+
+    yield counter(start, sleep)
+
+    logger.debug("Lifespan over for countdown")
+
+
+# For fun, let's add_command the second plugin, instead of using a decorator:
+@plugin
+@click.option(
+    "--immediately",
+    is_flag=True,
+    help="Don't wait for first update but echo right upon start",
+)
+@pass_clictx
+async def echo(clictx: CliContext, immediately: bool) -> PluginLifespan:
+    async def reactor() -> None:
+        async for cur in clictx.itc.updates("countdown", yield_immediately=immediately):
+            logger.info(f"Countdown currently at {cur}")
+
+    yield reactor()
+
+    logger.debug("Lifespan over for echo")
+
+
+cli_core.add_command(echo)
+cli_core.add_command(debug)
+
+if __name__ == "__main__":
+    import sys
+
+    sys.exit(cli_core())

click_async_plugins-0.7.3/pyproject.toml

@@ -0,0 +1,70 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.setuptools_scm]
+write_to = "_version.py"
+
+[project]
+name = "click-async-plugins"
+version = "0.7.3"
+authors = [
+  { name = "martin f. krafft", email = "click-async-plugins@pobox.madduck.net" },
+]
+description = "An architecture to easily run asyncio tasks from Click"
+readme = "README.md"
+requires-python = ">=3.12"
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+]
+dependencies = ["click"]
+
+[project.optional-dependencies]
+dev = [
+  "ipdb",
+  "pre-commit",
+  "ruff",
+  "mypy",
+  "pytest",
+  "pytest-asyncio",
+  "pytest-ruff",
+  "pytest-cov",
+  "coverage",
+]
+
+[tool.setuptools.package-data]
+"click-async-plugins" = ["click_async_plugins/py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra --cov=click_async_plugins --cov-report term-missing:skip-covered --no-cov-on-fail --pdbcls=IPython.terminal.debugger:TerminalPdb --ruff --ruff-format"
+asyncio_default_fixture_loop_scope = "function"
+log_level = "DEBUG"
+log_format = "%(name)s %(levelname)s %(message)s"
+
+[tool.ruff]
+line-length = 88
+
+[tool.ruff.lint]
+select = ["B", "C", "E", "F", "I", "W", "B9"]
+
+[tool.mypy]
+strict = true
+warn_unreachable = true
+
+[[tool.mypy.overrides]]
+module = "ipdb"
+ignore_missing_imports = true
+
+[tool.coverage.report]
+exclude_also = [
+  'def __repr__',
+  'if TYPE_CHECKING:',
+  'class .*\bProtocol\):',
+  '@overload',
+  '@(abc\.)?abstractmethod',
+  'raise NotImplementedError',
+  'raise AssertionError',
+]

click_async_plugins-0.7.3/tests/test_typedefs.py

@@ -0,0 +1 @@
+import click_async_plugins.typedefs  # noqa: F401