Skip to main content

16.4. argparse —用于命令行选项,参数和子命令的解析器

3.2 新版功能.

源代码: Lib/argparse.py


argparse 模块使编写用户友好的命令行界面变得容易。程序定义了它需要什么参数,argparse 会找出如何解析 sys.argv 中的参数。 argparse 模块还自动生成帮助和使用消息,并在用户给程序无效参数时发出错误。

16.4.1. 例

下面的代码是一个Python程序,它接受一个整数列表,并产生sum或max:

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'

以下部分将引导您完成此示例。

16.4.1.1. 创建解析器

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

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

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

16.4.1.2. 添加参数

通过调用 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() 将返回具有两个属性(integersaccumulate)的对象。 integers 属性将是一个或多个int的列表,并且 accumulate 属性将是 sum() 函数(如果在命令行中指定了 --sum)或 max() 函数(如果没有指定)。

16.4.1.3. 解析参数

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 的命令行参数。

16.4.2. 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 - 在参数help之前显示的文本(默认值:none)

  • epilog - 在参数help后显示的文本(默认值:none)

  • 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 参数。

以下部分介绍如何使用这些方法。

16.4.2.1. 程序

默认情况下,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

16.4.2.2. 用法

默认情况下,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 格式说明符可用于填写使用消息中的程序名称。

16.4.2.3. 描述

大多数对 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

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

16.4.2.4. 结语

一些程序喜欢在参数描述后显示程序的附加描述。这样的文本可以使用 ArgumentParserepilog= 参数来指定:

>>> 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= 文本默认为行包装,但是可以使用 ArgumentParserformatter_class 参数来调整此行为。

16.4.2.5. 父母

有时,几个解析器共享一组公共参数。不是重复这些参数的定义,而是可以使用具有所有共享参数并传递给 ArgumentParserparents= 参数的单个解析器。 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= 传递之前,必须完全初始化解析器。如果您在子解析器之后更改父解析器,那么这些更改将不会反映在子代中。

16.4.2.6. formatter_class

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

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

RawDescriptionHelpFormatterRawTextHelpFormatter 可以更好地控制文本描述的显示方式。默认情况下,ArgumentParser 对象在命令行帮助消息中换行 descriptionepilog 文本:

>>> 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= 传递表示 descriptionepilog 已经被正确格式化,并且不应该被线包裹:

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

16.4.2.7. 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 选项。

16.4.2.8. 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,意味着参数将不会被视为文件引用。

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

16.4.2.10. allow_abbrev

通常,当您将参数列表传递给 ArgumentParserparse_args() 方法时,它会使用长选项的 识别缩写

可以通过将 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 新版功能.

16.4.2.11. 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' 提供给 ArgumentParserconflict_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 选项字符串。

16.4.2.12. 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]

optional arguments:
 -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]

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

16.4.3. add_argument()方法

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

定义应如何解析单个命令行参数。每个参数都有自己更详细的描述如下,但总之他们是:

  • name or flags - 名称或选项字符串列表,例如 foo-f, --foo

  • action - 在命令行遇到此参数时要执行的操作的基本类型。

  • nargs - 应该使用的命令行参数的数量。

  • const - 某些 actionnargs 选择所需的常量值。

  • default - 如果参数在命令行中不存在,则生成的值。

  • type - 应转换命令行参数的类型。

  • choices - 参数的允许值的容器。

  • required - 是否可以省略命令行选项(仅可选)。

  • help - 参数的作用的简要描述。

  • metavar - 使用消息中参数的名称。

  • dest - 要添加到 parse_args() 返回的对象的属性的名称。

以下部分介绍如何使用这些方法。

16.4.3.1. 名称或标志

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: too few arguments

16.4.3.2. 行动

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''store_false' - 这些是用于分别存储值 TrueFalse'store_const' 的特殊情况。此外,它们分别创建 FalseTrue 的默认值。例如:

    >>> 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')
    >>> parser.parse_args(['-vvv'])
    Namespace(verbose=3)
    
  • '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
    

您还可以通过传递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

16.4.3.3. 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: too few arguments
    
  • argparse.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 确定。通常这意味着将消耗单个命令行参数,并且将生成单个项目(而不是列表)。

