Python argparse.ArgumentDefaultsHelpFormatter 怎样在帮助中显示默认值

我在给一个小型命令行工具补帮助信息时，最容易遗漏的是“参数不传时到底采用什么值”。如果只写 help="输入文件"，用户能知道参数做什么，却未必知道默认行为。Python argparse 的 ArgumentDefaultsHelpFormatter 可以让帮助条目自动追加默认值：把它传给 ArgumentParser(formatter_class=...)，再在 add_argument() 中明确写 default，调用 --help 时就会把默认值放到说明文本后面。

官方文档：https://docs.python.org/3/library/argparse.html

我会把这件事拆成“格式化器负责怎么显示、参数声明负责默认是什么”两层。这样既能得到更完整的帮助文本，也不会误以为 formatter 会替你解析输入或校验业务规则。

先给 ArgumentParser 配置默认值格式化器

formatter_class 是 ArgumentParser 的一个构造参数，用来选择帮助文本的格式化类。默认的 HelpFormatter 会处理换行和对齐，而 ArgumentDefaultsHelpFormatter 在此基础上会把默认值加入参数帮助条目。

import argparse

# 让每个参数的帮助条目自动带上 default 信息。
parser = argparse.ArgumentParser(
    prog="backup-tool",
    description="整理备份任务",
    formatter_class=argparse.ArgumentDefaultsHelpFormatter,
)

# default 是参数实际缺省值，help 是给使用者看的解释。
parser.add_argument("source", help="要整理的目录")
parser.add_argument("--keep", type=int, default=7, help="保留最近多少天")
parser.add_argument("--dry-run", action="store_true", help="只展示计划，不写入文件")

args = parser.parse_args()

这里的关键不是把类名写进 help，而是把类传入 formatter_class。source 没有声明 default，因为它是必填位置参数；--keep 的默认值是整数 7；--dry-run 的默认状态则由 store_true 体现为未出现时为假。

让 default 和 help 各自承担清楚的职责

default 是程序在参数缺席时得到的值，help 是帮助页面上的解释。格式化器只是读取参数动作中的元数据并拼出显示文本，不会替你推断“最近多少天”这样的业务语义。

因此我会把默认值写成读者一眼能理解的类型：整数写整数，字符串写字符串，列表或元组只在确实是默认集合时使用。不要为了让页面好看，把实际默认值复制到 help 里再另外维护一份；那样代码改成 14 后，帮助文本仍可能停留在“默认 7 天”。

如果要补充单位，可以在 help 里解释单位，但让 formatter 负责展示值。例如 default=7 配合 help="保留天数"，比写死成 help="保留天数，默认 7 天" 更不容易产生两份事实。

可选参数和位置参数的显示边界

ArgumentDefaultsHelpFormatter 会处理参数动作的默认值，既可以作用于选项，也可以作用于位置参数。位置参数通常是必填的，默认值往往没有实际意义；当位置参数使用 nargs="?" 或 nargs="*" 允许省略时，才需要认真考虑它的缺省行为。

图中的“参数定义”和“默认值元数据”应该分开理解：参数名、类型、choices、nargs 等决定输入形状，default 只是缺省值；它们最后共同进入帮助条目。格式化器不会把任意对象转换成更友好的业务名称。

三个容易误解的地方

第一，formatter 不负责输入校验。type=int、choices、required 和自定义校验仍由参数声明或解析后的业务代码负责。用户输入了不合法值时，问题发生在解析阶段，而不是“默认值显示”阶段。

第二，帮助文本中的默认值并不等于所有参数都会显示一个值。必填位置参数没有缺省值就不会凭空产生默认值；default=argparse.SUPPRESS 等特殊设计也可能让解析结果不创建对应属性。要不要向用户展示默认行为，取决于参数的真实语义。

第三，复杂对象的字符串表示可能不适合直接展示。如果默认值是列表、路径对象或自定义实例，formatter 依赖它的文本表示。此时更好的做法是让默认值可读，或者在 help 中补充业务解释，而不是把 formatter 改造成一套新的模板系统。

整理一个可复用的命令行入口

下面这个原创示例把默认值集中在参数定义处，再把业务逻辑放到解析之后。为了突出帮助设计，示例只展示入口组织方式，不执行真实备份，也不声称产生过实际运行日志。

import argparse

def build_parser():
    # 把帮助输出策略集中配置，业务函数不需要知道 formatter 的细节。
    parser = argparse.ArgumentParser(
        prog="backup-tool",
        description="生成备份整理计划",
        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
    )
    parser.add_argument("source", help="待整理的目录")
    parser.add_argument(
        "--keep",
        type=int,
        default=7,
        metavar="DAYS",
        help="保留最近多少天的文件",
    )
    parser.add_argument(
        "--format",
        choices=("zip", "tar"),
        default="zip",
        help="备份归档格式",
    )
    parser.add_argument(
        "--dry-run",
        action="store_true",
        help="只打印计划，不修改源目录",
    )
    return parser

def main(argv=None):
    parser = build_parser()
    args = parser.parse_args(argv)
    # 业务校验与帮助格式化分离，避免把显示逻辑散落到执行代码。
    if args.keep 

这段设计的好处是默认值只有一个来源：--keep 的真实默认值在 default=7，帮助说明只表达“它表示什么”。choices 负责限制归档格式，store_true 负责把开关映射成布尔值，而 formatter 只负责把这些信息组织成可读的帮助页面。

什么时候不该使用它

如果项目要求完全自定义帮助页面、隐藏所有默认值，或者需要根据运行环境动态生成复杂说明，就不必强行使用 ArgumentDefaultsHelpFormatter。可以继续使用普通 formatter，并在固定位置写有条件的说明。选择它的前提是：默认值本身对用户有帮助，并且它的文本表示稳定。

我的判断标准很简单：用户不传参数时会发生什么，能不能从帮助里直接看出来？如果能，自动追加默认值通常值得；如果默认值涉及密钥、内部路径、临时对象或敏感环境信息，就应该重新考虑是否展示。

为什么写了 default，帮助里仍然没有我想要的句子？

formatter 只会按自己的格式追加默认值，不会理解你的业务句式。把业务解释放进 help，把机器默认值放进 default，必要时再自定义 formatter。

store_true 需要手动写 default=False 吗？

通常不需要。这个 action 在开关未出现时为假、出现时为真；帮助文字应该说明开关出现后的效果。

default 可以和 choices 一起使用吗？

可以，但默认值应属于 choices 集合，否则帮助和解析行为会互相矛盾。

formatter 会改变 parse_args 的结果吗？

不会。它改变的是帮助文本格式；参数类型转换、默认值注入和业务校验仍由参数动作及后续代码负责。