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

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

3.2 新版功能.

教程

此页面包含该 API 的参考信息。有关 Python 命令行解析更细致的介绍，请参阅 argparse 教程。

argparse 模块可以让人轻松编写用户友好的命令行接口。程序定义它需要的参数，然后 argparse 将弄清如何从 sys.argv 解析出那些参数。 argparse 模块还会自动生成帮助和使用手册，并在用户给程序传入无效参数时报出错误信息。

示例

以下代码是一个 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
 
optional arguments:
 -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 如何获取命令行字符串并将其转换为对象。这些信息在 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)
创建一个新的 ArgumentParser 对象。所有的参数都应当作为关键字参数传入。每个参数在下面都有它更详细的描述，但简而言之，它们是：
- prog - 程序的名称（默认值：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）

在 3.5 版更改: 增加了 allow_abbrev 参数。

以下部分描述这些参数如何使用。

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]
 
optional arguments:
 -h, --help  show this help message and exit
 --foo FOO   foo help
$ cd ..
$ python subdir/myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]
 
optional arguments:
 -h, --help  show this help message and exit
 --foo FOO   foo help

要更改这样的默认行为，可以使用 prog= 参数为 ArgumentParser 指定另一个值：

>>> parser = argparse.ArgumentParser(prog='myprogram')
>>> parser.print_help()
usage: myprogram [-h]
 
optional arguments:
 -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]
 
optional arguments:
 -h, --help  show this help message and exit
 --foo FOO   foo of the myprogram program

usage

默认情况下，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
 
optional arguments:
 -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
 
optional arguments:
 -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
 
optional arguments:
 -h, --help  show this help message and exit

在默认情况下，description 将被换行以便适应给定的空间。如果想改变这种行为，见 formatter_class 参数。

epilog

一些程序喜欢在 description 参数后显示额外的对程序的描述。这种文字能够通过给 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
 
optional arguments:
 -h, --help  show this help message and exit
 
And that's how you'd foo a bar

和 description 参数一样，epilog= text 在默认情况下会换行，但是这种行为能够被调整通过提供 formatter_class 参数给 ArgumentParse.

parents

有些时候，少数解析器会使用同一系列参数。单个解析器能够通过提供 parents= 参数给 ArgumentParser 而使用相同的参数而不是重复这些参数的定义。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 . 否则， ArgumentParse 将会看到两个 -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
 
optional arguments:
 -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
 
optional arguments:
 -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 [bar ...]]
 
positional arguments:
 bar         BAR! (default: [1, 2, 3])
 
optional arguments:
 -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
 
optional arguments:
  -h, --help  show this help message and exit
  --foo int

prefix_chars

许多命令行会使用 - 当作前缀，比如 -f/—foo。如果解析器需要支持不同的或者额外的字符，比如像 +f 或者 /foo 的选项，可以在参数解析构建器中使用 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')

The prefix_chars= 参数默认使用 '-'. 支持一系列字符，但是不包括 - ，这样会产生不被允许的 -f/—foo 选项。

fromfile_prefix_chars

有些时候，先举个例子，当处理一个特别长的参数列表的时候，把它存入一个文件中而不是在命令行打出来会很有意义。如果 fromfile_prefix_chars= 参数提供给 ArgumentParser 构造函数，之后所有类型的字符的参数都会被当成文件处理，并且会被文件包含的参数替代。举个栗子:

>>> with open('args.txt', 'w') 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'] 的表示相同。

fromfile_prefix_chars= 参数默认为 None，意味着参数不会被当作文件对待。

argument_default

一般情况下，参数默认会通过设置一个默认到 add_argument() 或者调用带一组指定键值对的 ArgumentParser.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

正常情况下，当你向 ArgumentParser 的 parse_args() 方法传入一个参数列表时，它会 recognizes abbreviations。

这个特性可以设置 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]
 
optional arguments:
 -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 or —help 在命令行中被提供, 参数解析器帮助信息会打印:

