DEBUG.WIKI
京东云;让 AI 进入真实业务;零售 · 物流 · 客服 · 硬件;查看方案 →
阿里云;从建站到云上业务;云服务器 · 数据库 · 对象存储;查看产品 →
雨云;给项目一台云服务器

argparse 帮助文本加颜色后提前换行,检查 ANSI 长度计算

Python 3.15 早期开发版的 argparse 可能把 ANSI 颜色码算进帮助文本长度。说明关闭自动颜色的局部处理与正式 3.15.0 的拆行修正。

终端宽度没有变化,argparse 帮助文本加上自动颜色后,(default: False) 却被提前拆到下一行。若纯文本版本的相同文字可以放下,应检查 ANSI 颜色转义序列是否被当作可见字符计入长度。

这个具体问题记录于 Python 3.15 开发过程中的 argparse 选项帮助排版。颜色码占用字符串长度,但通常不占对应的显示列,直接交给普通 textwrap.wrap() 会高估宽度。它不意味着所有中文、组合字符或 emoji 的宽度问题都来自同一个原因,也不应据此认定 Python 3.14 的所有彩色帮助都有此回归。

可以接受纯文本时,只关闭此解析器的自动颜色

Python 3.14 起,ArgumentParser 支持 color 参数。对受影响的解析器,保留原格式器和参数定义,只增加明确的关闭设置:

import argparse

parser = argparse.ArgumentParser(
    formatter_class=argparse.ArgumentDefaultsHelpFormatter,
    color=False,
)
parser.add_argument("--input", default="input.txt", help="Input file path")

示例只是解析器构造片段,已有子命令、参数和后续解析入口应在同一个解析器上保留。它关闭 argparse 自动生成的颜色,不会替你清理业务自己嵌入到 help 字符串里的 ANSI 序列。

不要靠把终端宽度调大来隐藏这个问题,同一个程序在较窄终端仍会重新错行。也不要把默认值手抄进每条帮助文本,再保留自动默认值格式器,否则可能重复或在参数修改后出现旧值。

正式 3.15.0 已按去色文本拆行

Python 3.15.0 的正式 _split_lines() 先去除颜色取得纯文本,按纯文本计算换行,再尽可能把颜色按词映射回去。遇到单词被拆开、无法可靠对应的情况,会保留纯文本行,避免为保颜色破坏拆行。3.15.2 的同一实现仍保留这条处理。

需要保留自动颜色时,应采用包含该处理且符合项目兼容要求的正式解释器。解释器切换涉及虚拟环境和扩展包,应保留锁文件与旧环境,不在原虚拟环境里只替换一个 Python 可执行文件。

这项修正集中在 argparse 选项帮助的拆行,不等于 textwrap 的通用显示宽度模型已经改变。应用自行排版的彩色日志、说明段落或第三方 CLI,仍须核对它们自己的格式化路径。

比较相同文字和相同宽度

验收固定帮助内容、格式器和终端宽度,再比较自动颜色开启与关闭两种输出,检查默认值、选项名和多行缩进。还应覆盖长词、空的插值值,以及输出重定向时是否仍含不需要的控制序列。

如果只有中文或组合字符的对齐仍不同,而自动颜色关闭后也一样,应另查终端字宽和格式器,不继续把所有间距问题归到 ANSI。保留原帮助文本和截图,避免为了通过一次比较删除有用的参数说明。