pycomplete

一个用于为您的CLI应用生成静态完成脚本的Python库

安装

pycomplete 需要 Python 3.6 或更高版本，您可以通过 PyPI 安装它

$ pip install pycomplete

用法

使用 pycomplete，可以为兼容给定shell的CLI应用生成完成脚本。该脚本将结果输出到 stdout，允许您将输出重定向到您选择的文件。

pycomplete 根据您使用的CLI框架接受不同类型的对象。对于 argparse，期望 argparse.ArgumentParser，而对于 click，则可以是 click.Command 或 click.Context。 pycomplete 会智能地处理。

您放置文件的位置将取决于您使用的shell和操作系统。您的特定配置也可能决定这些脚本需要放置的位置。

请注意，pycomplete 需要在与目标CLI应用相同的环境中安装才能正常工作。

以下是Unix和类似操作系统（如GNU/Linux）下支持的三种shell的一些常见设置。

BASH

完成文件通常存储在 /etc/bash_completion.d/。运行命令

$ pycomplete "myscript:parser" bash > /etc/bash_completion.d/_myscript

您可能需要注销并重新登录shell会话才能使更改生效。

FISH

Fish完成文件通常存储在$HOME/.config/fish/completions/。运行命令

$ pycomplete "myscript:parser" fish > $HOME/.config/fish/completions/myscript.fish

您可能需要注销并重新登录shell会话才能使更改生效。

ZSH

ZSH完成通常存储在您的 $fpath 变量列出的任何目录中。要使用这些完成，您必须将生成的脚本添加到这些目录之一，或者将其添加到该列表中。

在不确定使用哪个目录的情况下，添加自定义目录通常是最佳选择。首先创建目录，例如，我们将创建一个隐藏目录在我们的 $HOME 目录内

$ mkdir ~/.zfunc

然后将以下行添加到您的 .zshrc 文件中，在 compinit 前面

$ fpath+=~/.zfunc

运行命令

$ pycomplete "myscript:parser" zsh > ~/.zfunc/_myscript

然后您必须注销并重新登录，或者简单地运行

$ exec zsh

以使新的补全生效。

PowerShell

PowerShell 中没有补全脚本的默认位置。可能需要在其配置文件中执行脚本

PS > mkdir $PROFILE\..\Completions
PS > echo @'
Get-ChildItem "$PROFILE\..\Completions\" | ForEach-Object {
    . $_.FullName
}
'@ | Out-File -Append -Encoding utf8 $PROFILE

确保您设置了正确的 执行策略

PS > Set-ExecutionPolicy Unrestricted -Scope CurrentUser

运行命令以生成脚本

PS > pycomplete "myscript:parser" powershell | Out-File -Encoding utf8 $PROFILE\..\Completions\myscript_completion.ps1

您可能需要注销并重新登录shell会话才能使更改生效。

自定义位置

或者，您可以将这些文件保存到您选择的位置，例如 $HOME 中的自定义目录。这样做将需要您在登录脚本中添加适当的指令，如 source。请查阅您shell的文档了解如何添加此类指令。

与现有 CLI 应用程序集成

pycomplete 也可以用作 Python 库，允许您与现有的 CLI 应用程序集成。

from pycomplete import Completer
from mypackage.cli import parser

completer = Completer(parser)
print(completer.render())

查看 examples/ 文件夹以获取工作应用程序的完整示例。

它与 argcomplete 有何不同？

argcomplete 与 click-completion 一起可以生成 shell 补全脚本。然而，它们的工作方式不同，即当请求匹配的标记时，动态检索命令和选项。当导入 CLI 应用程序成本较高时，这会导致性能下降。另一方面，pycomplete 生成 静态和固定 脚本，其中包含所有所需信息。此外，argcomplete 和 click-completion 都适用于特定框架。人们可能会注意到静态补全的缺点也很明显——当命令和/或选项更新时，用户必须重新生成脚本。幸运的是，在大多数包管理器（如 homebrew）中，补全脚本是包的一部分，并与其捆绑在一起，所以这不应该成问题。

限制

只有选项和子命令可以自动补全，位置参数不会补全，因为用户通常期望在这种情况下路径建议可以工作。

支持的 CLI 框架

• argparse.ArgumentParser
• click.Command，click.Context
• 更多将添加