$ python myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]
 
optional arguments:
 -h, --help  show this help message and exit
 --foo FOO   foo help

有时候可能会需要关闭额外的帮助信息。这可以通过在 ArgumentParser 中设置 add_help= 参数为 False 来实现。

>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
>>> parser.add_argument('--foo', help='foo help')
>>> parser.print_help()
usage: PROG [--foo FOO]
 
optional arguments:
 --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]
 
optional arguments:
  +h, ++help  show this help message and exit

add_argument() 方法

ArgumentParser.addargument(_name or flags…[, action][, nargs][, const][, default][, type][, choices][, required][, help][, metavar][, dest])
定义单个的命令行参数应当如何解析。每个形参都在下面有它自己更多的描述，长话短说有：
- name or flags - 一个命名或者一个选项字符串的列表，例如 foo 或 -f, —foo。
- action - 当参数在命令行中出现时使用的动作基本类型。
- nargs - 命令行参数应当消耗的数目。
- const - 被一些 action 和 nargs 选择所需求的常数。
- default - 当参数未在命令行中出现时使用的值。
- type - 命令行参数应当被转换成的类型。
- choices - 可用的参数的容器。
- required - 此命令行选项是否可省略（仅选项可用）。
- help - 一个此选项作用的简单描述。
- metavar - 在使用方法消息中使用的参数值示例。
- dest - 被添加到 parse_args() 所返回对象上的属性名。

以下部分描述这些参数如何使用。

name or flags

add_argument() 方法必须知道它是否是一个选项，例如 -f 或 —foo，或是一个位置参数，例如一组文件名。第一个传递给 add_argument() 的参数必须是一系列 flags 或者是一个简单的参数名。例如，可以选项可以被这样创建:

>>> 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 命名参数指定的值。 'store_const' 动作通常用在选项中来指定一些标志。例如:

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

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

Note, the default will be None unless explicitly set to 0.

'help' - 打印所有当前解析器中的选项和参数的完整帮助信息，然后退出。默认情况下，一个 help 动作会被自动加入解析器。关于输出是如何创建的，参与 ArgumentParser。
'version' - 期望有一个 version= 命名参数在 add_argument() 调用中，并打印版本信息并在调用后退出:

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

您还可以通过传递 Action 子类或实现相同接口的其他对象来指定任意操作。建议的方法是扩展 Action，覆盖 call 方法和可选的 init 方法。

一个自定义动作的例子:

>>> class FooAction(argparse.Action):
...     def __init__(self, option_strings, dest, nargs=None, **kwargs):
...         if nargs is not None:
...             raise ValueError("nargs not allowed")
...         super(FooAction, self).__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='' 来实现多个位置参数通常没有意义，但是多个选项是可能的。例如:

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

argarse.REMAINDER。所有剩余的命令行参数被聚集到一个列表中。这通常在从一个命令行功能传递参数到另一个命令行功能中时有用:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo')
>>> parser.add_argument('command')
>>> parser.add_argument('args', nargs=argparse.REMAINDER)
>>> print(parser.parse_args('--foo B cmd --arg1 XX ZZ'.split()))
Namespace(args=['--arg1', 'XX', 'ZZ'], command='cmd', foo='B')

如果不提供 nargs 命名参数，则消耗参数的数目将被 action 决定。通常这意味着单一项目（非列表）消耗单一命令行参数。

const

add_argument() 的const 参数用于保存不从命令行中读取但被各种 ArgumentParser 动作需求的常数值。最常用的两例为：

当 add_argument() 通过 action='store_const' 或 action='append_const 调用时。这些动作将 const 值添加到 parse_args() 返回的对象的属性中。在 action 的描述中查看案例。
当 add_argument() 通过选项（例如 -f 或 —foo）调用并且 nargs='?' 时。这会创建一个可以跟随零个或一个命令行参数的选项。当解析命令行时，如果选项后没有参数，则将用 const 代替。在 nargs 描述中查看案例。

