2025-10-16 Python 标准库 13——argparse 模块-CSDN博客

文章目录

1. argparse 简介
2. 基础用法
3. 位置参数
4. 可选参数
5. 结合位置参数和可选参数
6. 处理歧义参数与矛盾选项
- 6.1. 解决参数歧义（-- 的使用）
- 6.2. 定义矛盾选项（互斥组）
7. 自定义类型转换器

argparse 是 Python 标准库中推荐的命令行解析模块，专为简化命令行程序的参数处理而设计。

参考文档：argparse 教程 — Python 3.13.9 文档

1. argparse 简介

argparse 是 Python 处理命令行参数的首选工具，相比标准库中的 optparse（需更多配置代码）和 getopt（C 风格低层级接口），它提供更简洁的 API 和自动生成的帮助文档，支持位置参数、可选参数、参数校验等核心功能，且兼容性更强。

通过 ls 命令的用法可直观理解 argparse 的核心概念：

$ ls
cpython  devguide  prog.py  pypy  rm-unused-function.patch
$ ls pypy
ctypes_configure  demo  dotviewer  include  lib_pypy  lib-python ...
$ ls -l
total 20
drwxr-xr-x 19 wena wena 4096 Feb 18 18:51 cpython
drwxr-xr-x  4 wena wena 4096 Feb  8 12:04 devguide
-rwxr-xr-x  1 wena wena  535 Feb 19 00:05 prog.py
drwxr-xr-x 14 wena wena 4096 Feb  7 00:59 pypy
-rw-r--r--  1 wena wena  741 Feb 18 01:01 rm-unused-function.patch
$ ls --help
Usage: ls [OPTION]... [FILE]...
List information about the FILEs (the current directory by default).
Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.
...

无参数运行：ls 未传入任何参数时，默认输出当前目录文件（程序需支持默认行为）；
位置参数：ls pypy 中的 pypy 是位置参数，程序根据参数位置判断用途（如 cp SRC DEST 中第一个参数为源文件，第二个为目标路径）；
可选参数：ls -l 中的 -l 是可选参数，用于修改程序行为（输出详细文件信息）；
帮助文档：ls --help 生成的用法说明，argparse 可自动为程序生成类似文档。

2. 基础用法

2.1. 最小示例：初始化解析器

import argparse
parser = argparse.ArgumentParser()
parser.parse_args()

无参数运行 python prog.py：无输出（程序未定义任何功能）；
查看帮助 python prog.py --help：自动生成用法说明（仅支持 -h/--help 选项）；
传入无效参数 python prog.py --verbose 或 python prog.py foo：报错并提示未识别参数。

以下是该代码的运行结果：

$ python prog.py
$ python prog.py --help
usage: prog.py [-h]

options:
  -h, --help  show this help message and exit
$ python prog.py --verbose
usage: prog.py [-h]
prog.py: error: unrecognized arguments: --verbose
$ python prog.py foo
usage: prog.py [-h]
prog.py: error: unrecognized arguments: foo

说明

argparse.ArgumentParser()：创建解析器实例，用于注册参数；
parser.parse_args()：解析命令行参数，返回包含参数值的命名空间（Namespace）；
自动支持 -h/--help：无需额外配置，默认生成帮助文档。

2.2. `ArgumentParser`

ArgumentParser 是 argparse 的核心类，用于存储参数规则并执行解析逻辑。其构造函数支持多个配置参数，用于定制解析器行为。

class argparse.ArgumentParser(
    prog=None,
    usage=None,
    description=None,
    epilog=None,
    parents=[],
    formatter_class=argparse.HelpFormatter,
    prefix_chars='-',
    fromfile_prefix_chars=None,
    argument_default=None,
    conflict_handler='error',
    add_help=True,
    allow_abbrev=True,
    exit_on_error=True
)

prog：程序名称

作用：指定帮助文档中显示的程序名称，默认值为 sys.argv[0] 的 basename；

>>> parser = argparse.ArgumentParser(prog='myprogram')
>>> parser.add_argument('--foo', help='foo of the %(prog)s program')
>>> parser.print_help()  # 帮助文档中显示 "usage: myprog [-h]"
usage: myprogram [-h] [--foo FOO]