16.4.3.4. const

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

  • 当使用 action='store_const'action='append_const' 调用 add_argument() 时。这些操作将 const 值添加到 parse_args() 返回的对象的某个属性。有关示例,请参阅 action 说明。

  • 当使用选项字符串(如 -f--foo)和 nargs='?' 调用 add_argument() 时。这将创建一个可选参数,后跟零或一个命令行参数。当解析命令行时,如果遇到后面没有命令行参数的选项字符串,将改为使用 const 的值。有关示例,请参阅 nargs 说明。

使用 'store_const''append_const' 操作,必须给出 const 关键字参数。对于其他操作,它默认为 None

16.4.3.5. 默认

所有可选参数和一些位置参数可以在命令行中省略。 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')

16.4.3.6. 类型

默认情况下,ArgumentParser 对象以简单的字符串读取命令行参数。然而,很多时候命令行字符串应该解释为另一种类型,如 floatintadd_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 关键字参数一节。

为了方便使用各种类型的文件,argparse模块提供了工厂FileType,它接受 open() 函数的 mode=bufsize=encoding=errors= 参数。例如,FileType('w') 可用于创建可写文件:

>>> 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= 可以接受任何可调用,它接受单个字符串参数并返回转换的值:

>>> 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 部分。

16.4.3.7. 选择

一些命令行参数应从有限的值集中选择。这些可以通过将容器对象作为 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')

注意,在执行任何 type 转换之后检查包括在 choices 容器中,因此 choices 容器中的对象的类型应该与指定的 type 匹配:

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

支持 in 运算符的任何对象都可以作为 choices 值传递,因此,支持 dict 对象,set 对象,自定义容器等。

16.4.3.8. 需要

一般来说,argparse 模块假定像 -f--bar 这样的标志指示 optional 参数,它们在命令行中总是可以省略。要选择 required,可以为 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: argparse.py [-h] [--foo FOO]
argparse.py: error: option --foo is required

如示例所示,如果某个选项被标记为 required,如果该选项在命令行中不存在,parse_args() 将报告错误。

注解

所需的选项通常被认为是不好的形式,因为用户期望 optionsoptional,因此在可能的时候应该避免它们。

16.4.3.9. 帮帮我

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

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

help 字符串可以包括各种格式说明符,以避免重复诸如程序名称或参数 default 之类的事情。可用的说明符包括程序名称,%(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)

optional arguments:
 -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]

optional arguments:
  -h, --help  show this help message and exit

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

optional arguments:
 -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

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

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

不同的 nargs 值可能导致元代码被多次使用。向 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]

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

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

16.4.3.12. 动作类

Action类实现了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)

Action对象由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 参数是可选的,如果操作与位置参数相关联,则 option_string 参数将不存在。

__call__ 方法可以执行任意动作,但是通常将基于 destvaluesnamespace 上设置属性。

16.4.4. parse_args()方法

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

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

先前对 add_argument() 的调用确定创建什么对象以及如何分配它们。有关详细信息,请参阅 add_argument() 的文档。

默认情况下,参数字符串取自 sys.argv,并为属性创建一个新的空 Namespace 对象。

16.4.4.1. 选项值语法

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

16.4.4.2. 参数无效

在解析命令行时,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

16.4.4.3. 包含 - 的参数

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)

16.4.4.4. 参数缩写(前缀匹配)

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 来禁用此功能。

16.4.4.5. 超越 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])

16.4.4.6. Namespace对象

class argparse.Namespace

默认情况下由 parse_args() 使用的简单类创建一个保存属性并返回它的对象。

这个类是故意简单的,只是一个具有可读字符串表示的 object 子类。如果你喜欢有属性的dict类似的视图,你可以使用标准的Python成语,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'

16.4.5. 其他公用事业

16.4.5.1. 子命令

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

许多程序将其功能分为多个子命令,例如,svn 程序可以调用子命令,如 svn checkoutsvn updatesvn commit。当程序执行需要不同类型的命令行参数的几个不同的函数时,这种方式分裂功能是一个特别好的主意。 ArgumentParser 支持使用 add_subparsers() 方法创建这样的子命令。 add_subparsers() 方法通常在没有参数的情况下调用,并返回特殊的操作对象。这个对象有一个方法,add_parser(),它接受一个命令名和任何 ArgumentParser 构造函数参数,并返回一个 ArgumentParser 对象,可以像往常一样修改。