对 'store_const' 和 'append_const' 动作， const 命名参数必须给出。对其他动作，默认为 None。

默认值

所有选项和一些位置参数可能在命令行中被忽略。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 值是一个字符串，解析器解析此值就像一个命令行参数。特别是，在将属性设置在 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 — 类型

默认情况下，ArgumentParser 对象将命令行参数当作简单字符串读入。然而，命令行字符串经常需要被当作其它的类型，比如 float 或者 int。add_argument() 的 type 关键词参数允许任何的类型检查和类型转换。一般的内建类型和函数可以直接被 type 参数使用。

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', type=int)
>>> parser.add_argument('bar', type=open)
>>> parser.parse_args('2 temp.txt'.split())
Namespace(bar=<_io.TextIOWrapper name='temp.txt' encoding='UTF-8'>, foo=2)

当 type 参数被应用到默认参数时，请参考 default 参数的部分。

To ease the use of various types of files, the argparse module provides thefactory FileType which takes the mode=, bufsize=, encoding= anderrors= arguments of the open() function. For example,FileType('w') can be used to create a writable file:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('bar', type=argparse.FileType('w'))
>>> parser.parse_args(['out.txt'])
Namespace(bar=<_io.TextIOWrapper name='out.txt' encoding='UTF-8'>)

type= can take any callable that takes a single string argument and returnsthe converted value:

>>> def perfect_square(string):
...     value = int(string)
...     sqrt = math.sqrt(value)
...     if sqrt != int(sqrt):
...         msg = "%r is not a perfect square" % string
...         raise argparse.ArgumentTypeError(msg)
...     return value
...
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', type=perfect_square)
>>> parser.parse_args(['9'])
Namespace(foo=9)
>>> parser.parse_args(['7'])
usage: PROG [-h] foo
PROG: error: argument foo: '7' is not a perfect square

choices 关键词参数可能会使类型检查者更方便的检查一个范围的值。

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', type=int, choices=range(5, 10))
>>> parser.parse_args(['7'])
Namespace(foo=7)
>>> parser.parse_args(['11'])
usage: PROG [-h] {5,6,7,8,9}
PROG: error: argument foo: invalid choice: 11 (choose from 5, 6, 7, 8, 9)

详情请查阅 choices 段落。

choices

Some command-line arguments should be selected from a restricted set of values.These can be handled by passing a container object as the choices keywordargument to add_argument(). When the command line isparsed, argument values will be checked, and an error message will be displayedif the argument was not one of the acceptable values:

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

Note that inclusion in the choices container is checked after any typeconversions have been performed, so the type of the objects in the _choices_container should match the type specified:

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

Any object that supports the in operator can be passed as the _choices_value, so dict objects, set objects, custom containers,etc. are all supported.

required

In general, the argparse module assumes that flags like -f and —barindicate optional arguments, which can always be omitted at the command line.To make an option required, True can be specified for the required=keyword argument to add_argument():

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', required=True)
>>> parser.parse_args(['--foo', 'BAR'])
Namespace(foo='BAR')
>>> parser.parse_args([])
usage: argparse.py [-h] [--foo FOO]
argparse.py: error: option --foo is required

As the example shows, if an option is marked as required,parse_args() will report an error if that option is notpresent at the command line.

注解

Required options are generally considered bad form because users expectoptions to be optional, and thus they should be avoided when possible.

help

The help value is a string containing a brief description of the argument.When a user requests help (usually by using -h or —help at thecommand line), these help descriptions will be displayed with eachargument:

>>> 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
 
optional arguments:
 -h, --help  show this help message and exit
 --foo   foo the bars before frobbling

The help strings can include various format specifiers to avoid repetitionof things like the program name or the argument default. The availablespecifiers include the program name, %(prog)s and most keyword arguments toadd_argument(), e.g. %(default)s, %(type)s, etc.:

>>> 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)
 