options:
 -h, --help  show this help message and exit
 --foo FOO   foo of the myprogram program

技巧：可通过 %(prog)s 在帮助文本中引用程序名称。

usage：自定义用法格式

作用：覆盖默认生成的用法字符串（默认从参数列表自动生成）；

>>> parser = argparse.ArgumentParser(prog='PROG', usage='%(prog)s [options]')
>>> parser.add_argument('--foo', nargs='?', help='foo help')
>>> parser.add_argument('bar', nargs='+', help='bar help')
>>> parser.print_help()  # 用法显示为 "usage: PROG [options] <file>"
usage: PROG [options]

positional arguments:
 bar          bar help

options:
 -h, --help   show this help message and exit
 --foo [FOO]  foo help>>>

description 与 epilog：描述文本
- description：帮助文档中参数列表前显示的描述文本；
- epilog：帮助文档中参数列表后显示的补充文本；

parser = argparse.ArgumentParser(
description=‘A foo that bars’,
epilog=“And that’s how you’d foo a bar”)
parser.print_help() # 前后分别显示描述与补充文本
usage: argparse.py [-h]

A foo that bars

options:
-h, --help show this help message and exit

And that’s how you’d foo a bar


4. parents：继承父解析器参数

- 作用：复用其他 `ArgumentParser` 对象的参数（避免重复定义）；


- 注意：父解析器需设置 `add_help=False`，避免 `-h` 选项冲突；


5. formatter_class：自定义帮助文档格式

作用：指定帮助文档的格式化类，支持 4 种内置类：

1. `RawDescriptionHelpFormatter`：保留 `description` 和 `epilog` 的原始格式（不自动换行）；
2. `RawTextHelpFormatter`：保留所有帮助文本的空白符（多个换行合并为一个）；
3. `ArgumentDefaultsHelpFormatter`：自动显示参数默认值；
4. `MetavarTypeHelpFormatter`：用参数类型作为元变量显示；

