Bash tab completion for argparse
项目描述
Tab complete all the things!
Argcomplete为您的Python应用程序提供简单、可扩展的命令行参数tab自动完成。
它假设以下两点
您使用bash或zsh作为您的shell
您使用argparse来管理您的命令行参数/选项
如果您的程序有很多选项或子解析器，并且如果您的程序可以为您的参数/选项值动态建议完成（例如，如果用户正在浏览网络资源），则Argcomplete特别有用。
安装
pip install argcomplete activate-global-python-argcomplete
有关第二步的详细信息，请参阅以下激活全局完成。
刷新您的shell环境（启动新的shell）。
概述
将PYTHON_ARGCOMPLETE_OK标记和argcomplete.autocomplete()的调用添加到您的Python应用程序中，如下所示
#!/usr/bin/env python
# PYTHON_ARGCOMPLETE_OK
import argcomplete, argparse
parser = argparse.ArgumentParser()
...
argcomplete.autocomplete(parser)
args = parser.parse_args()
...通过运行register-python-argcomplete将您的Python应用程序注册到shell的完成框架中
eval "$(register-python-argcomplete my-python-app)"
引号很重要；没有引号注册将失败。请参阅下面的全局完成部分，了解一种无需单独为每个应用程序注册即可一般启用argcomplete的方法。
argcomplete.autocomplete(parser)
此方法是模块的入口点。必须在完成ArgumentParser构建之后调用此方法，但在调用ArgumentParser.parse_args()方法之前调用。该方法查找由完成钩子shellcode设置的环境外部变量，如果存在，则收集补全项，将它们打印到输出流（默认为文件描述符8），然后退出。否则，它立即返回到调用者。
指定补全器
您可以为您选项和参数指定自定义补全函数。支持两种样式：可调用和readline风格。可调用补全器更简单。它们使用以下关键字参数调用：
prefix：命令行上光标之前最后一个单词的前缀文本。对于动态补全器，这可以用来减少生成可能补全项所需的工作量。
action：被此补全器调用的argparse.Action实例。
parser：执行动作的argparse.ArgumentParser实例。
parsed_args：到目前为止的参数解析结果（通常由ArgumentParser.parse_args()返回的argparse.Namespace args对象）。
补全器可以将它们的补全项作为字符串的可迭代对象或字符串到其描述的映射（字典）（zsh将描述显示为与补全项一起的上下文帮助）。一个环境变量名称的示例补全器可能如下所示
def EnvironCompleter(**kwargs):
return os.environ要指定参数或选项的补全器，设置其关联动作的completer属性。在定义时这样做的一种简单方法是
from argcomplete.completers import EnvironCompleter
parser = argparse.ArgumentParser()
parser.add_argument("--env-var1").completer = EnvironCompleter
parser.add_argument("--env-var2").completer = EnvironCompleter
argcomplete.autocomplete(parser)如果您为argparse选项或参数指定了choices关键字（并且没有指定补全器），则它将被用于补全。
一个初始化为该动作可能值的全部可能集合的补全器可能如下所示
class ChoicesCompleter(object):
def __init__(self, choices):
self.choices = choices
def __call__(self, **kwargs):
return self.choices以下两种指定静态选择集的方法在补全目的上等效
from argcomplete.completers import ChoicesCompleter
parser.add_argument("--protocol", choices=('http', 'https', 'ssh', 'rsync', 'wss'))
parser.add_argument("--proto").completer=ChoicesCompleter(('http', 'https', 'ssh', 'rsync', 'wss'))注意：如果您使用 choices=<completions> 选项，argparse 将默认在 --help 输出中显示所有这些选项。要防止这种情况，请设置 metavar（例如 parser.add_argument("--protocol", metavar="PROTOCOL", choices=('http', 'https', 'ssh', 'rsync', 'wss'))）。
以下 脚本 使用 parsed_args 和 Requests 查询 GitHub 组织的公开成员，并完成他们的姓名，然后打印成员描述。
#!/usr/bin/env python
# PYTHON_ARGCOMPLETE_OK
import argcomplete, argparse, requests, pprint
def github_org_members(prefix, parsed_args, **kwargs):
resource = "https://api.github.com/orgs/{org}/members".format(org=parsed_args.organization)
return (member['login'] for member in requests.get(resource).json() if member['login'].startswith(prefix))
parser = argparse.ArgumentParser()
parser.add_argument("--organization", help="GitHub organization")
parser.add_argument("--member", help="GitHub member").completer = github_org_members
argcomplete.autocomplete(parser)
args = parser.parse_args()
pprint.pprint(requests.get("https://api.github.com/users/{m}".format(m=args.member)).json())./describe_github_user.py --organization heroku --member <TAB>
如果您想向 completer 库 添加有用的补全程序，请发送 pull request！
Readline 风格的补全程序
readline 模块在 rlcompleter 中定义了一个补全协议。argcomplete 也支持 Readline 风格的补全程序，因此您可以在交互式 readline 驱动的 shell 和命令行上使用相同的补全对象。例如，您可以使用 IPython 提供的 Readline 风格补全程序，在 IPython shell 中获取类似的自省补全。
import IPython
parser.add_argument("--python-name").completer = IPython.core.completer.Completer()argcomplete.CompletionFinder.rl_complete 也可以用来将 argparse 解析器作为 readline 补全程序插入。
在补全程序中打印警告
当 argcomplete 运行时，正常的 stdout/stderr 输出将被暂停。不过，当用户按下 <TAB> 时，打印补全生成失败的原因可能是适当的。为此，请使用 warn。
from argcomplete import warn
def AwesomeWebServiceCompleter(prefix, **kwargs):
if login_failed:
warn("Please log in to Awesome Web Service to use autocompletion")
return completions使用自定义的补全验证器
默认情况下，argcomplete 通过检查补全是否以补全程序提供的词缀开头来验证您的补全。您可以通过向 argcomplete.autocomplete() 提供关键字参数 validator 来覆盖此验证检查。
def my_validator(completion_candidate, current_input):
"""Complete non-prefix substring matches."""
return current_input in completion_candidate
argcomplete.autocomplete(parser, validator=my_validator)全局补全
在全局补全模式下，您不需要单独注册每个 argcomplete 兼容的可执行文件。相反，shell 将在它为可执行文件运行补全时查找字符串 PYTHON_ARGCOMPLETE_OK，如果在开头 1024 字节中找到，则将遵循上述描述的 argcomplete 协议。
此外，对于作为 python <script> 和 python -m <module> 运行的脚本，也会激活补全。如果您在同一个系统上使用多个 Python 版本，用于运行脚本的版本必须已安装 argcomplete。
如果您选择不使用全局补全，或者发布一个依赖于argcomplete的补全模块，您必须使用以下命令显式注册您的脚本：eval "$(register-python-argcomplete my-python-app)"。标准补全模块注册规则适用：也就是说，脚本名称被直接传递给complete，这意味着只有在完全按照注册的方式调用时才会进行制表符补全。在上面的示例中，my-python-app必须在路径中，并且用户必须尝试用该名称完成它。仅此一行不会允许您补全./my-python-app或/path/to/my-python-app。
激活全局补全
脚本activate-global-python-argcomplete将全局补全脚本bash_completion.d/_python-argcomplete安装到系统中的合适位置，适用于bash和zsh。具体位置取决于您的平台以及您是否使用sudo在全局范围内安装argcomplete，还是本地（在用户的主目录中）安装。
zsh 支持
Argcomplete支持zsh。除了bash中的普通补全外，zsh还允许您将argparse帮助字符串作为补全描述。argcomplete包含的所有shellcode都与bash和zsh兼容，因此相同的补全器命令activate-global-python-argcomplete和eval "$(register-python-argcomplete my-python-app)"也适用于zsh。
Python 支持
Argcomplete需要Python 3.7及以上版本。
其他shell的支持
Argcomplete维护者只为Linux和MacOS上的bash和zsh shell提供支持。有关其他shell和平台（包括fish、tcsh、xonsh、powershell和Windows）的相关资源，请参阅contrib目录。
常见问题
如果全局补全不能补全您的脚本，bash可能已注册了一个默认补全函数
$ complete | grep my-python-app complete -F _minimal my-python-app
您可以通过重新启动shell或运行complete -r my-python-app来修复此问题。
调试
在您的shell中设置_ARC_DEBUG变量，每次运行argcomplete时都会启用详细调试输出。这可能会破坏您终端的命令行组合状态，但如果有问题，可以查看补全器的内部状态。
致谢
受Martin Blais的optcomplete模块的启发和指导。
链接
错误
请将错误、问题、功能请求等报告到GitHub。
许可证
版权 2012-2023，Andrey Kislyuk和argcomplete贡献者。根据Apache License，版本2.0的条款许可。在源代码副本和衍生作品中分发LICENSE和NOTICE文件是按照Apache License的指定必须的。
下载文件
下载适用于您平台的应用程序文件。如果您不确定选择哪个，请了解有关安装包的更多信息。
