`argparse` — 命令行选项、参数和子命令的解析器¶

3.2 版新增。

argparse 模块可以轻松编写用户友好的命令行界面。程序定义它需要的参数，argparse 将找出如何从 sys.argv 中解析这些参数。argparse 模块还会自动生成帮助和使用信息。当用户向程序提供无效参数时，该模块还会发出错误。

核心功能¶

argparse 模块对命令行接口的支持是围绕 argparse.ArgumentParser 的实例构建的。它是一个参数规范的容器，并具有应用于整个解析器的选项。

parser = argparse.ArgumentParser(
                    prog='ProgramName',
                    description='What the program does',
                    epilog='Text at the bottom of help')

ArgumentParser.add_argument() 方法将各个参数规范附加到解析器。它支持位置参数、接受值的选项和开/关标志。

parser.add_argument('filename')           # positional argument
parser.add_argument('-c', '--count')      # option that takes a value
parser.add_argument('-v', '--verbose',
                    action='store_true')  # on/off flag

ArgumentParser.parse_args() 方法运行解析器并将提取的数据放入 argparse.Namespace 对象中。

args = parser.parse_args()
print(args.filename, args.count, args.verbose)

add_argument() 快速链接¶

名称	描述	值
action	指定如何处理参数	`'store'`、`'store_const'`、`'store_true'`、`'append'`、`'append_const'`、`'count'`、`'help'`、`'version'`
choices	将值限制为一组特定的选项	`['foo', 'bar']`、`range(1, 10)` 或 `Container` 实例
const	存储常量值
default	未提供参数时使用的默认值	默认为 `None`
dest	指定结果命名空间中使用的属性名称
help	参数的帮助信息
metavar	参数的备用显示名称，如帮助中所示
nargs	参数可使用的次数	`int`、`'?'`、`'*'` 或 `'+'`
required	指示参数是必需的还是可选的	`True` 或 `False`
type	自动将参数转换为给定类型	`int`、`float`、`argparse.FileType('w')` 或可调用函数

示例¶

以下代码是一个 Python 程序，它接受一个整数列表并生成总和或最大值。

import argparse

parser = argparse.ArgumentParser(description='Process some integers.')
parser.add_argument('integers', metavar='N', type=int, nargs='+',
                    help='an integer for the accumulator')
parser.add_argument('--sum', dest='accumulate', action='store_const',
                    const=sum, default=max,
                    help='sum the integers (default: find the max)')

args = parser.parse_args()
print(args.accumulate(args.integers))

假设上面的 Python 代码保存到名为 prog.py 的文件中，则可以在命令行运行它，它会提供有用的帮助信息。

$ python prog.py -h
usage: prog.py [-h] [--sum] N [N ...]

Process some integers.

positional arguments:
 N           an integer for the accumulator

options:
 -h, --help  show this help message and exit
 --sum       sum the integers (default: find the max)

当使用适当的参数运行时，它会打印命令行整数的总和或最大值。

$ python prog.py 1 2 3 4
4

$ python prog.py 1 2 3 4 --sum
10

如果传入无效参数，则会显示错误。

$ python prog.py a b c
usage: prog.py [-h] [--sum] N [N ...]
prog.py: error: argument N: invalid int value: 'a'

以下部分将逐步介绍此示例。

创建解析器¶

使用 argparse 的第一步是创建一个 ArgumentParser 对象。

>>> parser = argparse.ArgumentParser(description='Process some integers.')

ArgumentParser 对象将保存将命令行解析为 Python 数据类型所需的所有信息。

添加参数¶

通过调用 ArgumentParser 的 add_argument() 方法，可以用程序参数的信息填充 ArgumentParser。通常，这些调用会告诉 ArgumentParser 如何获取命令行上的字符串并将其转换为对象。这些信息会被存储起来，并在调用 parse_args() 时使用。例如

>>> parser.add_argument('integers', metavar='N', type=int, nargs='+',
...                     help='an integer for the accumulator')
>>> parser.add_argument('--sum', dest='accumulate', action='store_const',
...                     const=sum, default=max,
...                     help='sum the integers (default: find the max)')

稍后，调用 parse_args() 将返回一个具有两个属性的对象：integers 和 accumulate。integers 属性将是一个包含一个或多个整数的列表，而 accumulate 属性将是 sum() 函数（如果在命令行中指定了 --sum）或 max() 函数（如果没有指定）。

解析参数¶

ArgumentParser 通过 parse_args() 方法解析参数。这将检查命令行，将每个参数转换为适当的类型，然后调用相应的操作。在大多数情况下，这意味着将从命令行解析出的属性构建一个简单的 Namespace 对象

>>> parser.parse_args(['--sum', '7', '-1', '42'])
Namespace(accumulate=<built-in function sum>, integers=[7, -1, 42])

在脚本中，通常会在不带参数的情况下调用 parse_args()，并且 ArgumentParser 将自动从 sys.argv 中确定命令行参数。

ArgumentParser 对象¶

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)¶

创建一个新的 ArgumentParser 对象。所有参数都应作为关键字参数传递。每个参数在下面都有更详细的描述，但简而言之，它们是

prog - 程序的名称（默认值：os.path.basename(sys.argv[0])）
usage - 描述程序用法的字符串（默认值：从添加到解析器的参数生成）
description - 在参数帮助之前显示的文本（默认情况下不显示文本）
epilog - 在参数帮助之后显示的文本（默认情况下不显示文本）
parents - ArgumentParser 对象的列表，其参数也应包括在内
formatter_class - 用于自定义帮助输出的类
prefix_chars - 可选参数前缀的字符集（默认值：'-'）
fromfile_prefix-chars - 用于从中读取其他参数的文件的前缀字符集（默认值：None）
argument_default - 参数的全局默认值（默认值：None）
conflict_handler - 解决冲突选项的策略（通常不需要）
add_help - 向解析器添加 -h/--help 选项（默认值：True）
allow_abbrev - 如果缩写没有歧义，则允许缩写长选项。（默认值：True）
exit_on_error - 确定 ArgumentParser 在发生错误时是否退出并显示错误信息。（默认值：True）

版本 3.5 中的变化：添加了 allow_abbrev 参数。

版本 3.8 中的变化：在以前的版本中，allow_abbrev 还禁用了短标志的组合，例如 -vv 表示 -v -v。

版本 3.9 中的变化：添加了 exit_on_error 参数。

以下部分描述了如何使用每个参数。

prog¶

默认情况下，ArgumentParser 对象使用 sys.argv[0] 来确定如何在帮助消息中显示程序的名称。此默认值几乎总是可取的，因为它将使帮助消息与程序在命令行上的调用方式相匹配。例如，考虑一个名为 myprogram.py 的文件，其中包含以下代码

import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--foo', help='foo help')
args = parser.parse_args()

此程序的帮助将显示 myprogram.py 作为程序名称（无论程序是从哪里调用的）

$ python myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]

options:
 -h, --help  show this help message and exit
 --foo FOO   foo help
$ cd ..
$ python subdir/myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]

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

要更改此默认行为，可以使用传递给 ArgumentParser 的 prog= 参数来提供另一个值。

>>> parser = argparse.ArgumentParser(prog='myprogram')
>>> parser.print_help()
usage: myprogram [-h]

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

请注意，程序名称（无论是从 sys.argv[0] 确定还是从 prog= 参数确定）都可用于帮助消息，使用 %(prog)s 格式说明符。

>>> parser = argparse.ArgumentParser(prog='myprogram')
>>> parser.add_argument('--foo', help='foo of the %(prog)s program')
>>> parser.print_help()
usage: myprogram [-h] [--foo FOO]

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

用法¶