optional arguments:
 -h, --help  show this help message and exit

As the help string supports %-formatting, if you want a literal % to appearin the help string, you must escape it as %%.

argparse supports silencing the help entry for certain options, bysetting the help value to argparse.SUPPRESS:

>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('--foo', help=argparse.SUPPRESS)
>>> parser.print_help()
usage: frobble [-h]
 
optional arguments:
  -h, --help  show this help message and exit

metavar

When ArgumentParser generates help messages, it needs some way to referto each expected argument. By default, ArgumentParser objects use the destvalue as the "name" of each object. By default, for positional argumentactions, the dest value is used directly, and for optional argument actions,the dest value is uppercased. So, a single positional argument withdest='bar' will be referred to as bar. A singleoptional argument —foo that should be followed by a single command-line argumentwill be referred to as FOO. An example:

>>> 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
 
optional arguments:
 -h, --help  show this help message and exit
 --foo FOO

An alternative name can be specified with 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
 
optional arguments:
 -h, --help  show this help message and exit
 --foo YYY

Note that metavar only changes the displayed name - the name of theattribute on the parse_args() object is still determinedby the dest value.

Different values of nargs may cause the metavar to be used multiple times.Providing a tuple to metavar specifies a different display for each of thearguments:

>>> 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]
 
optional arguments:
 -h, --help     show this help message and exit
 -x X X
 --foo bar baz

dest

Most ArgumentParser actions add some value as an attribute of theobject returned by parse_args(). The name of thisattribute is determined by the dest keyword argument ofadd_argument(). For positional argument actions,dest is normally supplied as the first argument toadd_argument():

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

For optional argument actions, the value of dest is normally inferred fromthe option strings. ArgumentParser generates the value of dest bytaking the first long option string and stripping away the initial —string. If no long option strings were supplied, dest will be derived fromthe first short option string by stripping the initial - character. Anyinternal - characters will be converted to _ characters to make surethe string is a valid attribute name. The examples below illustrate thisbehavior:

>>> 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 allows a custom attribute name to be provided:

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

Action classes

Action classes implement the Action API, a callable which returns a callablewhich processes arguments from the command-line. Any object which followsthis API may be passed as the action parameter toadd_argument().

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

Action objects are used by an ArgumentParser to represent the informationneeded to parse a single argument from one or more strings from thecommand line. The Action class must accept the two positional argumentsplus any keyword arguments passed to ArgumentParser.add_argument()except for the action itself.

Instances of Action (or return value of any callable to the actionparameter) should have attributes "dest", "optionstrings", "default", "type","required", "help", etc. defined. The easiest way to ensure these attributesare defined is to call Action._init.

Action instances should be callable, so subclasses must override thecall method, which should accept four parameters:

parser - The ArgumentParser object which contains this action.
namespace - The Namespace object that will be returned byparse_args(). Most actions add an attribute to thisobject using setattr().
values - The associated command-line arguments, with any type conversionsapplied. Type conversions are specified with the type keyword argument toadd_argument().
option_string - The option string that was used to invoke this action.The option_string argument is optional, and will be absent if the actionis associated with a positional argument.

The call method may perform arbitrary actions, but will typically setattributes on the namespace based on dest and values.

parse_args() 方法

ArgumentParser.parseargs(_args=None, namespace=None)
Convert argument strings to objects and assign them as attributes of thenamespace. Return the populated namespace.

Previous calls to add_argument() determine exactly what objects arecreated and how they are assigned. See the documentation foradd_argument() for details.

args - List of strings to parse. The default is taken fromsys.argv.
namespace - An object to take the attributes. The default is a new emptyNamespace object.

Option value syntax

The parse_args() method supports several ways ofspecifying the value of an option (if it takes one). In the simplest case, theoption and its value are passed as two separate arguments:

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

For long options (options with names longer than a single character), the optionand value can also be passed as a single command-line argument, using = toseparate them:

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

