Metadata-Version: 2.5
Name: click-async-plugins
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
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/0-testing.yml/badge.svg)](https://github.com/madduck/click-async-plugins/actions/workflows/0-testing.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) -> None:
        # 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.

## Plugin dependencies

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.