默认情况下，ArgumentParser 根据它包含的参数计算使用消息。

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo', nargs='?', help='foo help')
>>> parser.add_argument('bar', nargs='+', help='bar help')
>>> parser.print_help()
usage: PROG [-h] [--foo [FOO]] bar [bar ...]

positional arguments:
 bar          bar help

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

可以使用 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]

positional arguments:
 bar          bar help

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

%(prog)s 格式说明符可用于在使用消息中填写程序名称。

描述¶

大多数对 ArgumentParser 构造函数的调用将使用 description= 关键字参数。此参数简要描述了程序的功能及其工作原理。在帮助消息中，描述显示在命令行使用字符串和各种参数的帮助消息之间。

>>> parser = argparse.ArgumentParser(description='A foo that bars')
>>> parser.print_help()
usage: argparse.py [-h]

A foo that bars

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

默认情况下，描述将进行自动换行，以使其适合给定的空间。要更改此行为，请参阅 formatter_class 参数。

结语¶

某些程序喜欢在参数描述之后显示程序的附加描述。可以使用传递给 ArgumentParser 的 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

与 description 参数一样，epilog= 文本默认情况下会自动换行，但可以使用传递给 ArgumentParser 的 formatter_class 参数来调整此行为。

父级¶

有时，多个解析器共享一组通用的参数。可以将包含所有共享参数的单个解析器传递给 ArgumentParser 的 parents= 参数，而不是重复定义这些参数。 parents= 参数接受一个 ArgumentParser 对象列表，从中收集所有位置和可选操作，并将这些操作添加到正在构造的 ArgumentParser 对象。

>>> parent_parser = argparse.ArgumentParser(add_help=False)
>>> parent_parser.add_argument('--parent', type=int)

>>> foo_parser = argparse.ArgumentParser(parents=[parent_parser])
>>> foo_parser.add_argument('foo')
>>> foo_parser.parse_args(['--parent', '2', 'XXX'])
Namespace(foo='XXX', parent=2)

>>> bar_parser = argparse.ArgumentParser(parents=[parent_parser])
>>> bar_parser.add_argument('--bar')
>>> bar_parser.parse_args(['--bar', 'YYY'])
Namespace(bar='YYY', parent=None)

请注意，大多数父解析器将指定 add_help=False。否则，ArgumentParser 将看到两个 -h/--help 选项（一个在父级中，一个在子级中），并引发错误。

注意

您必须先完全初始化解析器，然后才能通过 parents= 传递它们。如果您在子解析器之后更改父解析器，则这些更改将不会反映在子解析器中。

formatter_class¶

ArgumentParser 对象允许通过指定备用格式化类来自定义帮助格式。当前，有四个这样的类。

class argparse.RawDescriptionHelpFormatter¶
class argparse.RawTextHelpFormatter¶
class argparse.ArgumentDefaultsHelpFormatter¶
class argparse.MetavarTypeHelpFormatter¶

RawDescriptionHelpFormatter 和 RawTextHelpFormatter 提供了对如何显示文本描述的更多控制。默认情况下，ArgumentParser 对象会在命令行帮助消息中对 description 和 epilog 文本进行自动换行。

>>> parser = argparse.ArgumentParser(
...     prog='PROG',
...     description='''this description
...         was indented weird
...             but that is okay''',
...     epilog='''
...             likewise for this epilog whose whitespace will
...         be cleaned up and whose words will be wrapped
...         across a couple lines''')
>>> parser.print_help()
usage: PROG [-h]

this description was indented weird but that is okay

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

likewise for this epilog whose whitespace will be cleaned up and whose words
will be wrapped across a couple lines

传递 RawDescriptionHelpFormatter 作为 formatter_class= 表示 description 和 epilog 已格式正确，不应自动换行。

>>> parser = argparse.ArgumentParser(
...     prog='PROG',
...     formatter_class=argparse.RawDescriptionHelpFormatter,
...     description=textwrap.dedent('''\
...         Please do not mess up this text!
...         --------------------------------
...             I have indented it
...             exactly the way
...             I want it
...         '''))
>>> parser.print_help()
usage: PROG [-h]

Please do not mess up this text!
--------------------------------
   I have indented it
   exactly the way
   I want it

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

RawTextHelpFormatter 保留所有类型帮助文本的空格，包括参数描述。但是，多个换行符将替换为一个。如果您希望保留多个空行，请在新行之间添加空格。

ArgumentDefaultsHelpFormatter 会自动将有关默认值的信息添加到每个参数帮助消息中。

>>> 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()
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)

MetavarTypeHelpFormatter 使用每个参数的 type 参数的名称作为其值的显示名称（而不是像常规格式化程序那样使用 dest）。

>>> parser = argparse.ArgumentParser(
...     prog='PROG',
...     formatter_class=argparse.MetavarTypeHelpFormatter)
>>> parser.add_argument('--foo', type=int)
>>> parser.add_argument('bar', type=float)
>>> parser.print_help()
usage: PROG [-h] [--foo int] float

positional arguments:
  float

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

prefix_chars¶

大多数命令行选项将使用 - 作为前缀，例如 -f/--foo。需要支持不同或其他前缀字符的解析器（例如，对于 +f 或 /foo 等选项）可以使用传递给 ArgumentParser 构造函数的 prefix_chars= 参数来指定它们。

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

prefix_chars= 参数默认为 '-'。提供一组不包含 - 的字符将导致 -f/--foo 选项被禁止。

fromfile_prefix_chars¶

有时，在处理特别长的参数列表时，将参数列表保存在文件中，而不是在命令行中键入，可能更有意义。如果将 fromfile_prefix_chars= 参数提供给 ArgumentParser 构造函数，则以任何指定字符开头的参数将被视为文件，并将被它们包含的参数替换。例如

>>> 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')

默认情况下，从文件读取的参数必须每行一个（但也请参阅 convert_arg_line_to_args()），并且它们的处理方式就像它们与命令行上引用原始文件的参数位于同一位置一样。因此，在上面的示例中，表达式 ['-f', 'foo', '@args.txt'] 被视为等同于表达式 ['-f', 'foo', '-f', 'bar']。

ArgumentParser 使用文件系统编码和错误处理程序读取包含参数的文件。

fromfile_prefix_chars= 参数默认为 None，这意味着参数永远不会被视为文件引用。

在 3.12 版更改: ArgumentParser 将读取参数文件的编码和错误处理方式从默认值（例如 locale.getpreferredencoding(False) 和 "strict"）更改为文件系统编码和错误处理程序。参数文件应使用 UTF-8 编码，而不是 Windows 上的 ANSI 代码页。

argument_default¶

通常，参数默认值通过将默认值传递给 add_argument() 或使用一组特定的名称-值对调用 set_defaults() 方法来指定。但是，有时为参数指定单个解析器范围的默认值可能很有用。这可以通过将 argument_default= 关键字参数传递给 ArgumentParser 来实现。例如，要在 parse_args() 调用中全局抑制属性创建，我们提供 argument_default=SUPPRESS

>>> 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()

allow_abbrev¶

通常，当您将参数列表传递给 parse_args() 方法时，ArgumentParser 会识别长选项的缩写。

可以通过将 allow_abbrev 设置为 False 来禁用此功能

>>> 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'])
usage: PROG [-h] [--foobar] [--foonley]
PROG: error: unrecognized arguments: --foon

3.5 版新增。

conflict_handler¶

ArgumentParser 对象不允许两个操作使用相同的选项字符串。默认情况下，如果尝试使用已在使用的选项字符串创建参数，ArgumentParser 对象会引发异常

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-f', '--foo', help='old foo help')
>>> parser.add_argument('--foo', help='new foo help')
Traceback (most recent call last):
 ..
ArgumentError: argument --foo: conflicting option string(s): --foo

