Python 教程 / 用 argparse 编写命令行工具

argparse 是 Python 定义命令行参数、转换规则、默认值和允许选项的标准模块,也能生成帮助与输入错误提示。把参数解析和实际计算分开,可以让命令行工具更容易测试和复用。

区分位置参数与具名选项

位置参数依照命令中的位置传入,--currency 这样的选项则用名字说明含义。nargs="+" 要求一个或多个值,type 指定转换函数,choices 限制允许的选项值。parse_args 返回的 Namespace 保存转换后的参数。

本例定义 nonnegative 转换函数,先尝试 int 转换,再拒绝负数。转换失败时抛出 ArgumentTypeError,由 argparse 生成适合命令行用户阅读的错误。详细接口见Python 官方 argparse 文档。

命令行参数可能出现在进程列表和终端历史中;加上 --password 这样的名字不会让内容变成秘密。令牌与密码应使用适合应用的独立安全输入或秘密管理机制。路径包含空格时,在所用 shell 中加引号,使其作为一个参数传入。

运行完整金额合计工具

建立独立练习目录,使用 Python 3.12 以上项目环境。把下面完整代码以 UTF-8 保存为 sum_cli.py,然后在该目录执行 python sum_cli.py 3500 8000 2500。若已确认解释器命令是 python3,则相应替换命令名。

import argparse

def nonnegative(text):
    try:
        value = int(text)
    except ValueError as error:
        raise argparse.ArgumentTypeError("expected an integer") from error
    if value < 0:
        raise argparse.ArgumentTypeError("expected a nonnegative amount")
    return value

def main():
    parser = argparse.ArgumentParser(description="Sum expense amounts")
    parser.add_argument("amounts", type=nonnegative, nargs="+")
    parser.add_argument("--currency", choices=["KRW", "USD"], default="KRW", help="Output unit label; no currency conversion")
    args = parser.parse_args()
    print(f"{sum(args.amounts):,} {args.currency}")

if __name__ == "__main__":
    main()

预期输出:

14,000 KRW

三个数转换后放在 args.amounts 列表中,sum 计算合计,格式中的逗号添加千位分隔符。末尾的 main 保护使导入模块时不自动读取命令行;函数的组织方式可参考函数定义与返回值。

--currency 只改变输出的单位标签,不做汇率换算。例如输入 14000 并选择 USD,输出是 14,000 USD,不是把 14,000 KRW 换算成美元。传入的数字本来就应使用所选择的同一种单位,不能混合货币后直接求和。

检查帮助、错误信息与退出码

在同一目录分别运行以下命令:

python sum_cli.py --help
python sum_cli.py 0 500 --currency KRW

第一条即使没有金额也会显示帮助并正常结束;查看 amounts、--currency、允许的 KRW 与 USD,以及不换算货币的说明。第二条应输出 500 KRW。帮助的换行、程序路径与颜色可能随 Python 版本和终端变化,检查意义即可,不要要求所有环境逐字符相同。

传给 sum_cli.py 的参数 预期行为 退出码
0 输出 0 KRW 0
-1 expected a nonnegative amount 2
abc expected an integer 2
不提供参数 提示缺少 amounts 2
500 --currency EUR 不在 choices 允许值中 2
--help 输出帮助 0

在 PowerShell 中,执行后立即查看 $LASTEXITCODE;macOS 或 Ubuntu 的常见 shell 可立即执行 echo $?。其他程序也可以使用子进程返回码区分成功和参数错误。本例普通 argparse 用法错误为 2,不应把这项规则推广为所有 Python 程序都必须使用相同错误码。

不要在检查状态之前再运行另一个外部命令,否则看到的可能是后一个命令的结果。错误通常写到标准错误流,正常合计写到标准输出;自动检查时应分别收集,并核对没有在失败时输出一个看似成功的合计。

保持清晰的输入契约再扩展

这个转换函数采用 int 接受的文字格式,并非严格的 ASCII 数字正则。因此 +5、某些空白包围的整数文字等也可能转换成功;若需求是特定文本格式,应另外制定并测试规则。不要从函数名推断它已经验证所有金额政策。

增加 init、add、list 等操作时,可用 subparsers 分开子命令,把计算函数需要的普通值传进去,避免业务函数依赖整个 argparse Namespace。这样网页入口和测试都能复用同一计算逻辑。

  1. 先验证正常三个金额和零值,再比较负数、缺失参数、错误通货与 --help。
  2. 分别核对输出流与退出码,确认错误不会产生有效合计。
  3. 恢复正常参数重新执行,保留可复现的示例。输入验证与文件保存应各有明确的失败结果。

可以沿用自动测试与边界检查中的方法,把用户关心的命令行为固定下来。扩展选项时仍需说明哪些参数可省略、如何解释输入,以及操作是否会修改文件。