click-plugins

click-plugins provides a single with_plugins decorator that lets a Click Group discover and attach subcommands registered by other installed Python packages through importlib.metadata entry points, without the group’s own code needing to know what plugins exist ahead of time. Each entry point is expected to resolve to a click.Command; if a plugin fails to import (a missing dependency, a syntax error in a third-party package), it’s wrapped in a BrokenCommand placeholder instead of crashing the whole CLI, so users still see the subcommand listed with a clear error and traceback when invoked.

The project is explicitly no longer actively maintained by its authors, who have deliberately structured it as a single dependency-free file (click_plugins.py) intended to be vendored directly into a consuming project rather than installed as a live PyPI dependency, trading ongoing maintenance for long-term stability of a small, frozen API.

What You Get

• The with_plugins decorator for attaching entry-point-discovered commands to a click.Group
• Support for passing an entry-point group name (string), a single EntryPoint, or a sequence of EntryPoints
• A BrokenCommand fallback that surfaces a plugin’s load traceback on invocation instead of failing the whole CLI at startup
• A dependency-free, single-file implementation designed to be vendored directly into a project

Common Use Cases

• Building extensible CLI tools where third-party packages register their own subcommands via entry_points in their packaging metadata
• Allowing a plugin ecosystem around a core CLI without the core project needing to know about plugins at release time
• Degrading gracefully when an optional plugin dependency is missing, showing a BrokenCommand instead of an unusable CLI

Under The Hood

Architecture - The library’s core is the with_plugins() decorator, which normalizes its entry_points argument (a group name string, single EntryPoint, or sequence) into a list of importlib.metadata.EntryPoint objects, then iterates them calling ep.load() and group.add_command(); any exception during load is caught and converted into a BrokenCommand, a click.Command subclass that overrides parse_args() to skip argument parsing and invoke() to print the captured traceback and exit with an error code. Tech Stack - Pure Python standard library plus a single runtime dependency on click; no other third-party dependencies, and the project intentionally avoids providing a conventional installable package structure. Code Quality - A companion click_plugins_tests.py using Python’s built-in unittest covers plugin loading, entry-point normalization across Python version differences, and broken-command behavior; the single source file is fully docstring-annotated including a runnable doctest-style usage example. API Design - The entire public surface is one decorator (with_plugins) plus the BrokenCommand class it uses internally, requiring only that a consuming project already define entry points in its packaging metadata — an intentionally minimal API given the project’s stated no-longer-actively-maintained status and vendoring-first distribution model.