有时（例如，在使用 parents 时），简单地用具有相同选项字符串的任何较旧参数覆盖可能很有用。要获得此行为，可以将值 'resolve' 提供给 ArgumentParser 的 conflict_handler= 参数

>>> 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')
>>> parser.print_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

请注意，ArgumentParser 对象仅在其所有选项字符串都被覆盖时才删除操作。因此，在上面的示例中，旧的 -f/--foo 操作保留为 -f 操作，因为只有 --foo 选项字符串被覆盖。

add_help¶

默认情况下，ArgumentParser 对象会添加一个选项，该选项仅显示解析器的帮助消息。例如，考虑一个名为 myprogram.py 的文件，其中包含以下代码

import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--foo', help='foo help')
args = parser.parse_args()

如果在命令行中提供了 -h 或 --help，则将打印 ArgumentParser 帮助

$ python myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]

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

有时，禁用此帮助选项的添加可能很有用。这可以通过将 False 作为 add_help= 参数传递给 ArgumentParser 来实现

>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
>>> parser.add_argument('--foo', help='foo help')
>>> parser.print_help()
usage: PROG [--foo FOO]

options:
 --foo FOO  foo help

帮助选项通常为 -h/--help。例外情况是，如果指定了 prefix_chars= 并且不包含 -，在这种情况下，-h 和 --help 不是有效选项。在这种情况下，prefix_chars 中的第一个字符用于作为帮助选项的前缀

>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='+/')
>>> parser.print_help()
usage: PROG [+h]

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

exit_on_error¶

通常，当您将无效参数列表传递给 parse_args() 方法时，ArgumentParser 将退出并显示错误信息。

如果用户希望手动捕获错误，则可以通过将 exit_on_error 设置为 False 来启用该功能

>>> parser = argparse.ArgumentParser(exit_on_error=False)
>>> parser.add_argument('--integers', type=int)
_StoreAction(option_strings=['--integers'], dest='integers', nargs=None, const=None, default=None, type=<class 'int'>, choices=None, help=None, metavar=None)
>>> try:
...     parser.parse_args('--integers a'.split())
... except argparse.ArgumentError:
...     print('Catching an argumentError')
...
Catching an argumentError

3.9 版新增。

add_argument() 方法¶

ArgumentParser.add_argument(name or flags...[, action][, nargs][, const][, default][, type][, choices][, required][, help][, metavar][, dest])¶

定义如何解析单个命令行参数。每个参数在下面都有更详细的描述，但简而言之，它们是

名称或标志 - 名称或选项字符串列表，例如 foo 或 -f, --foo。
action - 在命令行遇到此参数时要采取的基本操作类型。
nargs - 应该消耗的命令行参数数量。
const - 一些 action 和 nargs 选择所需的常量值。
default - 如果命令行和命名空间对象中缺少该参数，则生成的值。
type - 命令行参数应转换成的类型。
choices - 参数允许值的序列。
required - 命令行选项是否可以省略（仅限可选参数）。
help - 参数作用的简要说明。
metavar - 用法消息中参数的名称。
dest - 要添加到 parse_args() 返回的对象的属性的名称。

以下部分描述了如何使用每个参数。

名称或标志¶

add_argument() 方法必须知道是期望可选参数（如 -f 或 --foo）还是位置参数（如文件名列表）。因此，传递给 add_argument() 的第一个参数必须是一系列标志或一个简单的参数名称。

例如，可以像这样创建一个可选参数

>>> parser.add_argument('-f', '--foo')

而位置参数可以像这样创建

>>> parser.add_argument('bar')

调用 parse_args() 时，可选参数将由 - 前缀标识，其余参数将假定为位置参数

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-f', '--foo')
>>> parser.add_argument('bar')
>>> parser.parse_args(['BAR'])
Namespace(bar='BAR', foo=None)
>>> parser.parse_args(['BAR', '--foo', 'FOO'])
Namespace(bar='BAR', foo='FOO')
>>> parser.parse_args(['--foo', 'FOO'])
usage: PROG [-h] [-f FOO] bar
PROG: error: the following arguments are required: bar

action¶

ArgumentParser 对象将命令行参数与操作相关联。这些操作可以对与其关联的命令行参数执行几乎任何操作，尽管大多数操作只是将属性添加到 parse_args() 返回的对象。 action 关键字参数指定应如何处理命令行参数。提供的操作是

'store' - 这只会存储参数的值。这是默认操作。例如

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.parse_args('--foo 1'.split())
Namespace(foo='1')

'store_const' - 这将存储 const 关键字参数指定的值；请注意，const 关键字参数默认为 None。 'store_const' 操作最常用于指定某种标志的可选参数。例如
```
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='store_const', const=42)
>>> parser.parse_args(['--foo'])
Namespace(foo=42)
```

'store_true' 和 'store_false' - 这些是 'store_const' 的特殊情况，分别用于存储值 True 和 False。此外，它们分别创建默认值 False 和 True。例如

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='store_true')
>>> parser.add_argument('--bar', action='store_false')
>>> parser.add_argument('--baz', action='store_false')
>>> parser.parse_args('--foo --bar'.split())
Namespace(foo=True, bar=False, baz=True)

'append' - 这将存储一个列表，并将每个参数值追加到该列表。允许多次指定一个选项很有用。如果默认值不为空，则默认元素将出现在选项的解析值中，命令行中的任何值都追加在这些默认值之后。使用示例
```
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='append')
>>> parser.parse_args('--foo 1 --foo 2'.split())
Namespace(foo=['1', '2'])
```

'append_const' - 这将存储一个列表，并将 const 关键字参数指定的值追加到该列表；请注意，const 关键字参数默认为 None。当多个参数需要将常量存储到同一个列表时，'append_const' 操作通常很有用。例如

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--str', dest='types', action='append_const', const=str)
>>> parser.add_argument('--int', dest='types', action='append_const', const=int)
>>> parser.parse_args('--str --int'.split())
Namespace(types=[<class 'str'>, <class 'int'>])

'count' - 这将计算关键字参数出现的次数。例如，这对于增加详细程度很有用

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

请注意，除非显式设置为 *0*，否则 *默认值* 将为 None。

'help' - 这将打印当前解析器中所有选项的完整帮助消息，然后退出。默认情况下，帮助操作会自动添加到解析器。有关输出创建方式的详细信息，请参阅 ArgumentParser。

'version' - 这需要在 add_argument() 调用中使用 version= 关键字参数，并在调用时打印版本信息并退出

>>> import argparse
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--version', action='version', version='%(prog)s 2.0')
>>> parser.parse_args(['--version'])
PROG 2.0

'extend' - 这将存储一个列表，并将每个参数值扩展到该列表。使用示例

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument("--foo", action="extend", nargs="+", type=str)
>>> parser.parse_args(["--foo", "f1", "--foo", "f2", "f3", "f4"])
Namespace(foo=['f1', 'f2', 'f3', 'f4'])

在 3.8 版中添加。

您还可以通过传递 Action 子类或实现相同接口的其他对象来指定任意操作。 BooleanOptionalAction 在 argparse 中可用，并添加了对布尔操作的支持，例如 --foo 和 --no-foo

>>> import argparse
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action=argparse.BooleanOptionalAction)
>>> parser.parse_args(['--no-foo'])
Namespace(foo=False)

3.9 版新增。

创建自定义操作的推荐方法是扩展 Action，覆盖 __call__ 方法，以及可选的 __init__ 和 format_usage 方法。

自定义操作示例

