click-async-plugins 0.7.4__tar.gz → 0.9.0__tar.gz

{click_async_plugins-0.7.4 → click_async_plugins-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: click-async-plugins
-Version: 0.7.4
+Version: 0.9.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
@@ -94,8 +94,62 @@ its running via key presses. Hit `?` to get an overview of commands available.
 
 Looking forward to your feedback.
 
-## TODO
+## Plugin dependencies
 
-Test coverage… yeah, there's none right now :(
+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.4 → click_async_plugins-0.9.0}/README.md

@@ -71,8 +71,62 @@ its running via key presses. Hit `?` to get an overview of commands available.
 
 Looking forward to your feedback.
 
-## TODO
+## Plugin dependencies
 
-Test coverage… yeah, there's none right now :(
+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.4 → click_async_plugins-0.9.0}/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.7.4'
-__version_tuple__ = version_tuple = (0, 7, 4)
+__version__ = version = '0.9.0'
+__version_tuple__ = version_tuple = (0, 9, 0)
 
 __commit_id__ = commit_id = None

{click_async_plugins-0.7.4 → click_async_plugins-0.9.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.4 → click_async_plugins-0.9.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.7.4 → click_async_plugins-0.9.0}/click_async_plugins/debug.py

@@ -10,7 +10,7 @@ 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 typing import Any, Coroutine, Never, cast
 
 from click_async_plugins.util import CliContext
 
@@ -44,6 +44,10 @@ def _name_for_coro(coro: Coroutine[Any, Any, Any] | None) -> str:
     return "(unknown)"
 
 
+def interrupt(clictx: CliContext) -> Never:
+    raise KeyboardInterrupt
+
+
 def debug_info(clictx: CliContext) -> str:
     """Prints debugging information on tasks and CliContext"""
     ret = "*** BEGIN DEBUG INFO: ***\n"
@@ -58,7 +62,7 @@ def debug_info(clictx: CliContext) -> str:
     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"
+        ret += f"  {attr:>{maxlen}s} = {value!r} (id:{id(value)})\n"
     return ret + "*** END DEBUG INFO: ***"
 
 
@@ -188,6 +192,7 @@ async def monitor_stdin_for_debug_commands[ContextT: CliContext](
     decrease_loglevel.__doc__ = "Decrease the logging level"
 
     map = {
+        0x3: KeyAndFunc(r"^C", interrupt),
         0xA: KeyAndFunc(r"\n", echo_newline),
         0xD: KeyAndFunc(r"\n", echo_newline),
         0x1B: KeyAndFunc("<Esc>", terminal_block),

click_async_plugins-0.9.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.4 → click_async_plugins-0.9.0}/click_async_plugins/itc.py

@@ -1,4 +1,5 @@
 import asyncio
+import inspect
 import logging
 import time
 from collections import defaultdict
@@ -8,6 +9,31 @@ from typing import Any
 logger = logging.getLogger(__name__)
 
 
+def _caller(depth: int = 1) -> str:
+    """Return a description of a calling frame, ``depth`` frames up.
+
+    ``depth`` counts frames starting at this helper, so ``depth=1`` (the
+    default) reports the direct caller of this helper, ``depth=2`` the frame
+    above that, and so on. Returns a ``file:lineno in function`` string, or
+    a fallback marker if the frame cannot be determined.
+
+    Raises:
+        ValueError: If ``depth`` is less than 1.
+    """
+    if depth < 1:
+        raise ValueError(f"depth must be >= 1, got {depth}")
+
+    frame = inspect.currentframe()
+    try:
+        for _ in range(depth):
+            frame = frame.f_back if frame is not None else None
+        if frame is None:
+            return "<unknown>"
+        return f"{frame.f_code.co_filename}:{frame.f_lineno} in {frame.f_code.co_name}"
+    finally:
+        del frame
+
+
 class ITC:
     def __init__(self) -> None:
         self._events: dict[str, list[asyncio.Event]] = defaultdict(list[asyncio.Event])
@@ -25,13 +51,20 @@ class ITC:
         return f"{ret}{'    ' if i > 0 else ''})"
 
     def set(self, key: str, obj: Any) -> None:
+        if logger.isEnabledFor(logging.DEBUG):
+            logger.debug(f"set('{key}', {obj!r}) called from {_caller(2)}")
         self._objects[key] = obj
         self.fire(key)
 
     def get(self, key: str, default: Any = None) -> Any:
-        return self._objects.get(key, default)
+        value = self._objects.get(key, default)
+        if logger.isEnabledFor(logging.DEBUG):
+            logger.debug(f"get('{key}') -> {value!r} called from {_caller(2)}")
+        return value
 
     def fire(self, key: str) -> None:
+        if logger.isEnabledFor(logging.DEBUG):
+            logger.debug(f"fire('{key}') called from {_caller(2)}")
         logger.debug(f"Notifying subscribers of update to '{key}'…")
         for event in self._events.get(key) or []:
             event.set()
@@ -47,6 +80,9 @@ class ITC:
     ) -> AsyncGenerator[Any | None]:
         at_most_every = 0 if at_most_every is None else at_most_every
 
+        caller = _caller(2) if logger.isEnabledFor(logging.DEBUG) else ""
+        logger.debug(f"updates('{key}') subscribing from {caller}")
+
         if timeout is not None and timeout <= 0:
             logger.warning("Updates timeout <= 0, disabling timeout…")
             timeout = None
@@ -58,10 +94,15 @@ 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:
+                value = self._objects.get(key, yield_for_no_value)
+                if logger.isEnabledFor(logging.DEBUG):
+                    logger.debug(
+                        f"updates('{key}') yielding initial {value!r} to {caller}"
+                    )
+                yield value
+
             timestamp = 0.0
             while True:
                 logger.debug(f"Waiting for update to '{key}'…")
@@ -75,8 +116,15 @@ 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)
+                if logger.isEnabledFor(logging.DEBUG):
+                    logger.debug(f"updates('{key}') yielding {value!r} to {caller}")
+                yield value
                 timestamp = time.monotonic()
 
         finally:

{click_async_plugins-0.7.4 → click_async_plugins-0.9.0}/click_async_plugins/util.py

@@ -8,6 +8,7 @@ from typing import Any, Never
 
 import click
 
+from .dependencies import resolve_dependencies
 from .itc import ITC
 from .typedefs import PluginFactory, PluginTask
 
@@ -111,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.4 → click_async_plugins-0.9.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.9.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"]