Python argparse 实战:用子命令、互斥参数和类型校验写一个像样的 CLI写脚本时你多半这么读命令行参数:sys.argv[1]拿第一个,sys.argv[2]拿第二个。脚本小的时候没问题,一旦参数多起来、有可选项、有默认值,这套就崩了——参数顺序一错全乱,少传一个直接IndexError,想加个--help还得自己拼字符串。标准库的argparse就是干这个的。但很多人只会用它的皮毛(add_argument加几个位置参数),真正好用的子命令、互斥组、类型转换、自定义校验反而没碰过。这篇我们从一个实际需求出发,把它写成一个像样的命令行工具。需求:一个文件处理 CLI假设我们要做个工具filetool,支持两个子命令:filetool compress path --level 9—— 压缩文件filetool convert path --to png --quality 80—— 格式转换先看没有 argparse 会写成什么样:importsys# 朴素写法:脆弱、难维护cmdsys.argv[1]pathsys.argv[2]ifcmdcompress:levelint(sys.argv[3])iflen(sys.argv)3else6# ...参数一多,这里的sys.argv[3]会变成灾难:用户不按顺序传就错位,int()转换失败直接崩,没有任何友好提示。第一步:基础 parser 与类型校验importargparse parserargparse.ArgumentParser(progfiletool,description一个文件压缩与转换工具,)parser.add_argument(path,help要处理的文件路径,)parser.add_argument(--level,typeint,# argparse 自动转 int,转不了会报友好错误default6,choicesrange(1,10),# 限定 1-9,超范围自动拒绝help压缩级别 1-9(默认 6),)argsparser.parse_args()print(args.path,args.level)typeint让 argparse 自己做转换,用户传--level abc会得到error: argument --level: invalid int value: abc,而不是一个丑陋的 traceback。choices直接把合法值锁死,省了你手写if not 1 level 9。第二步:自定义校验——type 可以是任意函数type不只能填int、float,它接受任何「接收字符串、返回目标值」的可调用对象。想校验文件必须存在?写个函数塞进去:importargparsefrompathlibimportPathdefexisting_file(s:str)-Path:pPath(s)ifnotp.is_file():# 抛这个异常,argparse 会转成友好的命令行错误raiseargparse.ArgumentTypeError(f文件不存在:{s})returnp parserargparse.ArgumentParser(progfiletool)parser.add_argument(path,typeexisting_file,help要处理的文件)argsparser.parse_args()# args.path 此时已经是一个校验过的 Path 对象,不是 strprint(args.path.stat().st_size)关键点:校验失败要抛argparse.ArgumentTypeError,而不是ValueError或直接sys.exit。只有这个异常 argparse 才会包装成filetool: error: argument path: 文件不存在: xxx这种统一格式。返回值会直接成为args.path,类型都帮你转好了。第三步:互斥参数——两个开关不能同时出现比如转换时,--quiet(静默)和--verbose(啰嗦)逻辑上互斥,用户不该两个都传。用add_mutually_exclusive_group:groupparser.add_mutually_exclusive_group()group.add_argument(--quiet,actionstore_true,help静默模式)group.add_argument(--verbose,actionstore_true,help详细输出)用户同时传--quiet --verbose,argparse 直接报错:argument --verbose: not allowed with argument --quiet。这种约束靠自己写if很容易漏,交给互斥组一劳永逸。第四步:子命令——subparsers这是argparse最被低估的能力。git commit/git push这种「一个主命令带多个子命令、每个子命令有自己的参数」的结构,靠add_subparsers实现:importargparsefrompathlibimportPathdefexisting_file(s:str)-Path:pPath(s)ifnotp.is_file():raiseargparse.ArgumentTypeError(f文件不存在:{s})returnp parserargparse.ArgumentParser(progfiletool)# destcmd 让我们能从 args.cmd 读出用户选了哪个子命令subparsersparser.add_subparsers(destcmd,requiredTrue)# 子命令 1:compressp_compresssubparsers.add_parser(compress,help压缩文件)p_compress.add_argument(path,typeexisting_file)p_compress.add_argument(--level,typeint,default6,choicesrange(1,10))# 子命令 2:convertp_convertsubparsers.add_parser(convert,help格式转换)p_convert.add_argument(path,typeexisting_file)p_convert.add_argument(--to,requiredTrue,choices[png,jpg,webp])p_convert.add_argument(--quality,typeint,default80)argsparser.parse_args()requiredTrue保证用户必须选一个子命令,否则直接提示。注意每个子命令的参数是独立的:--level只属于compress,--to只属于convert,互不干扰。第五步:用 set_defaults 把子命令绑到处理函数拿到args.cmd后写一堆if args.cmd compress不够优雅。更干净的做法是给每个子命令绑一个处理函数:defdo_compress(args):print(f压缩{args.path},级别{args.level})defdo_convert(args):print(f把{args.path}转成{args.to},质量{args.quality})# 绑定:每个子命令关联一个 funcp_compress.set_defaults(funcdo_compress)p_convert.set_defaults(funcdo_convert)argsparser.parse_args()# 一行分发,不用 if-else 链args.func(args)set_defaults(func...)把处理函数塞进args,最后args.func(args)一行完成分发。加新子命令时只需add_parser 写个函数 set_defaults,主流程完全不用动——这就是可扩展的写法。完整可运行示例importargparsefrompathlibimportPathdefexisting_file(s:str)-Path:pPath(s)ifnotp.is_file():raiseargparse.ArgumentTypeError(f文件不存在:{s})returnpdefdo_compress(args):print(f压缩{args.path},级别{args.level})defdo_convert(args):mode静默ifargs.quietelse详细print(f把{args.path}转成{args.to},质量{args.quality},{mode}模式)defbuild_parser():parserargparse.ArgumentParser(progfiletool,description文件工具)subparser.add_subparsers(destcmd,requiredTrue)pcsub.add_parser(compress,help压缩文件)pc.add_argument(path,typeexisting_file)pc.add_argument(--level,typeint,default6,choicesrange(1,10))pc.set_defaults(funcdo_compress)pvsub.add_parser(convert,help格式转换)pv.add_argument(path,typeexisting_file)pv.add_argument(--to,requiredTrue,choices[png,jpg,webp])pv.add_argument(--quality,typeint,default80)gpv.add_mutually_exclusive_group()g.add_argument(--quiet,actionstore_true)g.add_argument(--verbose,actionstore_true)pv.set_defaults(funcdo_convert)returnparserif__name____main__:argsbuild_parser().parse_args()args.func(args)跑一下:$ python filetool.py convert ./a.png--towebp--quality90--verbose把 a.png 转成 webp,质量90,详细模式 $ python filetool.py--help# 自动生成的帮助$ python filetool.py convert--help# 子命令也有独立帮助小结别再手撸sys.argv[n],argparse 帮你搞定顺序、默认值、--help和错误提示。type接受任意「字符串进、目标值出」的函数,校验失败抛argparse.ArgumentTypeError才能得到友好错误。choices锁定合法值,add_mutually_exclusive_group声明互斥,把约束交给框架而不是手写 if。子命令用add_subparsers,每个子命令参数独立;set_defaults(func...)args.func(args)实现零 if-else 分发。一句话记忆:argparse 的正确用法不是「解析参数」,而是「声明式地描述你的命令行长什么样」,解析、校验、帮助、分发它全包了。