>>> class FooAction(argparse.Action):
...     def __init__(self, option_strings, dest, nargs=None, **kwargs):
...         if nargs is not None:
...             raise ValueError("nargs not allowed")
...         super().__init__(option_strings, dest, **kwargs)
...     def __call__(self, parser, namespace, values, option_string=None):
...         print('%r %r %r' % (namespace, values, option_string))
...         setattr(namespace, self.dest, values)
...
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action=FooAction)
>>> parser.add_argument('bar', action=FooAction)
>>> args = parser.parse_args('1 --foo 2'.split())
Namespace(bar=None, foo=None) '1' None
Namespace(bar='1', foo=None) '2' '--foo'
>>> args
Namespace(bar='1', foo='2')

有关更多详细信息，请参阅 Action。

nargs¶

ArgumentParser 对象通常将单个命令行参数与要采取的单个操作相关联。 nargs 关键字参数将不同数量的命令行参数与单个操作相关联。另请参阅指定不明确的参数。支持的值为

N（整数）。来自命令行的 N 个参数将被收集到一个列表中。例如

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', nargs=2)
>>> parser.add_argument('bar', nargs=1)
>>> parser.parse_args('c --foo a b'.split())
Namespace(bar=['c'], foo=['a', 'b'])

请注意，nargs=1 会生成一个包含一项的列表。这与默认值不同，在默认值中，该项本身就会生成。

'?'。如果可能，将从命令行使用一个参数，并将其生成为单个项目。如果没有命令行参数，则将生成 default 的值。请注意，对于可选参数，还有一种情况 - 存在选项字符串，但后面没有命令行参数。在这种情况下，将生成 const 的值。以下是一些说明这一点的示例

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

nargs='?' 的更常见用途之一是允许可选的输入和输出文件

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('infile', nargs='?', type=argparse.FileType('r'),
...                     default=sys.stdin)
>>> parser.add_argument('outfile', nargs='?', type=argparse.FileType('w'),
...                     default=sys.stdout)
>>> parser.parse_args(['input.txt', 'output.txt'])
Namespace(infile=<_io.TextIOWrapper name='input.txt' encoding='UTF-8'>,
          outfile=<_io.TextIOWrapper name='output.txt' encoding='UTF-8'>)
>>> parser.parse_args([])
Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>,
          outfile=<_io.TextIOWrapper name='<stdout>' encoding='UTF-8'>)

'*'。将存在的所有命令行参数收集到一个列表中。请注意，通常拥有多个 nargs='*' 的位置参数没有多大意义，但可以使用多个 nargs='*' 的可选参数。例如

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', nargs='*')
>>> parser.add_argument('--bar', nargs='*')
>>> parser.add_argument('baz', nargs='*')
>>> parser.parse_args('a b --foo x y --bar 1 2'.split())
Namespace(bar=['1', '2'], baz=['a', 'b'], foo=['x', 'y'])

'+'。就像 '*' 一样，将存在的所有命令行参数收集到一个列表中。此外，如果不存在至少一个命令行参数，则会生成错误消息。例如

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', nargs='+')
>>> parser.parse_args(['a', 'b'])
Namespace(foo=['a', 'b'])
>>> parser.parse_args([])
usage: PROG [-h] foo [foo ...]
PROG: error: the following arguments are required: foo

如果未提供 nargs 关键字参数，则使用的参数数量由 action 确定。通常，这意味着将使用一个命令行参数并生成一个项目（而不是列表）。

const¶

add_argument() 的 const 参数用于保存不从命令行读取但各种 ArgumentParser 操作所需的常量值。它的两个最常见用途是

当使用 action='store_const' 或 action='append_const' 调用 add_argument() 时。这些操作将 const 值添加到 parse_args() 返回的对象的属性之一。有关示例，请参阅 action 说明。如果未向 add_argument() 提供 const，它将收到默认值 None。
当使用选项字符串（如 -f 或 --foo）和 nargs='?' 调用 add_argument() 时。这将创建一个可选参数，该参数后跟零个或一个命令行参数。解析命令行时，如果遇到选项字符串后没有命令行参数，则将假定 const 的值为 None。有关示例，请参阅 nargs 说明。

版本 3.11 中的变化：默认情况下为 const=None，包括 action='append_const' 或 action='store_const' 时。

default¶

所有可选参数和一些位置参数都可以在命令行中省略。 add_argument() 的 default 关键字参数（其值默认为 None）指定如果不存在命令行参数，则应使用什么值。对于可选参数，如果命令行中不存在选项字符串，则使用 default 值

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=42)
>>> parser.parse_args(['--foo', '2'])
Namespace(foo='2')
>>> parser.parse_args([])
Namespace(foo=42)

如果目标命名空间已设置属性，则操作 *default* 不会覆盖它

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=42)
>>> parser.parse_args([], namespace=argparse.Namespace(foo=101))
Namespace(foo=101)

如果 default 值是字符串，则解析器会解析该值，就好像它是一个命令行参数一样。特别是，解析器在对 Namespace 返回值设置属性之前应用任何 type 转换参数（如果提供）。否则，解析器将按原样使用该值

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--length', default='10', type=int)
>>> parser.add_argument('--width', default=10.5, type=int)
>>> parser.parse_args()
Namespace(length=10, width=10.5)

对于 nargs 等于 ? 或 * 的位置参数，如果不存在命令行参数，则使用 default 值

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', nargs='?', default=42)
>>> parser.parse_args(['a'])
Namespace(foo='a')
>>> parser.parse_args([])
Namespace(foo=42)

提供 default=argparse.SUPPRESS 会导致在不存在命令行参数时不添加任何属性

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=argparse.SUPPRESS)
>>> parser.parse_args([])
Namespace()
>>> parser.parse_args(['--foo', '1'])
Namespace(foo='1')

type¶

默认情况下，解析器将命令行参数读取为简单字符串。但是，命令行字符串通常应该解释为另一种类型，例如 float 或 int。 add_argument() 的 type 关键字允许执行任何必要的类型检查和类型转换。

如果将 type 关键字与 default 关键字一起使用，则仅当默认值为字符串时才应用类型转换器。

type 的参数可以是任何接受单个字符串的可调用对象。如果函数引发 ArgumentTypeError、TypeError 或 ValueError，则会捕获该异常并显示格式良好的错误消息。不处理其他异常类型。

常见的内置类型和函数可以用作类型转换器

import argparse
import pathlib

parser = argparse.ArgumentParser()
parser.add_argument('count', type=int)
parser.add_argument('distance', type=float)
parser.add_argument('street', type=ascii)
parser.add_argument('code_point', type=ord)
parser.add_argument('source_file', type=open)
parser.add_argument('dest_file', type=argparse.FileType('w', encoding='latin-1'))
parser.add_argument('datapath', type=pathlib.Path)

用户定义的函数也可以使用

>>> def hyphenated(string):
...     return '-'.join([word[:4] for word in string.casefold().split()])
...
>>> parser = argparse.ArgumentParser()
>>> _ = parser.add_argument('short_title', type=hyphenated)
>>> parser.parse_args(['"The Tale of Two Cities"'])
Namespace(short_title='"the-tale-of-two-citi')

不建议将 bool() 函数用作类型转换器。它所做的只是将空字符串转换为 False，将非空字符串转换为 True。这通常不是我们想要的。

通常，type 关键字只是一种便利，应该只用于只能引发三种受支持异常之一的简单转换。任何具有更有趣的错误处理或资源管理的操作都应该在解析参数后在下游完成。

例如，JSON 或 YAML 转换具有复杂的错误情况，需要比 type 关键字所能提供的更好的报告。 JSONDecodeError 的格式不正确，并且根本不会处理 FileNotFoundError 异常。

即使 FileType 与 type 关键字一起使用也存在局限性。如果一个参数使用 *FileType*，而随后的参数失败，则会报告错误，但不会自动关闭文件。在这种情况下，最好等到解析器运行后，然后使用 with 语句来管理文件。