```python
>>> parser = argparse.ArgumentParser(
    prog='PROG',
    formatter_class=argparse.ArgumentDefaultsHelpFormatter)
>>> parser.add_argument('--foo', type=int, default=42, help='FOO!')
>>> parser.add_argument('bar', nargs='*', default=[1, 2, 3], help='BAR!')
>>> parser.print_help()  # 帮助文本显示 "(default: 42)"
usage: PROG [-h] [--foo FOO] [bar ...]

positional arguments:
 bar         BAR! (default: [1, 2, 3])

options:
 -h, --help  show this help message and exit
 --foo FOO   FOO! (default: 42)

prefix_chars：自定义可选参数前缀

作用：指定可选参数的前缀字符（默认仅支持 -）；

>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='-+')
>>> parser.add_argument('+f')   # 支持 +f 选项
>>> parser.add_argument('++bar')
>>> parser.parse_args('+f X ++bar Y'.split())
Namespace(bar='Y', f='X')

fromfile_prefix_chars：从文件读取参数

作用：指定前缀字符，以该字符开头的参数会被视为文件路径，解析器会读取文件中的内容作为参数；

>>> # 创建参数文件 args.txt，内容为 "-f\nbar"
>>> with open('args.txt', 'w', encoding=sys.getfilesystemencoding()) as fp:
    	fp.write('-f\nbar')

>>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@')
>>> parser.add_argument('-f')
>>> parser.parse_args(['-f', 'foo', '@args.txt'])
Namespace(f='bar')

argument_default：全局参数默认值

作用：设置所有参数的全局默认值（优先级低于 add_argument() 的 default 参数）；

>>> parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS)
>>> parser.add_argument('--foo')
>>> parser.add_argument('bar', nargs='?')
>>> parser.parse_args(['--foo', '1', 'BAR'])
Namespace(bar='BAR', foo='1')
>>> parser.parse_args([])  # Namespace()，无 foo 属性
Namespace()

allow_abbrev：允许长选项缩写

作用：默认 True，允许无歧义的长选项缩写（如 --verbose 可缩写为 --verb）；

>>> parser = argparse.ArgumentParser(prog='PROG', allow_abbrev=False)
>>> parser.add_argument('--foobar', action='store_true')
>>> parser.add_argument('--foonley', action='store_false')
>>> parser.parse_args(['--foon'])  # 报错：未识别参数 --foon
usage: PROG [-h] [--foobar] [--foonley]
PROG: error: unrecognized arguments: --foon

conflict_handler：参数冲突处理

作用：处理重复参数的策略，默认 error（报错），可选 resolve（覆盖旧参数）；

>>> parser = argparse.ArgumentParser(prog='PROG', conflict_handler='resolve')
>>> parser.add_argument('-f', '--foo', help='old foo help')
>>> parser.add_argument('--foo', help='new foo help')  # 覆盖旧参数
usage: PROG [-h] [-f FOO] [--foo FOO]

options:
 -h, --help  show this help message and exit
 -f FOO      old foo help
 --foo FOO   new foo help

add_help：控制帮助选项

作用：默认 True，自动添加 -h/--help 选项；设为 False 可禁用；
exit_on_error：错误处理策略

作用：默认 True，解析错误时直接退出程序；设为 False 可捕获异常；

2.3. `parse_args()`

parse_args() 是执行参数解析的核心方法，将命令行参数字符串转换为 Namespace 对象。

ArgumentParser.parse_args(args=None, namespace=None)

args：待解析的参数字符串列表，默认从 sys.argv[1:] 获取；
namespace：存储解析结果的对象，默认创建新的 Namespace 对象。

2.3.1 选项值语法

argparse 支持多种选项值传入方式：

短选项：可拼接（如 -v -x 可简写为 -vx）；

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x', action='store_true')
>>> parser.add_argument('-y', action='store_true')
>>> parser.add_argument('-z')
>>> parser.parse_args(['-xyzZ'])
Namespace(x=True, y=True, z='Z')

长选项：支持 --foo=bar 或 --foo bar 格式；

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x')
>>> parser.add_argument('--foo')

>>> parser.parse_args(['-x', 'X'])
Namespace(foo=None, x='X')

>>> parser.parse_args(['--foo', 'FOO'])
Namespace(foo='FOO', x=None)

>>> parser.parse_args(['--foo=FOO'])
Namespace(foo='FOO', x=None)

2.3.2. 错误处理

解析时遇到以下情况会报错（默认退出程序，可通过 exit_on_error=False 捕获）：

无效参数类型（如 --foo abc 而 type=int）；
未识别的参数；

参数数量不匹配；

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo', type=int)
>>> parser.add_argument('bar', nargs='?')

>>> # invalid type
>>> parser.parse_args(['--foo', 'spam'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: argument --foo: invalid int value: 'spam'

>>> # invalid option
>>> parser.parse_args(['--bar'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: no such option: --bar

>>> # wrong number of arguments
>>> parser.parse_args(['spam', 'badger'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: extra arguments found: badger

2.3.3. 歧义参数处理

以 - 开头的位置参数（如 -1）可能被误判为选项，可通过 -- 分隔；

位置参数只有在它们看起来像负数并且解析器中没有任何选项看起来像负数时才能以 - 打头。

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x')
>>> parser.add_argument('foo', nargs='?')

>>> # 没有负数选项，因此 -1 是位置参数
>>> parser.parse_args(['-x', '-1'])
Namespace(foo=None, x='-1')

>>> # 没有负数选项，因此 -1 和 -5 是位置参数
>>> parser.parse_args(['-x', '-1', '-5'])
Namespace(foo='-5', x='-1')

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-1', dest='one')
>>> parser.add_argument('foo', nargs='?')

>>> # 有负数选项，因此 -1 是选项
>>> parser.parse_args(['-1', 'X'])
Namespace(foo=None, one='X')

>>> # 有负数选项，因此 -2 是选项
>>> parser.parse_args(['-2'])
usage: PROG [-h] [-1 ONE] [foo]
PROG: error: no such option: -2

>>> # 有负数选项，因此两个 -1 都是选项
>>> parser.parse_args(['-1', '-1'])
usage: PROG [-h] [-1 ONE] [foo]
PROG: error: argument -1: expected one argument

>>> parser.parse_args(['--', '-f'])
Namespace(foo='-f', one=None)

2.3.4. 参数缩写（前缀匹配）

默认允许无歧义的长选项缩写（如 --verbose 可缩写为 --verb），可通过 allow_abbrev=False 禁用；

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-bacon')
>>> parser.add_argument('-badger')
>>> parser.parse_args('-bac MMM'.split())
Namespace(bacon='MMM', badger=None)
>>> parser.parse_args('-bad WOOD'.split())
Namespace(bacon=None, badger='WOOD')
>>> parser.parse_args('-ba BA'.split())
usage: PROG [-h] [-bacon BACON] [-badger BADGER]
PROG: error: ambiguous option: -ba could match -badger, -bacon

3. 位置参数

3.1. 基础位置参数

位置参数是程序运行时必须传入的参数，按位置顺序解析：

import argparse
parser = argparse.ArgumentParser()
parser.add_argument("echo")  # 注册位置参数 "echo"
args = parser.parse_args()
print(args.echo)  # 访问参数值（属性名与参数名一致）

未传参数 python prog.py：报错提示“缺少必需参数 echo”；
传入参数 python prog.py foo：输出 foo；
查看帮助 python prog.py --help：显示位置参数 echo 的说明（无描述）。

3.2. 增强位置参数（添加说明与类型约束）

3.2.1. 添加帮助说明

import argparse
parser = argparse.ArgumentParser()

# 通过 help 参数添加描述
parser.add_argument("echo", help="echo the string you use here")
args = parser.parse_args()
print(args.echo)

运行 python prog.py --help 时，位置参数 echo 会显示帮助文本 echo the string you use here。

$ python prog.py -h
usage: prog.py [-h] echo

positional arguments:
  echo        echo the string you use here

options:
  -h, --help  show this help message and exit

3.2.2. 指定参数类型

argparse 默认将参数解析为字符串，可通过 type 参数指定类型（如 int、float）：

import argparse
parser = argparse.ArgumentParser()
# 指定参数为整数类型
parser.add_argument("square", help="display a square of a given number", type=int)
args = parser.parse_args()
print(args.square ** 2)  # 直接进行数值计算

传入整数 python prog.py 4：输出 16；
传入非整数 python prog.py four：报错提示“无效的 int 值”。

以下是该代码的运行结果：

$ python prog.py 4
16
$ python prog.py four
usage: prog.py [-h] square
prog.py: error: argument square: invalid int value: 'four'

4. 可选参数

4.1. 基础可选参数（带值选项）

可选参数通过 --参数名 定义，可选择是否传入，默认值为 None：

import argparse
parser = argparse.ArgumentParser()
# 注册可选参数 --verbosity
parser.add_argument("--verbosity", help="increase output verbosity")
args = parser.parse_args()
if args.verbosity:  # 若传入参数则执行
    print("verbosity turned on")

传入参数 python prog.py --verbosity 1：输出 verbosity turned on；
未传参数 python prog.py：无输出；
未传值 python prog.py --verbosity：报错提示“–verbosity 需传入一个参数”。

输出如下：

$ python prog.py --verbosity 1
verbosity turned on
$ python prog.py
$ python prog.py --help
usage: prog.py [-h] [--verbosity VERBOSITY]

options:
  -h, --help            show this help message and exit
  --verbosity VERBOSITY
                        increase output verbosity
$ python prog.py --verbosity
usage: prog.py [-h] [--verbosity VERBOSITY]
prog.py: error: argument --verbosity: expected one argument

4.2. 标志型可选参数（无值选项）

通过 action="store_true" 将可选参数设为“标志”（无需传值，传入则为 True，默认 False）：

import argparse
parser = argparse.ArgumentParser()
# action="store_true" 表示参数为标志，无需值
parser.add_argument("--verbose", help="increase output verbosity", action="store_true")
args = parser.parse_args()
if args.verbose:
    print("verbosity turned on")

传入参数 python prog.py --verbose：输出 verbosity turned on；
传入值 python prog.py --verbose 1：报错提示“未识别参数 1”；
查看帮助 python prog.py --help：参数说明中无“需要值”的提示。

输出如下：

$ python prog.py --verbose
verbosity turned on
$ python prog.py --verbose 1
usage: prog.py [-h] [--verbose]
prog.py: error: unrecognized arguments: 1
$ python prog.py --help
usage: prog.py [-h] [--verbose]

options:
  -h, --help  show this help message and exit
  --verbose   increase output verbosity

4.3. 短选项（缩写形式）

通过 "-短选项, --长选项" 为可选参数添加缩写（通常为单个字母），更符合命令行使用习惯：

import argparse
parser = argparse.ArgumentParser()
# 短选项 -v，长选项 --verbose
parser.add_argument("-v", "--verbose", help="increase output verbosity", action="store_true")
args = parser.parse_args()
if args.verbose:
    print("verbosity turned on")

传入短选项 python prog.py -v：输出 verbosity turned on；
查看帮助 python prog.py --help：同时显示 -v, --verbose。

输出如下：

$ python prog.py -v
verbosity turned on
$ python prog.py --help
usage: prog.py [-h] [-v]

options:
  -h, --help     show this help message and exit
  -v, --verbose  increase output verbosity

4.4. `add_argument()`

add_argument() 是 ArgumentParser 的核心方法，用于定义单个参数的解析规则，支持位置参数、可选参数等多种类型。

ArgumentParser.add_argument(
    name or flags...,
    action=None,
    nargs=None,
    const=None,
    default=None,
    type=None,
    choices=None,
    required=False,
    help=None,
    metavar=None,
    dest=None,
    deprecated=False
)

name or flags：参数名称或选项标志
- 作用：指定参数类型（位置参数或可选参数）；
- 位置参数：传入单个名称（如 'file'），必须在命令行中传入；
- 可选参数：传入选项标志列表（如 '-f', '--file'），可选择传入；

action：参数动作类型

作用：指定解析参数时的行为，支持多种内置动作：

store（默认）：存储参数值

>>> parser.add_argument('--foo')
>>> args = parser.parse_args(['--foo', 'bar'])
Namespace(foo='bar')

store_const：存储常量值

需配合 const 参数指定常量值，无需从命令行传入值；

>>> parser.add_argument('--foo', action='store_const', const=42)
>>> args = parser.parse_args(['--foo'])
Namespace(foo=42)

store_true /store_false：存储布尔值

store_true：传入选项则为 True，默认 False；

store_false：传入选项则为 False，默认 True；

>>> parser.add_argument('--enable', action='store_true')
>>> parser.add_argument('--disable', action='store_false')
>>> args = parser.parse_args(['--enable', '--disable'])
Namespace(enable=True, disable=False)

append：收集多个值到列表

支持同一选项多次传入，值以列表形式存储；

>>> parser.add_argument('--foo', action='append')
>>> args = parser.parse_args(['--foo', 'a', '--foo', 'b'])
Namespace(foo=['a', 'b'])

append_const：收集常量到列表

需配合 const 参数，多个选项可共享同一列表；

>>> parser.add_argument('--str', dest='types', action='append_const', const=str)
>>> parser.add_argument('--int', dest='types', action='append_const', const=int)
>>> args = parser.parse_args(['--str', '--int'])
Namespace(types=[str, int])

extend：扩展列表（3.8+）

接收多个值并扩展到列表，常配合 nargs='+' 使用；

>>> parser.add_argument('--foo', action='extend', nargs='+', type=str)
>>> args = parser.parse_args(['--foo', 'a', 'b', '--foo', 'c'])
Namespace(foo=['a', 'b', 'c'])

count：统计选项出现次数

常用于控制冗余度（如 -v 次数越多输出越详细）；

>>> parser.add_argument('-v', '--verbose', action='count', default=0)
>>> args = parser.parse_args(['-vvv'])
Namespace(verbose=3)

help：显示帮助文档并退出

覆盖默认的 -h/--help 行为（较少使用）；
version：显示版本信息并退出

需配合 version 参数指定版本文本；

>>> parser.add_argument('--version', action='version', version='%(prog)s 1.0')
>>> parser.parse_args(['--version'])
prog 1.0

自定义动作

继承 argparse.Action 类，重写 __call__ 方法；

>>> class UpperAction(argparse.Action):
        def __call__(self, parser, namespace, values, option_string=None):
            setattr(namespace, self.dest, values.upper())

>>> parser.add_argument('--foo', action=UpperAction)
>>> args = parser.parse_args(['--foo', 'bar'])
Namespace(foo='BAR')

nargs：参数接收数量

作用：指定参数可接收的命令行参数个数，支持多种值：

N（整数）：固定接收 N 个值

>>> parser.add_argument('--foo', nargs=2)
>>> args = parser.parse_args(['--foo', 'a', 'b'])
Namespace(foo=['a', 'b'])

‘?’：可选接收 0 或 1 个值

位置参数：未传入时使用 default 值；

可选参数：未传入值时使用 const 值；

>>> parser.add_argument('--foo', nargs='?', const='c', default='d')
>>> parser.add_argument('bar', nargs='?', default='d')
>>> args = parser.parse_args(['--foo'])
Namespace(bar='d', foo='c')

‘*’：接收任意个值（包括 0 个）

>>> parser.add_argument('--foo', nargs='*')
>>> args = parser.parse_args(['--foo', 'a', 'b', 'c'])
Namespace(foo=['a', 'b', 'c'])

‘+’：接收至少 1 个值

>>> parser.add_argument('foo', nargs='+')
>>> args = parser.parse_args([])  # 报错：缺少必需参数 foo

const：常量值

作用：配合 action='store_const'/'append_const' 或 nargs='?' 时使用，指定固定常量值；

>>> parser.add_argument('--foo', nargs='?', const='hello')
>>> args = parser.parse_args(['--foo'])
Namespace(foo='hello')

default：默认值
- 作用：指定参数未在命令行传入时的默认值；
- 注意：若 default 为字符串，会应用 type 参数的转换规则；
```
>>> parser.add_argument('--foo', type=int, default=42)
>>> args = parser.parse_args([])
Namespace(foo=42)
```

type：参数类型转换

作用：指定参数值的转换函数（如 int、float 或自定义函数）；

支持类型：
- 内置类型：int、float、str、pathlib.Path 等；
- 文件类型：argparse.FileType('r')（自动打开文件）；
- 自定义函数：需接收字符串参数，返回转换后的值；

>>> def even_number(s):
        num = int(s)
        if num % 2 != 0:
            raise argparse.ArgumentTypeError(f'{s} 不是偶数')
        return num

>>> parser.add_argument('--foo', type=even_number)
>>> args = parser.parse_args(['--foo', '4'])
Namespace(foo=4)

choices：参数值范围限制

作用：指定参数的允许值列表，超出范围则报错；

>>> parser.add_argument('--mode', choices=['train', 'test', 'eval'])
>>> args = parser.parse_args(['--mode', 'train'])  # 合法
>>> args = parser.parse_args(['--mode', 'predict'])  # 报错：无效选择

required：可选参数是否必需

作用：默认 False，设为 True 时可选参数变为必需传入；

>>> parser.add_argument('--foo', required=True)
>>> args = parser.parse_args([])  # 报错：缺少必需参数 --foo

help：参数帮助文本

作用：指定参数的帮助描述，支持 %(prog)s、%(default)s 等格式化占位符；

>>> parser.add_argument('--foo', type=int, default=42, help='整数参数（默认：%(default)s）')
>>> parser.print_help()  # 显示帮助文本：--foo FOO  整数参数（默认：42）

metavar：帮助文本中的参数占位符

作用：自定义帮助文本中显示的参数名称（不影响实际解析）；
```
>>> parser.add_argument('--foo', metavar='VALUE')
>>> parser.print_help()  # 帮助文本显示：--foo VALUE
```

dest：解析后的属性名

作用：指定参数解析后在 Namespace 对象中的属性名（默认从参数名推导）；

>>> parser.add_argument ('--foo-bar', dest='foobar')
>>> args = parser.parse_args (['--foo-bar', '42'])
Namespace (foobar='42')

deprecated：标记参数已弃用（3.13+）

作用：设为 True 时，传入该参数会打印警告信息；

>>> parser.add_argument('--old-opt', deprecated=True)
>>> args = parser.parse_args(['--old-opt', 'value'])  # 打印警告：--old-opt 已弃用

5. 结合位置参数和可选参数

5.1. 基础结合示例

import argparse
parser = argparse.ArgumentParser()
# 位置参数（必需）
parser.add_argument("square", type=int, help="display a square of a given number")
# 可选参数（标志型）
parser.add_argument("-v", "--verbose", action="store_true", help="increase output verbosity")
args = parser.parse_args()
answer = args.square ** 2
if args.verbose:
    print(f"the square of {args.square} equals {answer}")
else:
    print(answer)

传入位置参数 python prog.py 4：输出 16；
同时传入位置参数与可选参数 python prog.py 4 --verbose 或 python prog.py --verbose 4：输出 the square of 4 equals 16；
未传位置参数 python prog.py：报错提示“缺少必需参数 square”。

接着是输出：

$ python prog.py
usage: prog.py [-h] [-v] square
prog.py: error: the following arguments are required: square
$ python prog.py 4
16
$ python prog.py 4 --verbose
the square of 4 equals 16
$ python prog.py --verbose 4
the square of 4 equals 16

5.2. 多级别冗余度（带值可选参数进阶）

通过 type=int 和 choices 限制可选参数的取值范围，实现多级别输出控制：

import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", type=int, help="display a square of a given number")
# 可选参数为整数，仅允许 0、1、2 三个值
parser.add_argument("-v", "--verbosity", type=int, choices=[0, 1, 2], help="increase output verbosity")
args = parser.parse_args()
answer = args.square ** 2
if args.verbosity == 2:
    print(f"the square of {args.square} equals {answer}")
elif args.verbosity == 1:
    print(f"{args.square}^2 == {answer}")
else:
    print(answer)

传入 -v 1：python prog.py 4 -v 1 → 输出 4^2 == 16；
传入 -v 3：报错提示“无效选择 3（可选值：0、1、2）”。

和输出：

$ python prog.py 4
16
$ python prog.py 4 -v
usage: prog.py [-h] [-v VERBOSITY] square
prog.py: error: argument -v/--verbosity: expected one argument
$ python prog.py 4 -v 1
4^2 == 16
$ python prog.py 4 -v 2
the square of 4 equals 16
$ python prog.py 4 -v 3
16

5.3. 计数型可选参数（累计选项次数）

通过 action="count" 统计可选参数的出现次数，实现动态冗余度控制（类似 python -vvv 的用法）：

import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", type=int, help="display a square of a given number")
# action="count" 统计参数出现次数，默认 None
parser.add_argument("-v", "--verbosity", action="count", default=0, help="increase output verbosity")
args = parser.parse_args()
answer = args.square ** 2
if args.verbosity >= 2:
    print(f"the square of {args.square} equals {answer}")
elif args.verbosity >= 1:
    print(f"{args.square}^2 == {answer}")
else:
    print(answer)

无 -v：python prog.py 4 → 输出 16；
1 个 -v：python prog.py 4 -v → 输出 4^2 == 16；
2 个 -v：python prog.py 4 -vv 或 python prog.py 4 --verbosity --verbosity → 输出 the square of 4 equals 16；
3 个 -v：python prog.py 4 -vvv → 输出 the square of 4 equals 16（因判断条件为 >=2）。

和输出：

$ python prog.py 4 -v 3
usage: prog.py [-h] [-v {0,1,2}] square
prog.py: error: argument -v/--verbosity: invalid choice: 3 (choose from 0, 1, 2)
$ python prog.py 4 -h
usage: prog.py [-h] [-v {0,1,2}] square

positional arguments:
  square                display a square of a given number

options:
  -h, --help            show this help message and exit
  -v, --verbosity {0,1,2}
                        increase output verbosity

6. 处理歧义参数与矛盾选项

6.1. 解决参数歧义（-- 的使用）

当参数以 - 开头且需被视为位置参数时，用 -- 分隔，告知解析器后续参数为位置参数：

>>> import argparse
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-n', nargs='+')  # 可选参数，接收多个值
>>> parser.add_argument('args', nargs='*')  # 位置参数，接收任意个值

>>> # 示例 1：解析 -f（默认视为可选参数，报错）
>>> parser.parse_args(['-f'])
usage: PROG [-h] [-n N [N ...]] [args ...]
PROG: error: unrecognized arguments: -f

>>> # 示例 2：用 -- 标记 -f 为位置参数
>>> args = parser.parse_args(['--', '-f'])
Namespace(args=['-f'], n=None)

>>> # 示例 3：-n 贪婪匹配参数
>>> args = parser.parse_args(['-n', '1', '2', '3'])
Namespace(args=[], n=['1', '2', '3'])

>>> # 示例 4：-- 分隔后，-n 仅匹配前面的参数
>>> args = parser.parse_args(['-n', '1', '--', '2', '3'])
Namespace(args=['2', '3'], n=['1'])

说明：

nargs='+'：要求参数至少接收一个值；
nargs='*'：参数可接收任意个值（包括 0 个）；
-- 用于明确区分可选参数和位置参数，避免解析歧义。

6.2. 定义矛盾选项（互斥组）

通过 add_mutually_exclusive_group() 创建互斥参数组，确保组内参数不可同时使用：

import argparse
parser = argparse.ArgumentParser(description="calculate X to the power of Y")

# 创建互斥组
group = parser.add_mutually_exclusive_group()
group.add_argument("-v", "--verbose", action="store_true", help="output detailed info")
group.add_argument("-q", "--quiet", action="store_true", help="output only result")

# 位置参数
parser.add_argument("x", type=int, help="the base")
parser.add_argument("y", type=int, help="the exponent")
args = parser.parse_args()
answer = args.x ** args.y

if args.quiet:
    print(answer)
elif args.verbose:
    print(f"{args.x} to the power {args.y} equals {answer}")
else:
    print(f"{args.x}^{args.y} == {answer}")

正常运行 python prog.py 5 2 → 输出 5^2 == 25；
传入 -q：python prog.py 5 2 -q → 输出 25；
传入 -v：python prog.py 5 2 -v → 输出 5 to the power 2 equals 25；
同时传入 -v 和 -q：python prog.py 5 2 -vq → 报错提示“-q 不允许与 -v 同时使用”；
查看帮助 python prog.py --help：显示 [-v | -q]（表示二选一）。

输出如下：

$ python prog.py 4 2
4^2 == 16
$ python prog.py 4 2 -q
16
$ python prog.py 4 2 -v
4 to the power 2 equals 16
$ python prog.py 4 2 -vq
usage: prog.py [-h] [-v | -q] x y
prog.py: error: argument -q/--quiet: not allowed with argument -v/--verbose
$ python prog.py 4 2 -v --quiet
usage: prog.py [-h] [-v | -q] x y
prog.py: error: argument -q/--quiet: not allowed with argument -v/--verbose

7. 自定义类型转换器

argparse 允许通过 type 参数指定自定义函数，对输入参数进行预处理后再存储。

使用自定义类型转换器时，您可以使用任何可调用对象，该对象接受单个字符串参数（参数值）并返回转换后的值。但是，如果需要处理更复杂的情况，可以使用带有 action 形参的自定义动作类：

import argparse

def process_prefix(value):
    """自定义转换器：区分参数前缀并返回元组"""
    if value.startswith('-'):
        return ('negative', value.lstrip('-'))
    elif value.startswith('+'):
        return ('positive', value.lstrip('+'))
    else:
        return ('neutral', value)

# 创建支持 - 和 + 作为前缀的解析器
parser = argparse.ArgumentParser(prefix_chars='-+')
parser.add_argument('-a', metavar='<value>', action='append', type=process_prefix)
parser.add_argument('+a', metavar='<value>', action='append', type=process_prefix)

args = parser.parse_args()
print("处理后的参数：", args.a)

输入 python prog.py -a -123 +a +456 -a 789 → 输出 处理后的参数：[('negative', '123'), ('positive', '456'), ('neutral', '789')]；
关键说明：action='append' 表示参数可多次传入，值以列表形式存储。