SuperAPI AI 工具集

typer-cli-completion

编程与开发

查看项目

更新于 10-24 22:07

技能介绍

用途:为基于 Typer(底层为 Click)的 Python 命令行工具提供一种在不依赖 shellingham 的情况下生成 shell 补全脚本的方式,用于在非 shell 父进程中完成补全安装。

问题背景:Typer/Click 自带的 --install-completion 与 --show-completion 通过 shellingham 检测父进程 shell。shellingham 检查父进程链,而不读取 $SHELL 环境变量;当父进程不是已知 shell 时(例如智能体运行时、node 宿主、GitHub Actions runner、Docker entrypoint、从 Python 以子进程方式调用的 uv 安装工具、chezmoi apply 等),检测会失败,Typer 输出“Shell None is not supported”。资料指出,设置 $SHELL=/bin/zsh 无效,因为 shellingham 按设计忽略该环境变量。

主要能力:新增一个显式的 completion <shell> 子命令,把 shell 名称作为参数,直接调用 Click 的补全类,包括用 get_completion_class(shell) 获取补全类、用 typer.main.get_command(app) 取得 Click 命令对象,并用 cls(cli=..., ctx_args={}, prog_name="my-cli", complete_var="_MY_CLI_COMPLETE") 构造补全对象,最后 print(comp.source()) 输出脚本。不支持的 shell 会打印错误提示并以配置错误退出码退出。

使用方式:执行类似 my-cli completion zsh > ~/.zfunc/_my-cli 的命令,即可从任意父进程生成补全脚本。complete_var 需使用 Click 约定形式 _<PROG_NAME>_COMPLETE(短横线替换为下划线并大写);写错会导致静默失败,即脚本能安装但补全不生效。若接入 dotfiles 式补全注册表,可在表中为每个 CLI 增加一行,例如 chezmoi 的 .chezmoidata/completions.toml 中写 "my-cli" = "my-cli completion zsh",无需自写解析器,因为 Typer 已掌握 CLI 的全部参数。

验证:资料建议为子命令增加回归测试,断言每个受支持 shell 能输出可用脚本、不受支持的 shell 以非零退出码退出。给出的测试使用 typer.testing.CliRunner,分别检查 zsh 输出含 compdef、bash 输出含 complete、不支持 shell(tcsh)输出含 not supported。资料还列出各 shell 的断言标记:zsh 的 #compdef 或 compdef,bash 的 complete -o nosort -F,fish 的 complete -c。

限制与说明:资料不建议直接改造 Typer 的 --install-completion,因为其回调与 shellingham 紧密绑定且无回退钩子,覆盖需 monkey-patch 私有 API;显式子命令只需在自身代码中调用一次 Click。文中给出的代码含自定义退出码 EXIT_CONFIG_ERROR = 2 和占位 prog_name "my-cli",实际需按项目调整。资料给出两个参考实现位置(git-repo-agent 的 main.py 中 completion 命令及其 tests/test_completion.py 四个回归测试),并提及与 python-packaging 的 [project.scripts] 入口点、agent-cli-worktree-safety 的相关性。