对于仅根据一组固定值进行检查的类型检查器，请考虑改用 choices 关键字。

选项¶

某些命令行参数应该从一组受限的值中选择。可以通过将序列对象作为 choices 关键字参数传递给 add_argument() 来处理这些参数。解析命令行时，将检查参数值，如果参数不是可接受的值之一，则会显示错误消息。

>>> parser = argparse.ArgumentParser(prog='game.py')
>>> parser.add_argument('move', choices=['rock', 'paper', 'scissors'])
>>> parser.parse_args(['rock'])
Namespace(move='rock')
>>> parser.parse_args(['fire'])
usage: game.py [-h] {rock,paper,scissors}
game.py: error: argument move: invalid choice: 'fire' (choose from 'rock',
'paper', 'scissors')

请注意，在执行任何类型转换后，才会检查 choices 序列中的包含情况，因此 choices 序列中对象的类型应与指定的类型匹配。

>>> parser = argparse.ArgumentParser(prog='doors.py')
>>> parser.add_argument('door', type=int, choices=range(1, 4))
>>> print(parser.parse_args(['3']))
Namespace(door=3)
>>> parser.parse_args(['4'])
usage: doors.py [-h] {1,2,3}
doors.py: error: argument door: invalid choice: 4 (choose from 1, 2, 3)

任何序列都可以作为 choices 值传递，因此支持 list 对象、tuple 对象和自定义序列。

不建议使用 enum.Enum，因为它难以控制其在使用情况、帮助和错误消息中的显示方式。

格式化的选项会覆盖默认的 metavar，该默认值通常从 dest 派生。这通常是您想要的，因为用户永远不会看到 dest 参数。如果这种显示方式不理想（可能是因为选项太多），只需指定一个显式的 metavar。

必需¶

通常，argparse 模块假定像 -f 和 --bar 这样的标志表示可选参数，这些参数在命令行中始终可以省略。要使选项必需，可以为 add_argument() 的 required= 关键字参数指定 True。

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', required=True)
>>> parser.parse_args(['--foo', 'BAR'])
Namespace(foo='BAR')
>>> parser.parse_args([])
usage: [-h] --foo FOO
: error: the following arguments are required: --foo

如示例所示，如果将选项标记为 required，则如果该选项未出现在命令行中，parse_args() 将报告错误。

注意

必需选项通常被认为是不好的形式，因为用户期望选项是可选的，因此应尽可能避免使用它们。

帮助¶

help 值是一个字符串，其中包含参数的简要说明。当用户请求帮助时（通常通过在命令行中使用 -h 或 --help），将显示每个参数的这些 help 说明。

>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('--foo', action='store_true',
...                     help='foo the bars before frobbling')
>>> parser.add_argument('bar', nargs='+',
...                     help='one of the bars to be frobbled')
>>> parser.parse_args(['-h'])
usage: frobble [-h] [--foo] bar [bar ...]

positional arguments:
 bar     one of the bars to be frobbled

options:
 -h, --help  show this help message and exit
 --foo   foo the bars before frobbling

help 字符串可以包含各种格式说明符，以避免重复程序名称或参数默认值之类的内容。可用的说明符包括程序名称 %(prog)s 和 add_argument() 的大多数关键字参数，例如 %(default)s、%(type)s 等。

>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('bar', nargs='?', type=int, default=42,
...                     help='the bar to %(prog)s (default: %(default)s)')
>>> parser.print_help()
usage: frobble [-h] [bar]

positional arguments:
 bar     the bar to frobble (default: 42)

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

由于帮助字符串支持 %- 格式化，因此如果要在帮助字符串中显示文字 %，则必须将其转义为 %%。

argparse 支持通过将 help 值设置为 argparse.SUPPRESS 来隐藏某些选项的帮助条目。

>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('--foo', help=argparse.SUPPRESS)
>>> parser.print_help()
usage: frobble [-h]

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

metavar¶

当 ArgumentParser 生成帮助消息时，它需要某种方式来引用每个预期参数。默认情况下，ArgumentParser 对象使用 dest 值作为每个对象的“名称”。默认情况下，对于位置参数操作，直接使用 dest 值，对于可选参数操作，将 dest 值转换为大写。因此，dest='bar' 的单个位置参数将被称为 bar。后跟单个命令行参数的单个可选参数 --foo 将被称为 FOO。例如：

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.add_argument('bar')
>>> parser.parse_args('X --foo Y'.split())
Namespace(bar='X', foo='Y')
>>> parser.print_help()
usage:  [-h] [--foo FOO] bar

positional arguments:
 bar

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

可以使用 metavar 指定备用名称。

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', metavar='YYY')
>>> parser.add_argument('bar', metavar='XXX')
>>> parser.parse_args('X --foo Y'.split())
Namespace(bar='X', foo='Y')
>>> parser.print_help()
usage:  [-h] [--foo YYY] XXX

positional arguments:
 XXX

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

请注意，metavar 仅更改显示的名称 - parse_args() 对象上的属性名称仍由 dest 值确定。

nargs 的不同值可能会导致多次使用 metavar。为 metavar 提供元组可为每个参数指定不同的显示方式。

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x', nargs=2)
>>> parser.add_argument('--foo', nargs=2, metavar=('bar', 'baz'))
>>> parser.print_help()
usage: PROG [-h] [-x X X] [--foo bar baz]

options:
 -h, --help     show this help message and exit
 -x X X
 --foo bar baz

dest¶

大多数 ArgumentParser 操作都会将一些值添加为 parse_args() 返回的对象的属性。此属性的名称由 add_argument() 的 dest 关键字参数确定。对于位置参数操作，dest 通常作为第一个参数提供给 add_argument()。

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('bar')
>>> parser.parse_args(['XXX'])
Namespace(bar='XXX')

对于可选参数操作，dest 的值通常从选项字符串推断出来。ArgumentParser 通过获取第一个长选项字符串并删除初始 -- 字符串来生成 dest 的值。如果没有提供长选项字符串，则将通过删除初始 - 字符从第一个短选项字符串派生 dest。任何内部 - 字符都将转换为 _ 字符，以确保该字符串是有效的属性名称。以下示例说明了此行为：

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('-f', '--foo-bar', '--foo')
>>> parser.add_argument('-x', '-y')
>>> parser.parse_args('-f 1 -x 2'.split())
Namespace(foo_bar='1', x='2')
>>> parser.parse_args('--foo 1 -y 2'.split())
Namespace(foo_bar='1', x='2')

dest 允许提供自定义属性名称。

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', dest='bar')
>>> parser.parse_args('--foo XXX'.split())
Namespace(bar='XXX')

操作类¶

操作类实现 Action API，这是一个可调用对象，它返回一个可调用对象，该对象处理来自命令行的参数。任何遵循此 API 的对象都可以作为 action 参数传递给 add_argument()。

class argparse.Action(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)¶

ArgumentParser 使用动作对象来表示从命令行的一个或多个字符串中解析单个参数所需的信息。 Action 类必须接受两个位置参数以及传递给 ArgumentParser.add_argument() 的任何关键字参数，但 action 本身除外。

Action 的实例（或任何可调用对象到 action 参数的返回值）应该定义了 “dest”、 “option_strings”、 “default”、 “type”、 “required”、 “help” 等属性。确保定义这些属性的最简单方法是调用 Action.__init__。

Action 实例应该是可调用的，因此子类必须重写 __call__ 方法，该方法应该接受四个参数

parser - 包含此操作的 ArgumentParser 对象。
namespace - 将由 parse_args() 返回的 Namespace 对象。大多数操作使用 setattr() 将属性添加到此对象。
values - 关联的命令行参数，并应用了任何类型转换。类型转换使用 add_argument() 的 type 关键字参数指定。
option_string - 用于调用此操作的选项字符串。 option_string 参数是可选的，如果操作与位置参数相关联，则将不存在。

