click-async-plugins 0.7.3__tar.gz → 0.8.0__tar.gz

{click_async_plugins-0.7.3 → click_async_plugins-0.8.0}/.gitignore

@@ -6,3 +6,4 @@ __pycache__
 .coverage
 .*.sw?
 /dist
+/_version.py

{click_async_plugins-0.7.3 → click_async_plugins-0.8.0}/.pre-commit-config.yaml

@@ -2,7 +2,7 @@
 # See https://pre-commit.com/hooks.html for more hooks
 repos:
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.19.1
+    rev: v2.3.1
     hooks:
       - id: mypy
         additional_dependencies:
@@ -10,7 +10,7 @@ repos:
           - pytest
           - pytest-asyncio
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.15.6
+    rev: v0.16.4
     hooks:
       - id: ruff-check
         args: [--show-fixes]

{click_async_plugins-0.7.3 → click_async_plugins-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: click-async-plugins
-Version: 0.7.3
+Version: 0.8.0
 Summary: An architecture to easily run asyncio tasks from Click
 Author-email: "martin f. krafft" <click-async-plugins@pobox.madduck.net>
 License-File: LICENSE
@@ -21,7 +21,7 @@ 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)
+[![Style and unit tests badge](https://github.com/madduck/click-async-plugins/actions/workflows/0-testing.yml/badge.svg)](https://github.com/madduck/click-async-plugins/actions/workflows/0-testing.yml)
 
 # click-async-plugins
 
@@ -37,7 +37,7 @@ async def myplugin(sleep: float) -> PluginLifespan:
 
     # code to set things up goes here
 
-    async def long_running_task(*, sleep: float):
+    async def long_running_task(*, sleep: float) -> None:
         # task initialisation can happen here
 
         try:
@@ -94,6 +94,62 @@ 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.
+## Plugin dependencies
 
-© 2025 martin f. krafft <<click-async-plugins@pobox.madduck.net>>
+A plugin can declare that it needs other plugins to be active, using the
+`depends_on` decorator. Put it underneath `@plugin`/`@plugin_command`, just like
+you would `click.option`:
+
+```Python
+from click_async_plugins import depends_on
+
+@cli_core.plugin_command
+@depends_on("countdown")
+@pass_clictx
+async def echo(clictx: CliContext) -> PluginLifespan: ...
+```
+
+Dependencies are given either as the plugin's command name (as typed on the
+command line), or as the plugin command object itself, e.g.
+`@depends_on(countdown)`; you can mix and match, and use the decorator more than
+once.
+
+When the plugins are run:
+
+- The declared dependencies must have been specified on the command line,
+  otherwise a usage error is raised before anything is set up;
+- The order on the command line does not matter: dependencies are always set up
+  *before* the plugins that need them, and (as teardown happens in reverse) torn
+  down *after* them. Plugins that are not constrained by a dependency keep their
+  command line order;
+- Circular dependencies are reported as a usage error, too.
+
+Both errors are raised as `PluginDependencyError`, a `click.UsageError`. If you
+call `run_plugins` yourself, dependencies are resolved there; the logic is
+available separately as `resolve_dependencies`.
+
+## Contributing
+
+To contribute, please ensure you have the appropriate dependencies installed:
+
+```sh
+pip install -e .[dev]
+```
+
+and then install the Git pre-commit hooks that ensure that any commits conform
+with the coding-style used by this project.
+
+```sh
+pre-commit install
+```
+
+All code is 100% test-covered, and all contributions are expected to keep this up.
+Use `pytest` to run the test suite.
+
+Note that all code is typed, and typing is part of test-coverage.
+
+## Copyright & Licence
+
+© 2025–26 martin f. krafft <<click-async-plugins@pobox.madduck.net>>
+
+Available under the terms of the MIT licence.

{click_async_plugins-0.7.3 → click_async_plugins-0.8.0}/README.md

@@ -1,4 +1,4 @@
-[![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)
+[![Style and unit tests badge](https://github.com/madduck/click-async-plugins/actions/workflows/0-testing.yml/badge.svg)](https://github.com/madduck/click-async-plugins/actions/workflows/0-testing.yml)
 
 # click-async-plugins
 
@@ -14,7 +14,7 @@ async def myplugin(sleep: float) -> PluginLifespan:
 
     # code to set things up goes here
 
-    async def long_running_task(*, sleep: float):
+    async def long_running_task(*, sleep: float) -> None:
         # task initialisation can happen here
 
         try:
@@ -71,6 +71,62 @@ 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.
+## Plugin dependencies
 
-© 2025 martin f. krafft <<click-async-plugins@pobox.madduck.net>>
+A plugin can declare that it needs other plugins to be active, using the
+`depends_on` decorator. Put it underneath `@plugin`/`@plugin_command`, just like
+you would `click.option`:
+
+```Python
+from click_async_plugins import depends_on
+
+@cli_core.plugin_command
+@depends_on("countdown")
+@pass_clictx
+async def echo(clictx: CliContext) -> PluginLifespan: ...
+```
+
+Dependencies are given either as the plugin's command name (as typed on the
+command line), or as the plugin command object itself, e.g.
+`@depends_on(countdown)`; you can mix and match, and use the decorator more than
+once.
+
+When the plugins are run:
+
+- The declared dependencies must have been specified on the command line,
+  otherwise a usage error is raised before anything is set up;
+- The order on the command line does not matter: dependencies are always set up
+  *before* the plugins that need them, and (as teardown happens in reverse) torn
+  down *after* them. Plugins that are not constrained by a dependency keep their
+  command line order;
+- Circular dependencies are reported as a usage error, too.
+
+Both errors are raised as `PluginDependencyError`, a `click.UsageError`. If you
+call `run_plugins` yourself, dependencies are resolved there; the logic is
+available separately as `resolve_dependencies`.
+
+## Contributing
+
+To contribute, please ensure you have the appropriate dependencies installed:
+
+```sh
+pip install -e .[dev]
+```
+
+and then install the Git pre-commit hooks that ensure that any commits conform
+with the coding-style used by this project.
+
+```sh
+pre-commit install
+```
+
+All code is 100% test-covered, and all contributions are expected to keep this up.
+Use `pytest` to run the test suite.
+
+Note that all code is typed, and typing is part of test-coverage.
+
+## Copyright & Licence
+
+© 2025–26 martin f. krafft <<click-async-plugins@pobox.madduck.net>>
+
+Available under the terms of the MIT licence.

click_async_plugins-0.8.0/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.8.0'
+__version_tuple__ = version_tuple = (0, 8, 0)
+
+__commit_id__ = commit_id = None

{click_async_plugins-0.7.3 → click_async_plugins-0.8.0}/click_async_plugins/__init__.py

@@ -1,5 +1,6 @@
 from .command import plugin
 from .core import cli_core, runner
+from .dependencies import PluginDependencyError, depends_on, resolve_dependencies
 from .group import plugin_group
 from .itc import ITC
 from .typedefs import PluginFactory, PluginLifespan
@@ -20,9 +21,12 @@ __all__ = [
     "ITC",
     "pass_clictx",
     "plugin",
+    "PluginDependencyError",
     "PluginFactory",
     "plugin_group",
     "PluginLifespan",
+    "depends_on",
+    "resolve_dependencies",
     "react_to_data_update",
     "runner",
     "run_plugins",

{click_async_plugins-0.7.3 → click_async_plugins-0.8.0}/click_async_plugins/command.py

@@ -5,6 +5,7 @@ from typing import Any
 
 import click
 
+from .dependencies import get_dependencies, mark_plugin_factory
 from .typedefs import PluginFactory, PluginLifespan
 
 
@@ -17,6 +18,11 @@ class PluginCommand(click.Command):
         def wrapper(*args: list[Any], **kwargs: dict[str, Any]) -> PluginFactory:
             lifespan_manager = asynccontextmanager(partial(callback, *args, **kwargs))
             lifespan_manager.__name__ = callback.__name__
+            mark_plugin_factory(
+                lifespan_manager,
+                name=self.name,
+                requires=get_dependencies(callback),
+            )
             return lifespan_manager
 
         return ctx.invoke(wrapper, **ctx.params)

click_async_plugins-0.8.0/click_async_plugins/dependencies.py

@@ -0,0 +1,114 @@
+from collections.abc import Callable, Sequence
+from typing import Any
+
+import click
+
+from .typedefs import PluginFactory
+
+# Dependencies are recorded as attributes, rather than in some registry, so
+# that they survive decorators that use functools.wraps (e.g. pass_clictx).
+_REQUIRES_ATTR = "__plugin_requires__"
+_NAME_ATTR = "__plugin_name__"
+
+
+class PluginDependencyError(click.UsageError):
+    pass
+
+
+def depends_on[T](*plugins: str | click.Command) -> Callable[[T], T]:
+    if not plugins:
+        raise ValueError("depends_on() requires at least one plugin")
+
+    names = tuple(
+        _command_name(p) if isinstance(p, click.Command) else p for p in plugins
+    )
+
+    def decorator(obj: T) -> T:
+        # Also allow use above @plugin, where we get handed the command.
+        target: Any = obj.callback if isinstance(obj, click.Command) else obj
+        if target is None:
+            raise TypeError(f"{obj!r} has no callback to attach dependencies to")
+
+        existing: tuple[str, ...] = getattr(target, _REQUIRES_ATTR, ())
+        setattr(target, _REQUIRES_ATTR, (*existing, *names))
+        return obj
+
+    return decorator
+
+
+def _command_name(command: click.Command) -> str:
+    if command.name is None:
+        raise ValueError(f"{command!r} has no name, so cannot be depended upon")
+    return command.name
+
+
+def get_dependencies(obj: object) -> tuple[str, ...]:
+    return tuple(getattr(obj, _REQUIRES_ATTR, ()))
+
+
+def mark_plugin_factory(
+    factory: PluginFactory, *, name: str | None, requires: tuple[str, ...]
+) -> None:
+    setattr(factory, _NAME_ATTR, name)
+    setattr(factory, _REQUIRES_ATTR, requires)
+
+
+def _lookup(factory: PluginFactory, attr: str) -> Any:
+    # Also look through functools.partial, like util._get_name does.
+    for candidate in (factory, getattr(factory, "func", None)):
+        if candidate is not None and (value := getattr(candidate, attr, None)):
+            return value
+    return None
+
+
+def _plugin_name(factory: PluginFactory) -> str | None:
+    name: str | None = _lookup(factory, _NAME_ATTR)
+    return name
+
+
+def _display_name(factory: PluginFactory) -> str:
+    return _plugin_name(factory) or str(getattr(factory, "__name__", factory))
+
+
+def resolve_dependencies(
+    plugin_factories: Sequence[PluginFactory],
+) -> list[PluginFactory]:
+    names = [_display_name(f) for f in plugin_factories]
+    requires: list[tuple[str, ...]] = [
+        _lookup(f, _REQUIRES_ATTR) or () for f in plugin_factories
+    ]
+
+    by_name: dict[str, list[int]] = {}
+    for idx, factory in enumerate(plugin_factories):
+        if (name := _plugin_name(factory)) is not None:
+            by_name.setdefault(name, []).append(idx)
+
+    ordered: list[int] = []
+    done: set[int] = set()
+
+    def visit(idx: int, trail: tuple[int, ...]) -> None:
+        if idx in done:
+            return
+
+        if idx in trail:
+            cycle = [*trail[trail.index(idx) :], idx]
+            raise PluginDependencyError(
+                "Circular plugin dependency: " + " → ".join(names[i] for i in cycle)
+            )
+
+        for dependency in requires[idx]:
+            if dependency not in by_name:
+                raise PluginDependencyError(
+                    f"Plugin '{names[idx]}' requires plugin '{dependency}', "
+                    "which was not specified."
+                )
+            for dependency_idx in by_name[dependency]:
+                visit(dependency_idx, (*trail, idx))
+
+        done.add(idx)
+        ordered.append(idx)
+
+    for idx in range(len(plugin_factories)):
+        visit(idx, ())
+
+    return [plugin_factories[idx] for idx in ordered]

{click_async_plugins-0.7.3 → click_async_plugins-0.8.0}/click_async_plugins/itc.py

@@ -58,10 +58,10 @@ class ITC:
         event = asyncio.Event()
         self._events[key].append(event)
 
-        if yield_immediately:
-            yield self._objects.get(key, yield_for_no_value)
-
         try:
+            if yield_immediately:
+                yield self._objects.get(key, yield_for_no_value)
+
             timestamp = 0.0
             while True:
                 logger.debug(f"Waiting for update to '{key}'…")
@@ -75,8 +75,13 @@ class ITC:
                     logger.debug(f"Too early, sleeping for {waitremain:.02f}s")
                     await asyncio.sleep(waitremain)
 
-                yield self._objects.get(key, yield_for_no_value)
+                # Clear the event in the same synchronous step as reading the
+                # value, and *before* yielding: updates that arrive while the
+                # consumer is busy will then trigger the next iteration
+                # instead of being wiped out.
                 event.clear()
+                value = self._objects.get(key, yield_for_no_value)
+                yield value
                 timestamp = time.monotonic()
 
         finally:

{click_async_plugins-0.7.3 → click_async_plugins-0.8.0}/click_async_plugins/util.py

@@ -8,9 +8,16 @@ from typing import Any, Never
 
 import click
 
+from .dependencies import resolve_dependencies
 from .itc import ITC
 from .typedefs import PluginFactory, PluginTask
 
+try:
+    from inspect import iscoroutine
+except ImportError:
+    # fall back to legacy implementation
+    from asyncio import iscoroutine  # type: ignore[assignment]
+
 logger = logging.getLogger(__name__)
 
 
@@ -41,7 +48,7 @@ def create_plugin_task[T](
 ) -> asyncio.Task[T]:
     async def task_wrapper() -> None:
         try:
-            if asyncio.iscoroutine(task.task):
+            if iscoroutine(task.task):
                 logger.debug(f"Scheduling task for '{task.name}'")
                 await task.task
 
@@ -105,6 +112,9 @@ async def run_tasks(tasks: list[TaskWithName]) -> None:
 async def run_plugins(
     plugin_factories: list[PluginFactory], *args: Any, **kwargs: Any
 ) -> None:
+    # Fail early, before anything is set up, if dependencies cannot be met
+    plugin_factories = resolve_dependencies(plugin_factories)
+
     async with AsyncExitStack() as stack:
         tasks = await setup_plugins(plugin_factories, *args, stack=stack, **kwargs)
         await run_tasks(tasks)

{click_async_plugins-0.7.3 → click_async_plugins-0.8.0}/demo.py

@@ -7,6 +7,7 @@ from click_async_plugins import (
     CliContext,
     PluginLifespan,
     cli_core,
+    depends_on,
     pass_clictx,
     plugin,
 )
@@ -54,6 +55,7 @@ async def countdown(
     is_flag=True,
     help="Don't wait for first update but echo right upon start",
 )
+@depends_on(countdown)
 @pass_clictx
 async def echo(clictx: CliContext, immediately: bool) -> PluginLifespan:
     async def reactor() -> None:

{click_async_plugins-0.7.3 → click_async_plugins-0.8.0}/pyproject.toml

@@ -1,13 +1,19 @@
 [build-system]
-requires = ["hatchling"]
+requires = ["hatchling", "hatch-vcs"]
 build-backend = "hatchling.build"
 
-[tool.setuptools_scm]
-write_to = "_version.py"
+[tool.hatch.build.hooks.vcs]
+version-file = "_version.py"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.targets.sdist]
+exclude = [".direnv", ".gitignore", ".github"]
 
 [project]
 name = "click-async-plugins"
-version = "0.7.3"
+dynamic = ["version"]
 authors = [
   { name = "martin f. krafft", email = "click-async-plugins@pobox.madduck.net" },
 ]

click_async_plugins-0.8.0/tests/test_command_group_core.py

@@ -0,0 +1,195 @@
+import asyncio
+from collections.abc import Iterator
+from contextlib import asynccontextmanager
+from typing import Any
+
+import click
+import pytest
+from click.testing import CliRunner
+
+from click_async_plugins import (
+    ITC,
+    CliContext,
+    PluginFactory,
+    PluginLifespan,
+    cli_core,
+    pass_clictx,
+    plugin,
+    plugin_group,
+    runner,
+)
+from click_async_plugins.command import PluginCommand
+from click_async_plugins.group import PluginGroup
+
+
+def _make_group() -> PluginGroup:
+    @plugin_group
+    def group() -> None: ...
+
+    @group.result_callback()
+    def collect(factories: list[PluginFactory]) -> list[PluginFactory]:
+        return factories
+
+    return group
+
+
+def _invoke(group: click.Group, args: list[str], **kwargs: Any) -> Any:
+    result = CliRunner().invoke(group, args, standalone_mode=False, **kwargs)
+    if result.exception:
+        raise result.exception
+    return result.return_value
+
+
+def test_plugin_group_is_chained_plugin_group() -> None:
+    group = _make_group()
+    assert isinstance(group, PluginGroup)
+    assert group.chain
+
+
+def test_plugin_decorator_returns_plugin_command() -> None:
+    @plugin
+    async def myplugin() -> PluginLifespan:
+        yield None
+
+    assert isinstance(myplugin, PluginCommand)
+    assert myplugin.name == "myplugin"
+
+
+def test_plugin_command_registers_on_group() -> None:
+    group = _make_group()
+
+    @group.plugin_command
+    async def myplugin() -> PluginLifespan:
+        yield None
+
+    assert isinstance(myplugin, PluginCommand)
+    assert group.commands["myplugin"] is myplugin
+
+
+def test_plugin_command_without_callback_invokes_to_none() -> None:
+    command = PluginCommand("noop")
+    with click.Context(command) as ctx:
+        assert command.invoke(ctx) is None
+
+
+@pytest.mark.asyncio
+async def test_plugin_command_invoke_returns_lifespan_factory() -> None:
+    group = _make_group()
+    events: list[tuple[str, int]] = []
+
+    @group.plugin_command
+    @click.option("--count", type=int, default=1)
+    async def counter(count: int) -> PluginLifespan:
+        async def work() -> None:
+            events.append(("work", count))
+
+        events.append(("setup", count))
+        yield work()
+        events.append(("teardown", count))
+
+    (factory,) = _invoke(group, ["counter", "--count", "3"])
+    assert factory.__name__ == "counter"
+    assert events == []  # nothing runs until the factory is entered
+
+    async with factory() as task:
+        assert task is not None
+        await task
+
+    assert events == [("setup", 3), ("work", 3), ("teardown", 3)]
+
+
+def test_chained_plugin_commands_yield_one_factory_each() -> None:
+    group = _make_group()
+
+    @group.plugin_command
+    async def first() -> PluginLifespan:
+        yield None
+
+    @group.plugin_command
+    async def second() -> PluginLifespan:
+        yield None
+
+    factories = _invoke(group, ["first", "second"])
+    assert [f.__name__ for f in factories] == ["first", "second"]
+
+
+@pytest.fixture
+def registered_commands() -> Iterator[list[str]]:
+    """Track commands added to the global cli_core and remove them afterwards"""
+    before = set(cli_core.commands)
+    names: list[str] = []
+    yield names
+    for name in set(cli_core.commands) - before:
+        del cli_core.commands[name]
+
+
+def test_cli_core_provides_cli_context_and_runs_plugins(
+    registered_commands: list[str],
+) -> None:
+    events: list[Any] = []
+
+    @cli_core.plugin_command
+    @pass_clictx
+    async def spy(clictx: CliContext) -> PluginLifespan:
+        async def work() -> None:
+            events.append(("work", clictx.itc))
+
+        events.append(("setup", clictx))
+        yield work()
+        events.append(("teardown", clictx))
+
+    result = CliRunner().invoke(cli_core, ["spy"], standalone_mode=False)
+    assert result.exception is None
+
+    assert [e[0] for e in events] == ["setup", "work", "teardown"]
+    clictx = events[0][1]
+    assert isinstance(clictx, CliContext)
+    assert isinstance(clictx.itc, ITC)
+    assert events[1][1] is clictx.itc
+
+
+def test_cli_core_chains_plugins_sharing_itc(
+    registered_commands: list[str],
+) -> None:
+    received: list[int] = []
+
+    @cli_core.plugin_command
+    @pass_clictx
+    async def producer(clictx: CliContext) -> PluginLifespan:
+        async def work() -> None:
+            await asyncio.sleep(0.01)
+            clictx.itc.set("answer", 42)
+
+        yield work()
+
+    @cli_core.plugin_command
+    @pass_clictx
+    async def consumer(clictx: CliContext) -> PluginLifespan:
+        async def work() -> None:
+            async for value in clictx.itc.updates("answer", yield_immediately=False):
+                assert value is not None
+                received.append(value)
+                return
+
+        yield work()
+
+    result = CliRunner().invoke(
+        cli_core, ["consumer", "producer"], standalone_mode=False
+    )
+    assert result.exception is None
+    assert received == [42]
+
+
+def test_runner_runs_plugin_factories() -> None:
+    events: list[str] = []
+
+    @asynccontextmanager
+    async def lifespan() -> PluginLifespan:
+        async def work() -> None:
+            events.append("work")
+
+        yield work()
+        events.append("teardown")
+
+    runner([lifespan])
+    assert events == ["work", "teardown"]