pycli-color

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

pycli-color

何时使用

When to Use

当用户要求你编写 Python 命令行脚本（argparse），并希望

-h/--help

输出带统一配色高亮时，使用本技能。

目标是让所有脚本的

--help

输出呈现一致的视觉效果与可控的颜色开关策略（auto/NO_COLOR/FORCE_COLOR）。

Use this skill when you are requested to write Python command-line scripts (using argparse) and the user wants the

-h/--help

output to have consistent color highlighting. The goal is to ensure that the

--help

output of all scripts presents a consistent visual effect and a controllable color toggle strategy (auto/NO_COLOR/FORCE_COLOR).

核心规范（必须满足）

Core Specifications (Mandatory)

1) 机制（必须使用 argparse）

1) Mechanism (Must use argparse)

必须使用
```
argparse
```
。

必须实现

ColorHelpFormatter(argparse.HelpFormatter)

。

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

通过

ArgumentParser(formatter_class=ColorHelpFormatter)

启用。

Must use
```
argparse
```
.

Must implement

ColorHelpFormatter(argparse.HelpFormatter)

Must override the
```
_format_action_invocation(self, action)
```
method to control the rendering of option/metavar for each action.

Enable it via

ArgumentParser(formatter_class=ColorHelpFormatter)

2) 颜色规则（token 级别）

2) Color Rules (Token Level)

任何以
```
-
```
开头的 option token（例如
```
-h
```
,
```
--title
```
）必须 青色 + 加粗。
任何 metavar/占位符 token（通常满足
```
p.isupper()
```
或包含
```
_
```
，例如
```
TITLE
```
,
```
AJG_CSV
```
）必须 黄色 + 加粗。
其他 token 不着色。
每个被着色片段后必须追加 ANSI reset，避免串色。

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

3) Color Enablement Strategy (Controllable and Compatible)

必须实现：

```
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）。

Must implement:

```
supports_color() -> bool
```
- Default auto: Enable color only when
```
sys.stdout.isatty()
```
  is True and
```
TERM
```
  is not
```
dumb
```
- If the
```
NO_COLOR
```
  environment variable exists: Force disable color
- If
```
FORCE_COLOR=1
```
  : Force enable color (even in non-TTY environments)
```
colorize(text: str, ansi_code: str) -> str
```
: Wrap text with ANSI codes only when color is enabled.

Note: It is common for

NO_COLOR=1

to be set globally in your environment; to force color output, use

FORCE_COLOR=1 python3 your_script.py -h

directly (no need to clear NO_COLOR).

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

4) Minimum CLI Surface (For Validation)

脚本必须包含：

至少一个
```
required=True
```
参数
至少一个可选参数
至少一个带
```
choices=
```
的参数
标准入口：
```
if __name__ == "__main__": main()
```

The script must include:

At least one parameter with
```
required=True
```
At least one optional parameter
At least one parameter with
```
choices=
```
Standard entry point:
```
if __name__ == "__main__": main()
```

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

5) Test Comments (Must Be Included in Code)

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

```
NO_COLOR=1 python your_script.py -h
```
```
FORCE_COLOR=1 python your_script.py -h
```

The script must include two comments to facilitate manual verification:

```
NO_COLOR=1 python your_script.py -h
```
```
FORCE_COLOR=1 python your_script.py -h
```

Recommended Implementation (Can Be Copied Directly)

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

```
./scripts/demo_pycli_color.py
```

You can directly refer to the template in the project (relative path):

```
./scripts/demo_pycli_color.py
```

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

"Copyable Prompt" for Future Assistants

当你以后要求我写任何 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 默认使用相对路径，并保证脚本可直接运行。 """

When you ask me to write any Python CLI script in the future, you can directly paste the following (no need to explain the background):

""" Please implement a CLI using argparse, and make the -h/--help help information of the Python script support consistent color highlighting (in accordance with your pycli-color specifications).

Must implement:

supports_color(): Default auto (enable only when sys.stdout.isatty()==True and TERM != 'dumb'); force disable color if NO_COLOR exists; force enable color if FORCE_COLOR=1 (even in non-TTY environments).
colorize(text, ansi_code): Wrap text with ANSI codes only when color is enabled, otherwise return the text as-is.
ColorHelpFormatter(argparse.HelpFormatter), and override HelpFormatter._format_action_invocation:
- Tokens starting with '-' (e.g., -h/--title) → cyan + bold (\x1b[36;1m)
- Tokens that are metavars (all uppercase or contain '_', e.g., TITLE/AJG_CSV) → yellow + bold (\x1b[33;1m)
- Do not color other tokens; append reset (\x1b[0m) after each colored segment
Enable the formatter via ArgumentParser(formatter_class=ColorHelpFormatter).
The CLI must include at least: 1 parameter with required=True, 1 optional parameter, 1 parameter with choices=, and include the standard entry point if name == 'main': main().
Must retain test comments in the code:
- NO_COLOR=1 python3 your_script.py -h
- FORCE_COLOR=1 python3 your_script.py -h Use relative paths by default and ensure the script can be run directly. """

pycli-color

Original

Translation

pycli-color

pycli-color

何时使用

When to Use

核心规范（必须满足）

Core Specifications (Mandatory)

1) 机制（必须使用 argparse）

1) Mechanism (Must use argparse)

2) 颜色规则（token 级别）

2) Color Rules (Token Level)

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

3) Color Enablement Strategy (Controllable and Compatible)

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

4) Minimum CLI Surface (For Validation)

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

5) Test Comments (Must Be Included in Code)

推荐实现（可直接复制）

Recommended Implementation (Can Be Copied Directly)

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

"Copyable Prompt" for Future Assistants