__call__ 方法可以执行任意操作，但通常会根据 dest 和 values 在 namespace 上设置属性。

Action 子类可以定义一个 format_usage 方法，该方法不带参数并返回一个字符串，该字符串将在打印程序的使用方法时使用。如果未提供此类方法，则将使用合理的默认值。

parse_args() 方法¶

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

将参数字符串转换为对象并将它们分配为命名空间的属性。返回填充的命名空间。

先前对 add_argument() 的调用精确地确定了创建哪些对象以及如何分配它们。有关详细信息，请参阅 add_argument() 的文档。

args - 要解析的字符串列表。默认值取自 sys.argv。
namespace - 用于获取属性的对象。默认值是一个新的空 Namespace 对象。

选项值语法¶

parse_args() 方法支持几种指定选项值的方式（如果需要）。在最简单的情况下，选项及其值作为两个单独的参数传递

>>> 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)

对于短选项（只有一个字符长的选项），选项及其值可以连接在一起

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

只要只有最后一个选项（或没有选项）需要值，就可以使用单个 - 前缀将多个短选项连接在一起

>>> 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')

无效参数¶

在解析命令行时，parse_args() 会检查各种错误，包括不明确的选项、无效的类型、无效的选项、错误数量的位置参数等。当它遇到这样的错误时，它会退出并打印错误以及使用消息

>>> 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

包含 `-` 的参数¶

parse_args() 方法试图在用户明显出错时给出错误，但有些情况本质上是模棱两可的。例如，命令行参数 -1 可能是尝试指定选项，也可能是尝试提供位置参数。 parse_args() 方法在这里很谨慎：位置参数只能以 - 开头，如果它们看起来像负数，并且解析器中没有看起来像负数的选项

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

>>> # no negative number options, so -1 is a positional argument
>>> parser.parse_args(['-x', '-1'])
Namespace(foo=None, x='-1')

>>> # no negative number options, so -1 and -5 are positional arguments
>>> 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='?')

>>> # negative number options present, so -1 is an option
>>> parser.parse_args(['-1', 'X'])
Namespace(foo=None, one='X')

>>> # negative number options present, so -2 is an option
>>> parser.parse_args(['-2'])
usage: PROG [-h] [-1 ONE] [foo]
PROG: error: no such option: -2

>>> # negative number options present, so both -1s are options
>>> parser.parse_args(['-1', '-1'])
usage: PROG [-h] [-1 ONE] [foo]
PROG: error: argument -1: expected one argument

如果您的位置参数必须以 - 开头并且看起来不像负数，则可以插入伪参数 '--'，这告诉 parse_args() 之后的所有内容都是位置参数

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

有关更多详细信息，请参阅关于不明确参数的 argparse 操作指南。

参数缩写（前缀匹配）¶

parse_args() 方法默认情况下允许将长选项缩写为前缀，如果缩写是明确的（前缀匹配唯一的选项）

>>> 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

对于可能产生多个选项的参数，会产生错误。可以通过将 allow_abbrev 设置为 False 来禁用此功能。

超越 `sys.argv`¶

有时，让 ArgumentParser 解析 sys.argv 以外的参数可能很有用。这可以通过将字符串列表传递给 parse_args() 来实现。这对于在交互式提示符下进行测试很有用

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument(
...     'integers', metavar='int', type=int, choices=range(10),
...     nargs='+', help='an integer in the range 0..9')
>>> parser.add_argument(
...     '--sum', dest='accumulate', action='store_const', const=sum,
...     default=max, help='sum the integers (default: find the max)')
>>> parser.parse_args(['1', '2', '3', '4'])
Namespace(accumulate=<built-in function max>, integers=[1, 2, 3, 4])
>>> parser.parse_args(['1', '2', '3', '4', '--sum'])
Namespace(accumulate=<built-in function sum>, integers=[1, 2, 3, 4])

Namespace 对象¶

class argparse.Namespace¶: parse_args() 默认使用的简单类，用于创建保存属性的对象并返回它。

这个类故意简单，只是一个具有可读字符串表示形式的 object 子类。如果你更喜欢以类似字典的方式查看属性，可以使用标准的 Python idiom，vars()

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> args = parser.parse_args(['--foo', 'BAR'])
>>> vars(args)
{'foo': 'BAR'}

让 ArgumentParser 将属性分配给已存在的对象，而不是新的 Namespace 对象，这可能也很有用。这可以通过指定 namespace= 关键字参数来实现。

>>> class C:
...     pass
...
>>> c = C()
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.parse_args(args=['--foo', 'BAR'], namespace=c)
>>> c.foo
'BAR'

其他实用程序¶

子命令¶

ArgumentParser.add_subparsers([title][, description][, prog][, parser_class][, action][, option_strings][, dest][, required][, help][, metavar])¶

许多程序将其功能拆分为多个子命令，例如，svn 程序可以调用 svn checkout、svn update 和 svn commit 等子命令。当程序执行需要不同类型命令行参数的多种不同功能时，以这种方式拆分功能可能是一个特别好的主意。ArgumentParser 支持使用 add_subparsers() 方法创建此类子命令。add_subparsers() 方法通常不带参数调用，并返回一个特殊的动作对象。此对象有一个方法 add_parser()，它接受一个命令名称和任何 ArgumentParser 构造函数参数，并返回一个可以像往常一样修改的 ArgumentParser 对象。

参数说明

title - 帮助输出中子解析器组的标题；默认情况下，如果提供了描述，则为“子命令”，否则使用位置参数的标题
description - 帮助输出中子解析器组的描述，默认为 None
prog - 将与子命令帮助一起显示的使用信息，默认为程序的名称和子解析器参数之前的任何位置参数
parser_class - 将用于创建子解析器实例的类，默认为当前解析器的类（例如 ArgumentParser）
action - 在命令行遇到此参数时要采取的基本操作类型
dest - 将在其下存储子命令名称的属性的名称；默认为 None 并且不存储任何值
required - 是否必须提供子命令，默认为 False（在 3.7 中添加）
help - 帮助输出中子解析器组的帮助，默认为 None
metavar - 在帮助中显示可用子命令的字符串；默认情况下，它为 None 并以 {cmd1, cmd2, ..} 的形式显示子命令

一些使用示例

>>> # create the top-level parser
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo', action='store_true', help='foo help')
>>> subparsers = parser.add_subparsers(help='sub-command help')
>>>
>>> # create the parser for the "a" command
>>> parser_a = subparsers.add_parser('a', help='a help')
>>> parser_a.add_argument('bar', type=int, help='bar help')
>>>
>>> # create the parser for the "b" command
>>> parser_b = subparsers.add_parser('b', help='b help')
>>> parser_b.add_argument('--baz', choices='XYZ', help='baz help')
>>>
>>> # parse some argument lists
>>> parser.parse_args(['a', '12'])
Namespace(bar=12, foo=False)
>>> parser.parse_args(['--foo', 'b', '--baz', 'Z'])
Namespace(baz='Z', foo=True)

请注意，parse_args() 返回的对象将仅包含主解析器和命令行选择的子解析器的属性（而不包含任何其他子解析器）。因此，在上面的示例中，当指定 a 命令时，仅存在 foo 和 bar 属性，而当指定 b 命令时，仅存在 foo 和 baz 属性。

同样，当从子解析器请求帮助消息时，将仅打印该特定解析器的帮助。帮助消息将不包括父解析器或兄弟解析器消息。（但是，可以通过向 add_parser() 提供 help= 参数来提供每个子解析器命令的帮助消息，如上所示。）