For short options (options only one character long), the option and its valuecan be concatenated:

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

Several short options can be joined together, using only a single - prefix,as long as only the last option (or none of them) requires a value:

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

无效的参数

While parsing the command line, parse_args() checks for avariety of errors, including ambiguous options, invalid types, invalid options,wrong number of positional arguments, etc. When it encounters such an error,it exits and prints the error along with a usage message:

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

包含 - 的参数

The parse_args() method attempts to give errors wheneverthe user has clearly made a mistake, but some situations are inherentlyambiguous. For example, the command-line argument -1 could either be anattempt to specify an option or an attempt to provide a positional argument.The parse_args() method is cautious here: positionalarguments may only begin with - if they look like negative numbers andthere are no options in the parser that look like negative numbers:

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

If you have positional arguments that must begin with - and don't looklike negative numbers, you can insert the pseudo-argument '—' which tellsparse_args() that everything after that is a positionalargument:

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

参数缩写（前缀匹配）

The parse_args() method by defaultallows long options to be abbreviated to a prefix, if the abbreviation isunambiguous (the prefix matches a unique option):

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

An error is produced for arguments that could produce more than one options.This feature can be disabled by setting allow_abbrev to False.

Beyond sys.argv

Sometimes it may be useful to have an ArgumentParser parse arguments other than thoseof sys.argv. This can be accomplished by passing a list of strings toparse_args(). This is useful for testing at theinteractive prompt:

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

命名空间对象

class argparse.Namespace
Simple class used by default by parse_args() to createan object holding attributes and return it.

This class is deliberately simple, just an object subclass with areadable string representation. If you prefer to have dict-like view of theattributes, you can use the standard Python idiom, vars():

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

It may also be useful to have an ArgumentParser assign attributes to analready existing object, rather than a new Namespace object. This canbe achieved by specifying the namespace= keyword argument:

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

其它实用工具

子命令

ArgumentParser.addsubparsers([_title][, description][, prog][, parser_class][, action][, option_string][, dest][, required][, help][, metavar])
Many programs split up their functionality into a number of sub-commands,for example, the svn program can invoke sub-commands like svncheckout, svn update, and svn commit. Splitting up functionalitythis way can be a particularly good idea when a program performs severaldifferent functions which require different kinds of command-line arguments.ArgumentParser supports the creation of such sub-commands with theadd_subparsers() method. The add_subparsers() method is normallycalled with no arguments and returns a special action object. This objecthas a single method, add_parser(), which takes acommand name and any ArgumentParser constructor arguments, andreturns an ArgumentParser object that can be modified as usual.

形参的描述

title - title for the sub-parser group in help output; by default"subcommands" if description is provided, otherwise uses title forpositional arguments
description - description for the sub-parser group in help output, bydefault None
prog - usage information that will be displayed with sub-command help,by default the name of the program and any positional arguments before thesubparser argument
parser_class - class which will be used to create sub-parser instances, bydefault the class of the current parser (e.g. ArgumentParser)
action - the basic type of action to be taken when this argument isencountered at the command line
dest - name of the attribute under which sub-command name will bestored; by default None and no value is stored
required - Whether or not a subcommand must be provided, by defaultFalse (added in 3.7)
help - help for sub-parser group in help output, by default None
metavar - string presenting available sub-commands in help; by default itis None and presents sub-commands in form {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)

Note that the object returned by parse_args() will only containattributes for the main parser and the subparser that was selected by thecommand line (and not any other subparsers). So in the example above, whenthe a command is specified, only the foo and bar attributes arepresent, and when the b command is specified, only the foo andbaz attributes are present.

Similarly, when a help message is requested from a subparser, only the helpfor that particular parser will be printed. The help message will notinclude parent parser or sibling parser messages. (A help message for eachsubparser command, however, can be given by supplying the help= argumentto add_parser() as above.)

>>> parser.parse_args(['--help'])
usage: PROG [-h] [--foo] {a,b} ...
 
