click-plugins

Warnings

• breaking The PyPI package `click-plugins` is no longer actively maintained. Version 1.1.1.2 is the final release available via `pip install`.
  Fix: Consider migrating to alternatives or vendoring the necessary code. If you must use `click-plugins`, pin your dependency to `click-plugins==1.1.1.2`.
• breaking GitHub release 2.0 is *not* a continuation of the PyPI package. It restructured the project for vendoring and explicitly states it 'no longer directly supports building a `pip` package'.
  Fix: Do not attempt to install version 2.0 via `pip` or expect it to be a drop-in replacement for earlier PyPI versions. It's intended for direct inclusion in other projects.
• gotcha Version 1.1 contained a mismatch between its stated version and `click_plugins.__version__`. It was superseded by 1.1.1.
  Fix: Avoid using version 1.1; use 1.1.1 or 1.1.1.2 instead.
• gotcha The primary mechanism for discovering commands relies on setuptools entry points. Misconfiguration of `setup.py` or `pyproject.toml` can lead to commands not being discovered.
  Fix: Carefully review your `pyproject.toml` (or `setup.py`) to ensure the `[options.entry_points]` section correctly defines your plugin groups (e.g., `click_commands = ...`) and points to the correct functions.

Install

• pip install click-plugins Install the last PyPI release

Imports

• with_plugins

  from click_plugins import with_plugins

  This decorator is the primary mechanism for adding plugin support to a Click group.

Quickstart

This quickstart demonstrates how to use `with_plugins` to enable a Click group to discover commands via setuptools entry-points. The `ep_group` parameter specifies the entry-point group to look for. For this example to be fully functional, you would typically define entry points in your `setup.py` or `pyproject.toml` under a section like `[options.entry_points]`, e.g., `click_commands = my_package.my_plugins:my_command_function`.

import click
from click_plugins import with_plugins
import os

# Example of a 'plugin' that would be discovered via entry points
# In your setup.py/pyproject.toml, you'd define:
# [options.entry_points]
# click_commands = click_plugins_example.plugins:hello_plugin

@click.group()
def plugins():
    "A group for plugin commands."
    pass

@plugins.command()
def hello_plugin():
    click.echo("Hello from a plugin!")

@with_plugins(ep_group='click_commands')
@click.group()
def cli():
    "A CLI with plugin support."
    pass

# To make the quickstart runnable without a full setup.py, 
# we'll simulate the entry point discovery by directly adding it.
# In a real scenario, this wouldn't be necessary.
cli.add_command(plugins)

if __name__ == '__main__':
    # In a real environment, you'd run `cli()` directly.
    # For this quickstart, we're demonstrating the integration.
    # For testing, ensure 'plugins' command is added.
    cli()