>>> parser.parse_args(['--help'])
usage: PROG [-h] [--foo] {a,b} ...

positional arguments:
  {a,b}   sub-command help
    a     a help
    b     b help

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

>>> parser.parse_args(['a', '--help'])
usage: PROG a [-h] bar

positional arguments:
  bar     bar help

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

>>> parser.parse_args(['b', '--help'])
usage: PROG b [-h] [--baz {X,Y,Z}]

options:
  -h, --help     show this help message and exit
  --baz {X,Y,Z}  baz help

add_subparsers() 方法还支持 title 和 description 关键字参数。当其中任何一个存在时，子解析器的命令将出现在帮助输出中自己的组中。例如

>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers(title='subcommands',
...                                    description='valid subcommands',
...                                    help='additional help')
>>> subparsers.add_parser('foo')
>>> subparsers.add_parser('bar')
>>> parser.parse_args(['-h'])
usage:  [-h] {foo,bar} ...

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

subcommands:
  valid subcommands

  {foo,bar}   additional help

此外，add_parser 支持额外的 aliases 参数，该参数允许多个字符串引用同一个子解析器。此示例与 svn 一样，将 co 作为 checkout 的简写

>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers()
>>> checkout = subparsers.add_parser('checkout', aliases=['co'])
>>> checkout.add_argument('foo')
>>> parser.parse_args(['co', 'bar'])
Namespace(foo='bar')

处理子命令的一种特别有效的方法是将 add_subparsers() 方法的使用与对 set_defaults() 的调用结合起来，以便每个子解析器都知道它应该执行哪个 Python 函数。例如

>>> # sub-command functions
>>> def foo(args):
...     print(args.x * args.y)
...
>>> def bar(args):
...     print('((%s))' % args.z)
...
>>> # create the top-level parser
>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers(required=True)
>>>
>>> # create the parser for the "foo" command
>>> parser_foo = subparsers.add_parser('foo')
>>> parser_foo.add_argument('-x', type=int, default=1)
>>> parser_foo.add_argument('y', type=float)
>>> parser_foo.set_defaults(func=foo)
>>>
>>> # create the parser for the "bar" command
>>> parser_bar = subparsers.add_parser('bar')
>>> parser_bar.add_argument('z')
>>> parser_bar.set_defaults(func=bar)
>>>
>>> # parse the args and call whatever function was selected
>>> args = parser.parse_args('foo 1 -x 2'.split())
>>> args.func(args)
2.0
>>>
>>> # parse the args and call whatever function was selected
>>> args = parser.parse_args('bar XYZYX'.split())
>>> args.func(args)
((XYZYX))

这样，您就可以让 parse_args() 在参数解析完成后调用适当的函数。像这样将函数与操作相关联通常是处理每个子解析器的不同操作的最简单方法。但是，如果需要检查调用的子解析器的名称，则 add_subparsers() 调用的 dest 关键字参数将起作用

>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers(dest='subparser_name')
>>> subparser1 = subparsers.add_parser('1')
>>> subparser1.add_argument('-x')
>>> subparser2 = subparsers.add_parser('2')
>>> subparser2.add_argument('y')
>>> parser.parse_args(['2', 'frobble'])
Namespace(subparser_name='2', y='frobble')

在 3.7 版更改: 新的 required 关键字参数。

FileType 对象¶

class argparse.FileType(mode='r', bufsize=-1, encoding=None, errors=None)¶

FileType 工厂创建的对象可以传递给 ArgumentParser.add_argument() 的 type 参数。参数类型为 FileType 对象时，会以请求的模式、缓冲区大小、编码和错误处理方式打开命令行参数作为文件（有关详细信息，请参阅 open() 函数）

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--raw', type=argparse.FileType('wb', 0))
>>> parser.add_argument('out', type=argparse.FileType('w', encoding='UTF-8'))
>>> parser.parse_args(['--raw', 'raw.dat', 'file.txt'])
Namespace(out=<_io.TextIOWrapper name='file.txt' mode='w' encoding='UTF-8'>, raw=<_io.FileIO name='raw.dat' mode='wb'>)

FileType 对象能够识别伪参数 '-'，并自动将其转换为可读 FileType 对象的 sys.stdin 和可写 FileType 对象的 sys.stdout

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('infile', type=argparse.FileType('r'))
>>> parser.parse_args(['-'])
Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>)

版本 3.4 中的变化：添加了 encodings 和 errors 参数。

参数组¶

ArgumentParser.add_argument_group(title=None, description=None)¶

默认情况下，ArgumentParser 在显示帮助消息时，会将命令行参数分组为“位置参数”和“选项”。当存在比默认分组更好的概念分组时，可以使用 add_argument_group() 方法创建适当的组

>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
>>> group = parser.add_argument_group('group')
>>> group.add_argument('--foo', help='foo help')
>>> group.add_argument('bar', help='bar help')
>>> parser.print_help()
usage: PROG [--foo FOO] bar

group:
  bar    bar help
  --foo FOO  foo help

add_argument_group() 方法返回一个参数组对象，该对象具有与常规 ArgumentParser 相同的 add_argument() 方法。当将参数添加到组时，解析器会像对待普通参数一样对待它，但在帮助消息中将该参数显示在一个单独的组中。add_argument_group() 方法接受 title 和 description 参数，可用于自定义此显示

>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
>>> group1 = parser.add_argument_group('group1', 'group1 description')
>>> group1.add_argument('foo', help='foo help')
>>> group2 = parser.add_argument_group('group2', 'group2 description')
>>> group2.add_argument('--bar', help='bar help')
>>> parser.print_help()
usage: PROG [--bar BAR] foo

group1:
  group1 description

  foo    foo help

group2:
  group2 description

  --bar BAR  bar help

请注意，任何不在用户定义组中的参数最终都将回到通常的“位置参数”和“可选参数”部分。

版本 3.11 中的变化：不推荐在参数组上调用 add_argument_group()。此功能从未受支持，并且并非始终正常工作。该函数是通过继承意外出现在 API 中的，将来会被移除。

互斥¶

ArgumentParser.add_mutually_exclusive_group(required=False)¶

创建一个互斥组。argparse 将确保在命令行上只出现互斥组中的一个参数

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> group = parser.add_mutually_exclusive_group()
>>> group.add_argument('--foo', action='store_true')
>>> group.add_argument('--bar', action='store_false')
>>> parser.parse_args(['--foo'])
Namespace(bar=True, foo=True)
>>> parser.parse_args(['--bar'])
Namespace(bar=False, foo=False)
>>> parser.parse_args(['--foo', '--bar'])
usage: PROG [-h] [--foo | --bar]
PROG: error: argument --bar: not allowed with argument --foo

add_mutually_exclusive_group() 方法还接受一个 required 参数，以指示至少需要一个互斥参数

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> group = parser.add_mutually_exclusive_group(required=True)
>>> group.add_argument('--foo', action='store_true')
>>> group.add_argument('--bar', action='store_false')
>>> parser.parse_args([])
usage: PROG [-h] (--foo | --bar)
PROG: error: one of the arguments --foo --bar is required

请注意，当前互斥参数组不支持 add_argument_group() 的 title 和 description 参数。但是，可以将互斥组添加到具有标题和描述的参数组中。例如

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> group = parser.add_argument_group('Group title', 'Group description')
>>> exclusive_group = group.add_mutually_exclusive_group(required=True)
>>> exclusive_group.add_argument('--foo', help='foo help')
>>> exclusive_group.add_argument('--bar', help='bar help')
>>> parser.print_help()
usage: PROG [-h] (--foo FOO | --bar BAR)

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

Group title:
  Group description

  --foo FOO   foo help
  --bar BAR   bar help