参数说明:

  • title - 帮助输出中的子解析器组的标题;如果提供了描述,默认为“子命令”,否则使用位置参数的标题

  • description - 帮助输出中的子解析器组的描述,默认为 None

  • prog - 将使用sub-command帮助显示的使用信息,默认情况下程序的名称和在subparser参数之前的任何位置参数

  • parser_class - 将用于创建子解析器实例的类,默认情况下当前解析器的类(例如ArgumentParser)

  • action - 在命令行遇到此参数时要执行的基本操作类型

  • dest - 将存储子命令名称的属性的名称;默认为 None,不存储值

  • help - 帮助子解析器组在帮助输出中,默认为 None

  • metavar - 在help中显示可用子命令的字符串;默认情况下它是 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 命令时,仅存在 foobar 属性,并且当指定 b 命令时,仅存在 foobaz 属性。

类似地,当从子分析器请求帮助消息时,将仅打印用于该特定解析器的帮助。帮助消息将不包括父解析器或同级解析器消息。 (但是,可以通过如上所述向 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

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

add_subparsers() 方法还支持 titledescription 关键字参数。当其中一个存在时,子程序的命令将出现在帮助输出中它们自己的组中。例如:

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

此外,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()
>>>
>>> # 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')

16.4.5.2. FileType对象

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

FileType 工厂创建可以传递到 ArgumentParser.add_argument() 的类型参数的对象。具有 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对象理解伪参数 '-',并自动将其转换为 sys.stdin 用于可读的 FileType 对象,sys.stdout 用于可写入的 FileType 对象:

>>> 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 新版功能: encodingserrors 关键字参数。

16.4.5.3. 参数组

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() 方法接受 titledescription 参数,可用于自定义此显示:

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

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

16.4.5.4. 互斥

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()titledescription 参数。

16.4.5.5. 解析器默认值

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'

16.4.5.6. 打印帮助

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

ArgumentParser.print_usage(file=None)

打印如何在命令行上调用 ArgumentParser 的简要说明。如果 fileNone,则假定 sys.stdout

ArgumentParser.print_help(file=None)

打印帮助消息,包括程序使用情况和有关在 ArgumentParser 注册的参数的信息。如果 fileNone,则假定 sys.stdout

还有这些方法的变体,它们简单地返回一个字符串而不是打印它:

ArgumentParser.format_usage()

返回一个包含如何在命令行上调用 ArgumentParser 的简要描述的字符串。

ArgumentParser.format_help()

返回包含帮助消息的字符串,包括程序用法和有关在 ArgumentParser 注册的参数的信息。

16.4.5.7. 部分解析

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()。解析器可能会消耗一个选项,即使它只是一个已知选项的前缀,而不是留在剩余的参数列表中。

16.4.5.8. 自定义文件解析

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

16.4.5.9. 退出方法

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

此方法终止程序,退出指定的 status,如果给定,它打印之前的 message

ArgumentParser.error(message)

该方法将包括 message 的使用消息打印到标准错误,并以状态代码2终止程序。

16.4.6. 升级optparse代码

最初,argparse 模块试图保持与 optparse 的兼容性。然而,optparse 难以透明地扩展,特别是在需要改变以支持新的 nargs= 说明符和更好的使用消息时。当 optparse 中的大多数东西都被复制粘贴或猴子修补时,尝试保持向后兼容性似乎不现实。

argparse 模块在标准库 optparse 模块上以多种方式改进,包括:

  • 处理位置参数。

  • 支持子命令。

  • 允许替代选项前缀(如 +/)。

  • 处理零或多个和一个或多个样式参数。

  • 生成更多的信息使用消息。

  • 为自定义 typeaction 提供一个更简单的界面。

optparseargparse 的部分升级路径:

  • ArgumentParser.add_argument() 呼叫替换所有 optparse.OptionParser.add_option() 呼叫。

  • args = parser.parse_args() 替换 (options, args) = parser.parse_args(),并为位置参数添加额外的 ArgumentParser.add_argument() 调用。记住,以前称为 options,现在在 argparse 上下文中被称为 args

  • typeaction 参数替换回调操作和 callback_* 关键字参数。

  • 用相应的类型对象替换 type 关键字参数的字符串名称(例如int,float,complex等)。

  • Namespace 替换 optparse.Values,用 ArgumentError 替换 optparse.OptionErroroptparse.OptionValueError

  • 使用标准Python语法替换带有隐式参数(如 %default%prog)的字符串,以使用字典格式化字符串,即 %(default)s%(prog)s

  • 使用对 parser.add_argument('--version', action='version', version='<the version>') 的调用替换OptionParser构造函数 version 参数。