壳完成

2.0 版中的新功能。

单击可以为命令、选项和选择值提供制表符补全。支持 Bash、Zsh 和 Fish

只有通过入口点安装和调用脚本时才能完成，而不是通过 python 命令。参见 Setuptools 集成。

它完成了什么

通常，shell 补全支持将补全命令、选项以及类型为 click.Choice 的任何选项或参数值。仅当至少输入了一个破折号时才会列出选项。

$ repo <TAB><TAB>
clone    commit   copy     delete   setuser
$ repo clone -<TAB><TAB>
--deep     --help     --rev      --shallow  -r

通过提供返回字符串列表的 autocompletion 函数，可以为参数和选项值提供自定义完成。当建议需要动态生成完成时间时，这很有用。回调函数将传递 3 个关键字参数：

ctx - 当前命令上下文。
args - 传入的参数列表。
incomplete - 正在完成的部分字。如果尚未输入任何字符，则可能为空字符串。

以下是使用回调函数生成动态建议的示例：

import os

def get_env_vars(ctx, args, incomplete):
    return [k for k in os.environ.keys() if incomplete in k]

@click.command()
@click.argument("envvar", type=click.STRING, autocompletion=get_env_vars)
def cmd1(envvar):
    click.echo('Environment variable: %s' % envvar)
    click.echo('Value: %s' % os.environ[envvar])

完成帮助字符串

ZSH 和 fish 支持显示完成的文档字符串。这些来自选项和子命令的帮助参数。对于动态生成的完成，可以通过返回元组而不是字符串来提供帮助字符串。元组的第一个元素是完成，第二个是要显示的帮助字符串。

以下是使用回调函数生成带有帮助字符串的动态建议的示例：

import os

def get_colors(ctx, args, incomplete):
    colors = [('red', 'a warm color'),
              ('blue', 'a cool color'),
              ('green', 'the other starter color')]
    return [c for c in colors if incomplete in c[0]]

@click.command()
@click.argument("color", type=click.STRING, autocompletion=get_colors)
def cmd1(color):
    click.echo('Chosen color is %s' % color)

激活

为了激活 shell 补全，您需要通知您的 shell 补全可用于您的脚本。任何 Click 应用程序都会自动提供支持。如果使用特殊的 _<PROG_NAME>_COMPLETE 变量执行程序，则会触发完成机制而不是普通命令。 <PROG_NAME> 是大写的可执行文件名称，破折号由下划线代替。

如果您的工具名为 foo-bar，则该变量名为 _FOO_BAR_COMPLETE。通过使用 source_{shell} 值导出它，它将输出要评估的激活脚本。

以下是 foo-bar 脚本的示例。

对于 Bash，将其添加到 ~/.bashrc：

eval "$(_FOO_BAR_COMPLETE=source_bash foo-bar)"

对于 Zsh，将其添加到 ~/.zshrc：

eval "$(_FOO_BAR_COMPLETE=source_zsh foo-bar)"

对于 Fish，将其添加到 ~/.config/fish/completions/foo-bar.fish：

eval (env _FOO_BAR_COMPLETE=source_fish foo-bar)

打开一个新的 shell 以启用完成。或者直接在当前 shell 中运行 eval 命令来临时启用它。

激活脚本

上述 eval 示例将在每次 shell 启动时调用您的应用程序。这可能会显着减慢 shell 启动时间。

或者，将生成的完成代码导出为要执行的静态脚本。您可以随构建一起发布此文件；像 Git 这样的工具可以做到这一点。至少 Zsh 也会缓存完成文件的结果，但不会缓存 eval 脚本。

对于 Bash：

_FOO_BAR_COMPLETE=source_bash foo-bar > foo-bar-complete.sh

对于 Zsh：

_FOO_BAR_COMPLETE=source_zsh foo-bar > foo-bar-complete.sh

对于鱼：

_FOO_BAR_COMPLETE=source_zsh foo-bar > foo-bar-complete.sh

在 .bashrc 或 .zshrc 中，源脚本而不是 eval 命令：

. /path/to/foo-bar-complete.sh

对于 Fish，将文件添加到 completions 目录中：

_FOO_BAR_COMPLETE=source_fish foo-bar > ~/.config/fish/completions/foo-bar-complete.fish

Shell 完成 — 单击文档

壳完成

它完成了什么

完成帮助字符串

激活

激活脚本