positional arguments:
  {a,b}   sub-command help
    a     a help
    b     b help
 
optional arguments:
  -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
 
optional arguments:
  -h, --help  show this help message and exit
 
>>> parser.parse_args(['b', '--help'])
usage: PROG b [-h] [--baz {X,Y,Z}]
 
optional arguments:
  -h, --help     show this help message and exit
  --baz {X,Y,Z}  baz help

The add_subparsers() method also supports title and descriptionkeyword arguments. When either is present, the subparser's commands willappear in their own group in the help output. For example:

>>> 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} ...
 
optional arguments:
  -h, --help  show this help message and exit
 
subcommands:
  valid subcommands
 
  {foo,bar}   additional help

Furthermore, add_parser supports an additional aliases argument,which allows multiple strings to refer to the same subparser. This example,like svn, aliases co as a shorthand for 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')

One particularly effective way of handling sub-commands is to combine the useof the add_subparsers() method with calls to set_defaults() sothat each subparser knows which Python function it should execute. Forexample:

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

This way, you can let parse_args() do the job of calling theappropriate function after argument parsing is complete. Associatingfunctions with actions like this is typically the easiest way to handle thedifferent actions for each of your subparsers. However, if it is necessaryto check the name of the subparser that was invoked, the dest keywordargument to the add_subparsers() call will work:

>>> 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 版更改: New required keyword argument.

FileType 对象

class argparse.FileType(mode='r', bufsize=-1, encoding=None, errors=None)
The FileType factory creates objects that can be passed to the typeargument of ArgumentParser.add_argument(). Arguments that haveFileType objects as their type will open command-line arguments asfiles with the requested modes, buffer sizes, encodings and error handling(see the open() function for more details):

>>> 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 objects understand the pseudo-argument '-' and automaticallyconvert this into sys.stdin for readable FileType objects andsys.stdout for writable FileType objects:

>>> 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.addargument_group(_title=None, description=None)
By default, ArgumentParser groups command-line arguments into"positional arguments" and "optional arguments" when displaying helpmessages. When there is a better conceptual grouping of arguments than thisdefault one, appropriate groups can be created using theadd_argument_group() method:

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

The add_argument_group() method returns an argument group object whichhas an add_argument() method just like a regularArgumentParser. When an argument is added to the group, the parsertreats it just like a normal argument, but displays the argument in aseparate group for help messages. The add_argument_group() methodaccepts title and description arguments which can be used tocustomize this display:

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

Note that any arguments not in your user-defined groups will end up backin the usual "positional arguments" and "optional arguments" sections.

Mutual exclusion

ArgumentParser.addmutually_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 defaults

ArgumentParser.setdefaults(**kwargs_)
Most of the time, the attributes of the object returned by parse_args()will be fully determined by inspecting the command-line arguments and the argumentactions. set_defaults() allows some additionalattributes that are determined without any inspection of the command line tobe added:

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

Note that parser-level defaults always override argument-level defaults:

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

Parser-level defaults can be particularly useful when working with multipleparsers. See the add_subparsers() method for anexample of this type.

ArgumentParser.getdefault(_dest)
Get the default value for a namespace attribute, as set by eitheradd_argument() or byset_defaults():

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

打印帮助

In most typical applications, parse_args() will takecare of formatting and printing any usage or error messages. However, severalformatting methods are available:

ArgumentParser.printusage(_file=None)
Print a brief description of how the ArgumentParser should beinvoked on the command line. If file is None, sys.stdout isassumed.

ArgumentParser.printhelp(_file=None)
Print a help message, including the program usage and information about thearguments registered with the ArgumentParser. If file isNone, sys.stdout is assumed.

There are also variants of these methods that simply return a string instead ofprinting it:

ArgumentParser.format_usage()
Return a string containing a brief description of how theArgumentParser should be invoked on the command line.

ArgumentParser.format_help()
Return a string containing a help message, including the program usage andinformation about the arguments registered with the ArgumentParser.