版本 3.11 中的变化：不推荐在互斥组上调用 add_argument_group() 或 add_mutually_exclusive_group()。这些功能从未受支持，并且并非始终正常工作。这些函数是通过继承意外出现在 API 中的，将来会被移除。

解析器默认值¶

ArgumentParser.set_defaults(**kwargs)¶

大多数情况下，parse_args() 返回的对象的属性将通过检查命令行参数和参数操作来完全确定。set_defaults() 允许添加一些无需检查命令行即可确定的附加属性

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', type=int)
>>> parser.set_defaults(bar=42, baz='badger')
>>> parser.parse_args(['736'])
Namespace(bar=42, baz='badger', foo=736)

请注意，解析器级别的默认值始终会覆盖参数级别的默认值

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default='bar')
>>> parser.set_defaults(foo='spam')
>>> parser.parse_args([])
Namespace(foo='spam')

在使用多个解析器时，解析器级别的默认值特别有用。有关此类型的示例，请参阅 add_subparsers() 方法。

ArgumentParser.get_default(dest)¶

获取命名空间属性的默认值，该值由 add_argument() 或 set_defaults() 设置

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default='badger')
>>> parser.get_default('foo')
'badger'

打印帮助信息¶

在大多数典型应用中，parse_args() 将负责格式化和打印任何使用情况或错误消息。但是，可以使用几种格式化方法

ArgumentParser.print_usage(file=None)¶: 打印有关如何在命令行上调用 ArgumentParser 的简要说明。如果 file 为 None，则假定为 sys.stdout。

ArgumentParser.print_help(file=None)¶: 打印帮助消息，包括程序用法和使用 ArgumentParser 注册的参数信息。如果 *file* 是 None，则假定为 sys.stdout。

还有一些变体方法，它们只是返回一个字符串而不是打印它。

ArgumentParser.format_usage()¶: 返回一个字符串，其中包含有关如何在命令行上调用 ArgumentParser 的简要说明。

ArgumentParser.format_help()¶: 返回一个字符串，其中包含帮助消息，包括程序用法和使用 ArgumentParser 注册的参数信息。

部分解析¶

ArgumentParser.parse_known_args(args=None, namespace=None)¶

有时，脚本可能只解析命令行参数中的一部分，并将剩余的参数传递给另一个脚本或程序。在这些情况下，parse_known_args() 方法可能很有用。它的工作方式与 parse_args() 非常相似，只是在存在额外参数时不会产生错误。相反，它返回一个包含两个项目的元组：填充的命名空间和剩余参数字符串的列表。

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='store_true')
>>> parser.add_argument('bar')
>>> parser.parse_known_args(['--foo', '--badger', 'BAR', 'spam'])
(Namespace(bar='BAR', foo=True), ['--badger', 'spam'])

警告

前缀匹配规则适用于 parse_known_args()。解析器可能会消耗一个选项，即使它只是其已知选项之一的前缀，而不是将其保留在剩余的参数列表中。

自定义文件解析¶

ArgumentParser.convert_arg_line_to_args(arg_line)¶

从文件读取的参数（请参阅 ArgumentParser 构造函数的 *fromfile_prefix_chars* 关键字参数）是每行读取一个参数。可以覆盖 convert_arg_line_to_args() 以实现更高级的读取。

此方法接受单个参数 *arg_line*，它是从参数文件读取的字符串。它返回从此字符串解析的参数列表。每次从参数文件中读取一行时，都会按顺序调用一次此方法。

此方法的一个有用的覆盖是将每个空格分隔的单词视为一个参数。以下示例演示了如何执行此操作。

class MyArgumentParser(argparse.ArgumentParser):
    def convert_arg_line_to_args(self, arg_line):
        return arg_line.split()

退出方法¶

ArgumentParser.exit(status=0, message=None)¶

此方法终止程序，并以指定的 *status* 退出，如果给出，它会在退出之前打印一条 *message*。用户可以覆盖此方法以不同方式处理这些步骤。

class ErrorCatchingArgumentParser(argparse.ArgumentParser):
    def exit(self, status=0, message=None):
        if status:
            raise Exception(f'Exiting because of an error: {message}')
        exit(status)

ArgumentParser.error(message)¶: 此方法将打印一条包含 *message* 的使用消息到标准错误输出，并以状态码 2 终止程序。

混合解析¶

ArgumentParser.parse_intermixed_args(args=None, namespace=None)¶

ArgumentParser.parse_known_intermixed_args(args=None, namespace=None)¶

许多 Unix 命令允许用户将可选参数与位置参数混合使用。parse_intermixed_args() 和 parse_known_intermixed_args() 方法支持这种解析风格。

这些解析器不支持所有 argparse 功能，如果使用不受支持的功能，将会引发异常。特别是，不支持子解析器以及同时包含可选参数和位置参数的互斥组。

以下示例显示了 parse_known_args() 和 parse_intermixed_args() 之间的区别：前者返回 ['2', '3'] 作为未解析的参数，而后者将所有位置参数收集到 rest 中。

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.add_argument('cmd')
>>> parser.add_argument('rest', nargs='*', type=int)
>>> parser.parse_known_args('doit 1 --foo bar 2 3'.split())
(Namespace(cmd='doit', foo='bar', rest=[1]), ['2', '3'])
>>> parser.parse_intermixed_args('doit 1 --foo bar 2 3'.split())
Namespace(cmd='doit', foo='bar', rest=[1, 2, 3])

parse_known_intermixed_args() 返回一个包含两个项目的元组：填充的命名空间和剩余参数字符串的列表。如果存在任何剩余的未解析参数字符串，parse_intermixed_args() 会引发错误。

3.7 版新增。

升级 optparse 代码¶

最初，argparse 模块试图保持与 optparse 的兼容性。但是，optparse 难以透明地扩展，特别是对于支持新的 nargs= 说明符和更好的使用消息所需的更改。当 optparse 中的大多数内容都被复制粘贴或猴子补丁时，尝试保持向后兼容性似乎不再可行。

argparse 模块在许多方面改进了标准库 optparse 模块，包括：

处理位置参数。
支持子命令。
允许使用替代选项前缀，例如 + 和 /。
处理零个或多个和一个或多个样式的参数。
生成信息更丰富的使用消息。
为自定义 type 和 action 提供更简单的接口。

从 optparse 到 argparse 的部分升级路径

将所有 optparse.OptionParser.add_option() 调用替换为 ArgumentParser.add_argument() 调用。
将 (options, args) = parser.parse_args() 替换为 args = parser.parse_args() 并为位置参数添加额外的 ArgumentParser.add_argument() 调用。请记住，以前在 argparse 上下文中称为 options 的内容现在称为 args。
通过使用 parse_intermixed_args() 代替 parse_args() 来替换 optparse.OptionParser.disable_interspersed_args()。
使用 type 或 action 参数替换回调操作和 callback_* 关键字参数。
将 type 关键字参数的字符串名称替换为相应的类型对象（例如 int、float、complex 等）。
将 optparse.Values 替换为 Namespace，并将 optparse.OptionError 和 optparse.OptionValueError 替换为 ArgumentError。
使用标准 Python 语法将包含隐式参数（例如 %default 或 %prog）的字符串替换为使用字典来格式化字符串，即 %(default)s 和 %(prog)s。
将 OptionParser 构造函数的 version 参数替换为对 parser.add_argument('--version', action='version', version='<版本号>') 的调用。

异常¶

异常 argparse.ArgumentError¶

创建或使用参数（可选或位置参数）时出错。

此异常的字符串值是消息，其中添加了有关导致该异常的参数的信息。

异常 argparse.ArgumentTypeError¶: 在将命令行字符串转换为类型时出错。

argparse — 命令行选项、参数和子命令的解析器¶