click-plugins 1.1.1

为什么？

假设你开发了一个命令行界面，有人请求一个与你的项目绝对相关的功能，但会有负面影响，比如额外的依赖项、主要重构，或者可能太特定于领域而无法直接支持。与其开发一个单独的独立工具，你还可以提供一个setuptools entry point，允许其他人将你的命令行实用程序用作相关子命令的家园。你可以选择这些子命令或子组可以在哪里注册，但插件开发人员可以选择它们是否注册。你可以让所有插件与核心命令一起注册，在特殊子组中注册，跨多个子组注册，或者任何组合。

启用插件

有关更详细的示例，请参阅示例部分。

唯一的要求是使用 click.group() 时添加 click_plugins.with_plugins()，该功能负责处理附加外部命令和组。在这种情况下，核心 CLI 开发者从 core_package.cli_plugins 注册 CLI 插件。

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."""

插件开发

插件开发者需要将他们的子命令或子组注册到他们的 setup.py 入口点，该入口点由核心包加载。

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
    ''',
)

损坏和不兼容的插件

任何无法加载的子命令或子组都会被捕获并转换为 click_plugins.core.BrokenCommand()，而不是使整个 CLI 崩溃。简短的帮助信息被转换为警告消息，例如

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

如果执行子命令或组，则会打印整个堆栈跟踪。

最佳实践和额外积分

向插件开放 CLI 鼓励其他开发者独立扩展功能，但没有保证这些新功能将是“品牌化”的。插件开发者几乎肯定已经在 CLI 所属的核心包中使用了功能，因此在一个地方定义常用参数和选项可以让插件开发者重用这些标志来生成更统一的 CLI。如果 CLI 简单，也许只需在 yourpackage/cli.py 的顶部定义它们，或者对于更复杂的包，类似 yourpackage/cli/options.py 之类的。这些常见选项需要易于查找并且有良好的文档，这样插件开发者就知道应该将什么变量提供给子命令的函数，以及他们可以期望收到什么对象。别忘了记录不明显的回调。

请记住，插件开发者还可以访问父组的 ctx.obj，这对于在子命令之间传递诸如详细级别或配置值之类的信息非常有用。

以下是一些子命令可以重用的代码

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."
)

插件开发者可以通过以下方式访问此内容

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."""

安装

使用 pip

$ pip install click-plugins

从源代码

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

开发

$ 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

变更日志

查看 CHANGES.txt

作者

查看 AUTHORS.txt

许可协议

查看 LICENSE.txt