Python argparse.ArgumentParser.register 注册自定义 action 与 type

如果命令行参数的类型转换函数名字太长，或者自定义动作需要出现在稳定的错误提示里，可以使用 ArgumentParser.register() 给它登记一个短名称，再由 add_argument() 引用。它解决的是“解析器如何按名称找到可调用对象”的问题，不会替你完成业务校验。

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

register 的三个参数先对齐

注册调用的形状是 parser.register(registry_name, value, object)。例如 registry_name='type' 表示注册一个类型转换器，value='hexadecimal integer' 是参数声明中出现的名字，最后一个参数可以是函数、类或其他可调用对象。注册只作用于当前 ArgumentParser 实例，不会修改全局 argparse。

用可读名称注册十六进制 type

下面的示例把 0xFA 转成整数。重点不是十六进制本身，而是把转换器注册成名称后，参数定义不必直接暴露一个匿名 lambda。

import argparse

parser = argparse.ArgumentParser(prog="color-tool")

# 注册表放在当前 parser 中；名称会出现在后面的 type 参数里。
parser.register("type", "hexadecimal integer", lambda value: int(value, 16))

# 引用注册名，而不是把转换函数再写一遍。
parser.add_argument("--color", type="hexadecimal integer", required=True)

try:
    args = parser.parse_args(["--color", "0xFA"])
except SystemExit as exc:
    # argparse 默认会以 SystemExit 结束错误解析，调用方可统一接管退出码。
    raise RuntimeError("命令行参数解析失败") from exc
else:
    # 这里的值已经完成 type 转换，业务层拿到的是整数 250。
    print(args.color)

正常输入得到 250。若输入无法被 int(value, 16) 解析，错误仍然发生在参数转换阶段；注册机制不会把非法字符串变成合法业务值。生产代码中可以把 lambda 换成具名函数，并在函数内部抛出更明确的 ArgumentTypeError。

自定义 Action 要把消费规则写清楚

type 适合“一段输入转换成一个值”，而 action 适合决定值如何写入命名空间，例如把输入拆成键值对或追加到列表。自定义动作通常继承 argparse.Action，在 __call__ 中完成一次参数消费。

import argparse

class KeyValueAction(argparse.Action):
    def __init__(self, option_strings, dest, nargs=None, **kwargs):
        # 该动作只消费一个 key=value，避免 nargs 与实现语义冲突。
        if nargs is not None:
            raise ValueError("KeyValueAction 只接受一个值")
        super().__init__(option_strings, dest, **kwargs)

    def __call__(self, parser, namespace, values, option_string=None):
        # 把错误交给 argparse，调用方会得到带参数名的用法提示。
        if "=" not in values:
            raise argparse.ArgumentError(self, "值必须采用 key=value 格式")
        key, value = values.split("=", 1)
        current = getattr(namespace, self.dest, None) or {}
        current[key] = value
        setattr(namespace, self.dest, current)

parser = argparse.ArgumentParser(prog="config-tool")
parser.add_argument("--set", action=KeyValueAction, default={})
args = parser.parse_args(["--set", "mode=safe"])
print(args.set["mode"])

这里直接把 KeyValueAction 传给 action 已经足够。如果希望配置文件或团队约定统一使用字符串名称，可以使用 parser.register("action", "key-value", KeyValueAction)，再写 action="key-value"。两种方式的行为相同，差别只在参数声明是否通过注册名间接查找。

三个边界决定它是否适合生产

还要留意：注册名只在对应的注册表中解析，register("type", ...) 不能拿去填 action。自定义 Action 若不消费参数，必须显式设置合适的 nargs；若与位置参数、互斥组或子解析器组合，先用一个最小命令行样例确认解析行为。

常见问题

register 会影响其他 ArgumentParser 吗？

不会。注册表挂在当前解析器实例上；共享同一名称时，应在每个 parser 建立时完成注册，或直接传入可调用对象。

为什么自定义 type 还要做业务校验？

type 只负责把文本变成目标值，例如字符串到整数。范围、权限、文件是否存在等依赖业务上下文的判断，应在解析完成后处理。

自定义 Action 抛什么错误更合适？

参数格式错误可使用 ArgumentError，让 argparse 生成带用法的提示；不要在 Action 中静默吞掉异常，否则调用方难以判断参数是否生效。