Partial parsing

ArgumentParser.parseknown_args(_args=None, namespace=None)

Sometimes a script may only parse a few of the command-line arguments, passingthe remaining arguments on to another script or program. In these cases, theparse_known_args() method can be useful. It works much likeparse_args() except that it does not produce an error whenextra arguments are present. Instead, it returns a two item tuple containingthe populated namespace and the list of remaining argument strings.

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

警告

Prefix matching rules apply toparse_known_args(). The parser may consume an option even if it's justa prefix of one of its known options, instead of leaving it in the remainingarguments list.

自定义文件解析

ArgumentParser.convertarg_line_to_args(_arg_line)
Arguments that are read from a file (see the _fromfile_prefix_chars_keyword argument to the ArgumentParser constructor) are read oneargument per line. convert_arg_line_to_args() can be overridden forfancier reading.

This method takes a single argument arg_line which is a string read fromthe argument file. It returns a list of arguments parsed from this string.The method is called once per line read from the argument file, in order.

A useful override of this method is one that treats each space-separated wordas an argument. The following example demonstrates how to do this:

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

退出方法

ArgumentParser.exit(status=0, message=None)
This method terminates the program, exiting with the specified status_and, if given, it prints a _message before that.

ArgumentParser.error(message)
This method prints a usage message including the message to thestandard error and terminates the program with a status code of 2.

Intermixed parsing

ArgumentParser.parseintermixed_args(_args=None, namespace=None)

ArgumentParser.parseknown_intermixed_args(_args=None, namespace=None)

A number of Unix commands allow the user to intermix optional arguments withpositional arguments. The parse_intermixed_args()and parse_known_intermixed_args() methodssupport this parsing style.

These parsers do not support all the argparse features, and will raiseexceptions if unsupported features are used. In particular, subparsers,argparse.REMAINDER, and mutually exclusive groups that include bothoptionals and positionals are not supported.

The following example shows the difference betweenparse_known_args() andparse_intermixed_args(): the former returns ['2','3'] as unparsed arguments, while the latter collects all the positionalsinto 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() returns a two item tuplecontaining the populated namespace and the list of remaining argument strings.parse_intermixed_args() raises an error if there are anyremaining unparsed argument strings.

3.7 新版功能.

升级 optparse 代码

Originally, the argparse module had attempted to maintain compatibilitywith optparse. However, optparse was difficult to extendtransparently, particularly with the changes required to support the newnargs= specifiers and better usage messages. When most everything inoptparse had either been copy-pasted over or monkey-patched, it nolonger seemed practical to try to maintain the backwards compatibility.

The argparse module improves on the standard library optparsemodule in a number of ways including:

处理位置参数。
支持子命令。
Allowing alternative option prefixes like + and /.
Handling zero-or-more and one-or-more style arguments.
Producing more informative usage messages.
Providing a much simpler interface for custom type and action.

A partial upgrade path from optparse to argparse:

Replace all optparse.OptionParser.add_option() calls withArgumentParser.add_argument() calls.
Replace (options, args) = parser.parse_args() with args =parser.parse_args() and add additional ArgumentParser.add_argument()calls for the positional arguments. Keep in mind that what was previouslycalled options, now in the argparse context is called args.
Replace optparse.OptionParser.disable_interspersed_args()by using parse_intermixed_args() instead ofparse_args().
Replace callback actions and the callback_* keyword arguments withtype or action arguments.
Replace string names for type keyword arguments with the correspondingtype objects (e.g. int, float, complex, etc).
Replace optparse.Values with Namespace andoptparse.OptionError and optparse.OptionValueError withArgumentError.
Replace strings with implicit arguments such as %default or %prog withthe standard Python syntax to use dictionaries to format strings, that is,%(default)s and %(prog)s.
Replace the OptionParser constructor version argument with a call toparser.add_argument('—version', action='version', version='<the version>').