Skip to main content

An extension module for click to enable registering CLI commands via setuptools entry-points.

Project description

This PyPI package is no longer actively maintained, but the underlying library can be vendored. See homepage for more information.

An extension module for click to register external CLI commands via setuptools entry-points.

Why?

Lets say you develop a commandline interface and someone requests a new feature that is absolutely related to your project but would have negative consequences like additional dependencies, major refactoring, or maybe its just too domain specific to be supported directly. Rather than developing a separate standalone utility you could offer up a setuptools entry point that allows others to use your commandline utility as a home for their related sub-commands. You get to choose where these sub-commands or sub-groups CAN be registered but the plugin developer gets to choose they ARE registered. You could have all plugins register alongside the core commands, in a special sub-group, across multiple sub-groups, or some combination.

Enabling Plugins

For a more detailed example see the examples section.

The only requirement is decorating click.group() with click_plugins.with_plugins() which handles attaching external commands and groups. In this case the core CLI developer registers CLI plugins from core_package.cli_plugins.

from pkg_resources import iter_entry_points

import click
from click_plugins import with_plugins


@with_plugins(iter_entry_points('core_package.cli_plugins'))
@click.group()
def cli():
    """Commandline interface for yourpackage."""

@cli.command()
def subcommand():
    """Subcommand that does something."""

Developing Plugins

Plugin developers need to register their sub-commands or sub-groups to an entry-point in their setup.py that is loaded by the core package.

from setuptools import setup

setup(
    name='yourscript',
    version='0.1',
    py_modules=['yourscript'],
    install_requires=[
        'click',
    ],
    entry_points='''
        [core_package.cli_plugins]
        cool_subcommand=yourscript.cli:cool_subcommand
        another_subcommand=yourscript.cli:another_subcommand
    ''',
)

Broken and Incompatible Plugins

Any sub-command or sub-group that cannot be loaded is caught and converted to a click_plugins.core.BrokenCommand() rather than just crashing the entire CLI. The short-help is converted to a warning message like:

Warning: could not load plugin. See ``<CLI> <command/group> --help``.

and if the sub-command or group is executed the entire traceback is printed.

Best Practices and Extra Credit

Opening a CLI to plugins encourages other developers to independently extend functionality independently but there is no guarantee these new features will be “on brand”. Plugin developers are almost certainly already using features in the core package the CLI belongs to so defining commonly used arguments and options in one place lets plugin developers reuse these flags to produce a more cohesive CLI. If the CLI is simple maybe just define them at the top of yourpackage/cli.py or for more complex packages something like yourpackage/cli/options.py. These common options need to be easy to find and be well documented so that plugin developers know what variable to give to their sub-command’s function and what object they can expect to receive. Don’t forget to document non-obvious callbacks.

Keep in mind that plugin developers also have access to the parent group’s ctx.obj, which is very useful for passing things like verbosity levels or config values around to sub-commands.

Here’s some code that sub-commands could re-use:

from multiprocessing import cpu_count

import click

jobs_opt = click.option(
    '-j', '--jobs', metavar='CORES', type=click.IntRange(min=1, max=cpu_count()), default=1,
    show_default=True, help="Process data across N cores."
)

Plugin developers can access this with:

import click
import parent_cli_package.cli.options


@click.command()
@parent_cli_package.cli.options.jobs_opt
def subcommand(jobs):
    """I do something domain specific."""

Installation

With pip:

$ pip install click-plugins

From source:

$ git clone https://github.com/click-contrib/click-plugins.git
$ cd click-plugins
$ python setup.py install

Developing

$ git clone https://github.com/click-contrib/click-plugins.git
$ cd click-plugins
$ pip install -e .\[dev\]
$ pytest tests --cov click_plugins --cov-report term-missing

Changelog

See CHANGES.txt

Authors

See AUTHORS.txt

License

See LICENSE.txt

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

click_plugins-1.1.1.2.tar.gz (8.3 kB view details)

Uploaded Source

Built Distribution

click_plugins-1.1.1.2-py2.py3-none-any.whl (11.1 kB view details)

Uploaded Python 2Python 3

File details

Details for the file click_plugins-1.1.1.2.tar.gz.

File metadata

  • Download URL: click_plugins-1.1.1.2.tar.gz
  • Upload date:
  • Size: 8.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.13.3

File hashes

Hashes for click_plugins-1.1.1.2.tar.gz
Algorithm Hash digest
SHA256 d7af3984a99d243c131aa1a828331e7630f4a88a9741fd05c927b204bcf92261
MD5 c7364b4d9df45deb2e46f165d8c882fa
BLAKE2b-256 c3a434847b59150da33690a36da3681d6bbc2ec14ee9a846bc30a6746e5984e4

See more details on using hashes here.

File details

Details for the file click_plugins-1.1.1.2-py2.py3-none-any.whl.

File metadata

File hashes

Hashes for click_plugins-1.1.1.2-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 008d65743833ffc1f5417bf0e78e8d2c23aab04d9745ba817bd3e71b0feb6aa6
MD5 ff1be4ecff48993c7cff2c07cf0db85c
BLAKE2b-256 3d9a2abecb28ae875e39c8cad711eb1186d8d14eab564705325e77e4e6ab9ae5

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page