pycli-color

何时使用

当用户要求你编写 Python 命令行脚本（argparse），并希望 -h/--help 输出带统一配色高亮时，使用本技能。

目标是让所有脚本的 --help 输出呈现一致的视觉效果与可控的颜色开关策略（auto/NO_COLOR/FORCE_COLOR）。

核心规范（必须满足）

1. 机制（必须使用 argparse）

• 必须使用 argparse 。

• 必须实现 ColorHelpFormatter(argparse.HelpFormatter) 。

• 必须覆写 _format_action_invocation(self, action) 方法以控制每个 action 的 option/metavar 渲染。

• 通过 ArgumentParser(formatter_class=ColorHelpFormatter) 启用。

2. 颜色规则（token 级别）

• 任何以 - 开头的 option token（例如 -h , --title ）必须 青色 + 加粗。

• 任何 metavar/占位符 token（通常满足 p.isupper() 或包含 _ ，例如 TITLE , AJG_CSV ）必须 黄色 + 加粗。

• 其他 token 不着色。

• 每个被着色片段后必须追加 ANSI reset，避免串色。

推荐 ANSI：

• reset：\x1b[0m

• 青色加粗：\x1b[36;1m

• 黄色加粗：\x1b[33;1m

3. 颜色启用策略（可控且兼容）

必须实现：

• supports_color() -> bool

• 默认 auto：仅当 sys.stdout.isatty() 为 True 且 TERM 不是 dumb 时启用颜色

• 若环境变量 NO_COLOR 存在：强制禁用颜色

• 若 FORCE_COLOR=1 ：强制启用颜色（即便非 TTY）

• colorize(text: str, ansi_code: str) -> str ：仅在启用颜色时加 ANSI。

注意：你的环境中常见 NO_COLOR=1 全局存在；若要强制彩色，请用 FORCE_COLOR=1 python3 your_script.py -h 直接强制启用（无需清空 NO_COLOR）。

4. 最小 CLI 面（用于校验）

脚本必须包含：

• 至少一个 required=True 参数

• 至少一个可选参数

• 至少一个带 choices= 的参数

• 标准入口：if name == "main": main()

5. 测试注释（必须写入代码）

脚本中必须包含两条注释，方便手动验证：

• NO_COLOR=1 python your_script.py -h

• FORCE_COLOR=1 python your_script.py -h

推荐实现（可直接复制）

你可以直接参考项目内模板（相对路径）：

• ./scripts/demo_pycli_color.py

给未来助手的“可复制提示词”

当你以后要求我写任何 Python CLI 脚本时，可直接粘贴下面这段（无需解释背景）：

""" 请用 argparse 实现 CLI，并让 python 脚本 -h/--help 的帮助信息支持统一彩色高亮（与你的 pycli-color 规范一致）。

必须实现：

• supports_color()：默认 auto（仅 sys.stdout.isatty()==True 且 TERM != 'dumb' 启用）；若存在 NO_COLOR 则强制禁用；若 FORCE_COLOR=1 则强制启用（即便非 TTY）。

• colorize(text, ansi_code)：仅在启用颜色时包裹 ANSI，否则原样返回。

• ColorHelpFormatter(argparse.HelpFormatter)，并覆写 HelpFormatter._format_action_invocation：

• token 以 '-' 开头（-h/--title 等）→ 青色+加粗（\x1b[36;1m）

• token 为 metavar（全大写或含 '_'，TITLE/AJG_CSV 等）→ 黄色+加粗（\x1b[33;1m）

• 其他 token 不着色；每段着色后追加 reset（\x1b[0m）

• ArgumentParser(formatter_class=ColorHelpFormatter) 启用 formatter。

• CLI 至少包含：1 个 required=True 参数、1 个可选参数、1 个 choices 参数，并包含 if name == 'main': main()。

• 代码里必须保留测试注释：

• NO_COLOR=1 python3 your_script.py -h

• NO_COLOR= FORCE_COLOR=1 python3 your_script.py -h 默认使用相对路径，并保证脚本可直接运行。 """