plugcli

基于click的插件式CLI工具。

plugcli 是 click 的小型扩展。它提供了一些有用的功能，包括

• 插件注册系统，允许用户创建的插件通过在给定的命名空间中安装或向指定的目录添加插件文件来注册。
• 一个CLI类，它使用该插件注册系统来注册新子命令，并将子命令分开到用于 --help 文档的各个部分。
• 工具，用于在不同子命令之间复用参数，有助于确保一致的用户界面。尽管许多功能已经通过 click 实现，但 plugcli 中的工具在 click 的回调可能不足的情况下特别有用，例如，当参数解析的顺序很重要时。

安装 plugcli

plugcli 可以通过标准机制安装： pip install plugcli；或 conda install -c conda-forge plugcli，或者使用 setuptools 从源代码安装（python setup.py install 等）。它唯一的直接依赖项是 click。

插件注册

插件注册系统旨在处理那些本质上可以被视为调度表条目的插件。也就是说，这些是设计为提供可选额外功能的插件。CLI的子命令是一个例子，plugcli 为此提供了特定的工具。其他例子可能包括在处理用户输入文件时支持额外的关键字，或在交互式用户界面的菜单中支持其他选项。

编写插件的基本方法是使用 plugcli.Plugin 类的某个子类封装用户定义的功能，该类还可以封装程序有用的附加元数据。例如，plugcli.CommandPlugin 类还接受一个 section 标签，用于告诉插件命令应在哪个帮助部分中列出。

程序通过创建一个或多个 PluginLoader 定义用户可以放置插件的位置。两个具体的 PluginLoader 类是 FilePluginLoader，它接受一个目录并在该目录中的 Python 文件中搜索任何插件，以及 NamespacePluginLoader，它接受一个表示 Python 命名空间的字符串并在该命名空间中找到的模块/子包中搜索任何插件。

CLI 类

plugcli.CLI 类是 click.CLI 的子类，增加了从 plugcli 插件结构中加载命令的支持，并在 --help 中按开发者定义的节对命令进行排序。

用户必须子类化 plugcli.CLI。子类应将类变量 COMMAND_SECTIONS 设置为用于排序帮助中插件的节名称列表。子类还应实现 get_installed_plugins 方法，该方法使用一系列 PluginLoader，这些加载器确定插件将被找到和注册的位置。

可重用参数

plugcli 的可重用参数的目标是通过封装可共享的参数的名称和行为来确保不同子命令之间的一致性。这是通过使用 plugcli.Option 和 plugcli.Argument 类来实现的，这些类接受与 click.option 和 click.parameter 装饰器相同的参数，以及一个关键字参数 getter，它接受一个可调用的函数，该函数将 click 处理后的用户输入转换为 CLI 基础库代码中可使用的对象。这接受一个用户定义的 context 字典，它比标准的 click 回调提供更多的灵活性。

您可以使用 .parameter() 方法为这些参数之一创建一个标准的 click 装饰器，允许单个参数实例在多个子命令中重用。在 plugcli 参数初始化中设置的 click 参数可以由传递给 .parameter 方法的关键字参数覆盖，允许在特殊情况下进行一些自定义（例如，允许参数被调用不同次数）的同时保持大部分一致性。

历史

plugcli 最初是 OpenPathSampling CLI 的一部分。随着它越来越明显，它填补了一个小但有用的空白，并且可以在其他项目中重用，因此将其重构为单独的包。