argparse ---用于命令行选项、参数和子命令的分析器

3.2 新版功能.

源代码: Lib/argparse.py


这个 argparse 模块使编写用户友好的命令行界面变得容易。程序定义了它需要的参数,以及 argparse 将找出如何从 sys.argv . 这个 argparse 模块还自动生成帮助和用法消息,并在用户向程序提供无效参数时发出错误。

例子

下面的代码是一个python程序,它接受一个整数列表并生成和或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

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

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

$ python prog.py 1 2 3 4
4

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

如果传入的参数无效,将发出错误:

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

下面的部分将引导您完成这个示例。

创建分析器

使用的第一步 argparse 正在创建一个 ArgumentParser 对象:

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

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

添加参数

灌装 ArgumentParser 有关程序参数的信息通过调用 add_argument() 方法。一般来说,这些调用告诉我们 ArgumentParser 如何在命令行上获取字符串并将其转换为对象。此信息在以下情况下存储和使用: 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() 如果不是的话也可以。

正在分析参数

ArgumentParser 通过分析参数 parse_args() 方法。这将检查命令行,将每个参数转换为适当的类型,然后调用适当的操作。在大多数情况下,这意味着 Namespace 将根据从命令行中分析的属性生成对象::

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

在剧本中, parse_args() 通常在没有参数的情况下调用,并且 ArgumentParser 将自动确定命令行参数 sys.argv .

ArgumentParser对象

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

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

  • prog -程序的名称(默认: sys.argv[0]

  • usage -描述程序用法的字符串(默认值:由添加到分析器的参数生成)

  • description -要在参数帮助前显示的文本(默认值:无)

  • epilog -参数帮助后显示的文本(默认值:无)

  • parents -一览表 ArgumentParser 应包含其参数的对象

  • formatter_class -自定义帮助输出的类

  • prefix_chars -为可选参数加前缀的字符集(默认值:“-”)

  • fromfile_prefix_chars -为文件添加前缀的字符集,从中读取附加参数(默认: None

  • argument_default -参数的全局默认值(默认值: None

  • conflict_handler -解决冲突期权的策略(通常不必要)

  • add_help 添加一个 -h/--help 解析器选项(默认: True

  • allow_abbrev -如果缩写词不含糊,则允许缩写长选项。(默认: True

  • exit_on_error -确定发生错误时ArgumentParser是否与错误信息一起退出。(默认值: True

在 3.5 版更改: allow_abbrev 已添加参数。

在 3.8 版更改: 在以前的版本中, allow_abbrev 还禁用短标志分组,如 -vv 意思是说 -v -v .

在 3.9 版更改: exit_on_error 已添加参数。

以下各节描述了如何使用这些方法。

掠夺

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

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

将显示此程序的帮助 myprogram.py 作为程序名(无论从何处调用程序):

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

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

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

要更改此默认行为,可以使用 prog= 参数 ArgumentParser ::

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

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

请注意,程序名,是否由 sys.argv[0] 或者从 prog= 参数,可用于帮助使用 %(prog)s 格式说明符。

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

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

使用

默认情况下, ArgumentParser 根据包含的参数计算用法消息::

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

positional arguments:
 bar          bar help

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

默认消息可以用 usage= 关键字参数:

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

positional arguments:
 bar          bar help

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

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

描述

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

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

A foo that bars

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

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

尾声

有些程序类似于在参数描述之后显示程序的附加描述。可以使用 epilog= 参数 ArgumentParser ::

>>> parser = argparse.ArgumentParser(
...     description='A foo that bars',
...     epilog="And that's how you'd foo a bar")
>>> parser.print_help()
usage: argparse.py [-h]

A foo that bars

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

And that's how you'd foo a bar

如同 description 参数 epilog= 文本默认为换行,但可以使用 formatter_class 参数 ArgumentParser .

父母

有时,几个解析器共享一组公共的参数。不是重复这些参数的定义,而是一个包含所有共享参数并传递给 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 .否则, ArgumentParser 将看到两个 -h/--help 选项(一个在父项中,一个在子项中)并引发错误。

注解

在将解析器传递给 parents= .如果在子解析器之后更改父解析器,那么这些更改将不会反映在子解析器中。

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

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

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

经过 RawDescriptionHelpFormatter 作为 formatter_class= 表明 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

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

RawTextHelpFormatter 维护各种帮助文本的空白,包括参数描述。但是,多个新行被替换为一行。如果要保留多个空行,请在新行之间添加空格。

ArgumentDefaultsHelpFormatter 自动向每个参数帮助消息添加有关默认值的信息::

>>> parser = argparse.ArgumentParser(
...     prog='PROG',
...     formatter_class=argparse.ArgumentDefaultsHelpFormatter)
>>> parser.add_argument('--foo', type=int, default=42, help='FOO!')
>>> parser.add_argument('bar', nargs='*', default=[1, 2, 3], help='BAR!')
>>> parser.print_help()
usage: PROG [-h] [--foo FOO] [bar ...]

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

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

MetavarTypeHelpFormatter 使用的名称 type 每个参数的参数作为其值的显示名称(而不是使用 dest 就像常规格式化程序一样)::

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

positional arguments:
  float

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

prefix_chars

大多数命令行选项将使用 - 作为前缀,例如 -f/--foo . 需要支持不同或附加前缀字符的解析器,例如,对于诸如 +f/foo ,可以使用 prefix_chars= ArgumentParser构造函数的参数::

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

这个 prefix_chars= 参数默认为 '-' . 提供一组不包括 - 将导致 -f/--foo 不允许的选项。

fromfile_prefix_chars

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

>>> with open('args.txt', 'w') 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() 或者调用给 set_defaults() 具有一组特定名称-值对的方法。但是,有时为参数指定一个解析器范围的默认值可能很有用。这可以通过 argument_default= 关键字参数 ArgumentParser .例如,全局禁止在 parse_args() 调用,我们提供 argument_default=SUPPRESS ::

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

allow_abbrev

通常,当您将参数列表传递给 parse_args() AN方法 ArgumentParserrecognizes abbreviations 有很多选择。

可以通过设置禁用此功能 allow_abbrevFalse ::

>>> 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' 可提供给 conflict_handler= 的参数 ArgumentParser ::

>>> parser = argparse.ArgumentParser(prog='PROG', conflict_handler='resolve')
>>> parser.add_argument('-f', '--foo', help='old foo help')
>>> parser.add_argument('--foo', help='new foo help')
>>> parser.print_help()
usage: PROG [-h] [-f FOO] [--foo FOO]

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

注意 ArgumentParser 对象仅在其所有选项字符串都被重写时移除操作。因此,在上面的例子中, -f/--foo 动作保留为 -f 行动,因为只有 --foo 选项字符串被重写。

add_help

默认情况下,ArgumentParser对象添加一个选项,该选项只显示分析器的帮助消息。例如,考虑一个名为 myprogram.py 包含以下代码:

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

如果 -h--help 在命令行中提供,将打印ArgumentParser帮助:

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

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

有时,禁用添加此帮助选项可能很有用。这可以通过传球来实现 False 作为 add_help= 参数 ArgumentParser ::

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

options:
 --foo FOO  foo help

帮助选项通常是 -h/--help . 例外情况是 prefix_chars= 已指定但不包括 - ,在这种情况下 -h--help 不是有效选项。在本例中,第一个字符 prefix_chars 用于为帮助选项加前缀:

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

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

exit_on_error

通常,当您向 parse_args() AN方法 ArgumentParser ,它将退出并显示错误信息。

如果用户希望手动捕获错误,可以通过设置 exit_on_errorFalse ::

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

3.9 新版功能.

add_argument()方法

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

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

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

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

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

  • const -一些 actionnargs 选择。

  • default -如果命令行中没有该参数,并且命名空间对象中没有该参数,则生成的值。

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

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

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

  • help -对参数的简要描述。

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

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

以下各节描述了如何使用这些方法。

名称或标志

这个 add_argument() 方法必须知道是否有可选参数,例如 -f--foo 或位置参数,如文件名列表。第一个参数传递给 add_argument() 因此必须是一系列标志或简单参数名。例如,可以创建如下可选参数:

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

位置参数的创建方式如下:

>>> parser.add_argument('bar')

什么时候? parse_args() 调用时,可选参数将由 - 前缀,其余参数将假定为位置::

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

行动

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' -这些是特殊情况 'store_const' 用于存储值 TrueFalse 分别。此外,它们还创建默认值 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', default=0)
    >>> parser.parse_args(['-vvv'])
    Namespace(verbose=3)
    

    注意, 违约None 除非显式设置为 0 .

  • '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
    
  • 'extend' -这将存储一个列表,并将每个参数值扩展到该列表。示例用法:

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

    3.8 新版功能.

还可以通过传递实现同一接口的操作子类或其他对象来指定任意操作。这个 BooleanOptionalAction 在中可用 argparse 并添加对布尔操作的支持,如 --foo--no-foo ::

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

建议创建自定义操作的方法是 Action ,覆盖 __call__ 方法和可选的 __init__format_usage 方法。

自定义操作的示例:

>>> class FooAction(argparse.Action):
...     def __init__(self, option_strings, dest, nargs=None, **kwargs):
...         if nargs is not None:
...             raise ValueError("nargs not allowed")
...         super(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 .

纳尔格斯

ArgumentParser对象通常将单个命令行参数与要执行的单个操作相关联。这个 nargs 关键字参数将不同数量的命令行参数与单个操作关联。支持的值包括:

  • N (整数) N 命令行中的参数将被收集到一个列表中。例如::

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

    注意 nargs=1 生成一个项目列表。这与默认情况不同,在默认情况下,项目是由其自身生成的。

  • '?' . 如果可能,将从命令行中使用一个参数,并作为单个项生成。如果不存在命令行参数,则返回 default 将生产。请注意,对于可选参数,还有一种情况——选项字符串存在,但后面没有命令行参数。在这种情况下,值来自 const 将生产。举例说明:

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

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

    >>> parser = argparse.ArgumentParser()
    >>> parser.add_argument('infile', nargs='?', type=argparse.FileType('r'),
    ...                     default=sys.stdin)
    >>> parser.add_argument('outfile', nargs='?', type=argparse.FileType('w'),
    ...                     default=sys.stdout)
    >>> parser.parse_args(['input.txt', 'output.txt'])
    Namespace(infile=<_io.TextIOWrapper name='input.txt' encoding='UTF-8'>,
              outfile=<_io.TextIOWrapper name='output.txt' encoding='UTF-8'>)
    >>> parser.parse_args([])
    Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>,
              outfile=<_io.TextIOWrapper name='<stdout>' encoding='UTF-8'>)
    
  • '*' . 所有存在的命令行参数都被收集到一个列表中。注意,通常情况下,使用多个位置参数 nargs='*' ,但有多个可选参数 nargs='*' 是可能的。例如::

    >>> parser = argparse.ArgumentParser()
    >>> parser.add_argument('--foo', nargs='*')
    >>> parser.add_argument('--bar', nargs='*')
    >>> parser.add_argument('baz', nargs='*')
    >>> parser.parse_args('a b --foo x y --bar 1 2'.split())
    Namespace(bar=['1', '2'], baz=['a', 'b'], foo=['x', 'y'])
    
  • '+' . 就像 '*' ,所有存在的命令行参数都被收集到一个列表中。此外,如果没有至少一个命令行参数,则将生成一条错误消息。例如::

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

如果 nargs 未提供关键字参数,使用的参数数由 action. 一般来说,这意味着将使用单个命令行参数并生成单个项(而不是列表)。

康斯特

这个 const 的参数 add_argument() 用于保存不从命令行中读取但在 ArgumentParser 行动。它最常见的两种用途是:

  • 什么时候? add_argument() 被调用 action='store_const'action='append_const' . 这些操作添加了 const 返回的对象属性之一的值 parse_args() . 见 action 示例说明。

  • 什么时候? add_argument() 使用选项字符串(如 -f--foonargs='?' . 这将创建一个可选参数,后面可以跟零个或一个命令行参数。在分析命令行时,如果遇到选项字符串后没有命令行参数,则 const 将被假定为。见 nargs 示例说明。

'store_const''append_const' 行动 const 必须提供关键字参数。对于其他操作,默认为 None .

违约

所有可选参数和一些位置参数都可以在命令行中省略。这个 default 的关键字参数 add_argument() ,其值默认为 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)

如果目标命名空间已经设置了属性,则操作 默认设置 不会覆盖它::

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

如果 default 值是一个字符串,解析器解析该值时将其视为命令行参数。特别是,解析器应用 type 如果提供了转换参数,则在设置 Namespace 返回值。否则,解析器将按原样使用值:

>>> 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 等于 ?* , the 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')

类型

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

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

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

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

import argparse
import pathlib

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

还可以使用用户定义的函数:

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

这个 bool() 函数不推荐用作类型转换器。它所做的只是将空字符串转换为 False 和非空字符串连接到 True 。这通常不是人们想要的。

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

例如,JSON或YAML转换具有复杂的错误情况,需要比 type 关键字。一个 JSONDecodeError 将不会被正确格式化,并且 FileNotFound 异常将根本不会被处理。

甚至 FileType 与一起使用有其局限性。 type 关键字。如果一个参数使用 FileType 然后后续参数失败,则会报告错误,但不会自动关闭文件。在这种情况下,最好等到解析器运行之后再使用 with -管理文件的语句。

对于简单地对照一组固定值进行检查的类型检查器,请考虑使用 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 已执行转换,因此 选择 容器应与 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)

任何容器都可以作为 选择 价值,因此 list 对象, set 对象和自定义容器都是受支持的。

使用 enum.Enum 不推荐使用,因为很难控制其在使用、帮助和错误消息中的外观。

格式化选项将覆盖默认选项 元数据 它通常派生自 dest 。这通常是您想要的,因为用户永远看不到 dest 参数。如果此显示不是所需的(可能是因为有很多选择),只需指定一个显式 metavar.

必修的

一般来说, argparse 模块假定标志如下 -f--bar 表明 可选择的 参数,可在命令行中忽略。做出选择 必修的True 可以为指定 required= 关键字参数 add_argument() ::

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

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

注解

所需选项通常被认为是不正确的形式,因为用户希望 option 成为 可选择的 因此,在可能的情况下,应避免使用它们。

帮助

这个 help 值是包含参数简要说明的字符串。当用户请求帮助时(通常使用 -h--help 在命令行),这些 help 描述将与每个参数一起显示::

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

positional arguments:
 bar     one of the bars to be frobbled

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

这个 help 字符串可以包含各种格式说明符,以避免重复程序名或参数等内容。 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)

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

因为帮助字符串支持%-格式,如果需要文本 % 若要显示在帮助字符串中,必须将其作为 %% .

argparse 支持通过设置 help 价值到 argparse.SUPPRESS ::

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

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

梅塔伐

什么时候? ArgumentParser 生成帮助消息,它需要某种方式来引用每个期望的参数。默认情况下,ArgumentParser对象使用 dest 值作为每个对象的“名称”。默认情况下,对于位置参数操作, dest 值直接使用,对于可选参数操作, dest 值为大写。所以,一个位置参数 dest='bar' 将被称为 bar . 单个可选参数 --foo 后面应该跟一个命令行参数 FOO .示例:

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

positional arguments:
 bar

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

可使用指定替代名称 metavar ::

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

positional arguments:
 XXX

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

注意 metavar 只改变 显示 名称-属性的名称 parse_args() 对象仍由 dest 价值。

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

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

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

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

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

对于可选参数操作,值为 dest 通常从选项字符串推断。 ArgumentParser 生成的值 dest 取第一个长选项字符串并去掉初始值 -- 字符串。如果没有提供长选项字符串, dest 将从第一个短选项字符串中提取初始值 - 性格。任何内部 - 字符将转换为 _ 字符以确保字符串是有效的属性名。下面的例子说明了这种行为:

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

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

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

动作类

action类实现action api,这是一个可调用的,它返回一个可调用的,用于处理命令行中的参数。此API后面的任何对象都可以作为 action 参数到 add_argument() .

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

ArgumentParser使用操作对象表示从命令行的一个或多个字符串分析单个参数所需的信息。action类必须接受两个位置参数加上传递给的任何关键字参数 ArgumentParser.add_argument() 除了 action 本身。

操作实例(或返回可调用到 action 参数)应定义属性“dest”、“option_strings”、“default”、“type”、“required”、“help”等。确保定义这些属性的最简单方法是调用 Action.__init__ .

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

  • parser -包含此操作的ArgumentParser对象。

  • namespace - Namespace 将由返回的对象 parse_args() . 大多数操作都使用 setattr() .

  • values -关联的命令行参数,应用了任何类型转换。类型转换是用指定的 type 关键字参数 add_argument() .

  • option_string -用于调用此操作的选项字符串。这个 option_string 参数是可选的,如果操作与位置参数关联,则该参数将不存在。

这个 __call__ 方法可以执行任意操作,但通常会在 namespace 基于 destvalues .

动作子类可以定义 format_usage 方法,该方法不接受参数并返回一个字符串,该字符串将在打印程序的用法时使用。如果没有提供这种方法,则将使用合理的默认值。

parse args()方法

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

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

以前调用 add_argument() 准确地确定创建了什么对象以及如何分配它们。参见文档 add_argument() 有关详细信息。

选项值语法

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

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x')
>>> parser.add_argument('--foo')
>>> parser.parse_args(['-x', 'X'])
Namespace(foo=None, x='X')
>>> parser.parse_args(['--foo', 'FOO'])
Namespace(foo='FOO', x=None)

对于长选项(名称长于单个字符的选项),也可以将选项和值作为单个命令行参数传递,使用 = 分开它们:

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

对于短选项(选项只有一个字符长),选项及其值可以连接:

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

几个短选项可以连接在一起,只使用一个 - 前缀,只要最后一个选项(或它们都不需要)需要一个值::

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

无效参数

分析命令行时, parse_args() 检查各种错误,包括不明确的选项、无效的类型、无效的选项、错误的位置参数数目等。当遇到此类错误时,它将退出并打印错误以及用法消息:

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

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

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

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

参数包含 -

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

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

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

>>> # no negative number options, so -1 and -5 are positional arguments
>>> parser.parse_args(['-x', '-1', '-5'])
Namespace(foo='-5', x='-1')

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

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

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

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

如果有位置参数必须以 - 不要看起来像负数,你可以插入伪参数 '--' 它告诉 parse_args() 之后的一切都是位置论证:

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

参数缩写(前缀匹配)

这个 parse_args() 方法 by default 如果缩写词不含糊(前缀与唯一选项匹配),则允许将长选项缩写为前缀:

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

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

命名空间对象

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'

其他公用事业

子命令

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

许多程序将其功能划分为若干个子命令,例如, svn 程序可以调用子命令,比如 svn checkoutsvn updatesvn commit . 当程序执行需要不同类型命令行参数的几个不同函数时,以这种方式拆分功能是一个特别好的主意。 ArgumentParser 支持使用 add_subparsers() 方法。这个 add_subparsers() 方法通常不带参数调用,并返回一个特殊的操作对象。此对象只有一个方法, add_parser() ,它采用命令名和 ArgumentParser 构造函数参数,并返回 ArgumentParser 可以像往常一样修改的对象。

参数说明:

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

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

  • prog-将在子命令帮助中显示的用法信息,默认情况下,在subparser参数之前显示程序名称和任何位置参数。

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

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

  • dest -存储子命令名的属性的名称;默认情况下 None 不存储任何值

  • required -默认情况下,是否必须提供子命令 False (在3.7中增加)

  • help -默认情况下,帮助输出中的子解析器组帮助 None

  • metavar -在帮助中显示可用子命令的字符串;默认情况下为 None 并以命令1、命令2、.形式显示子命令。

示例用法:

>>> # 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 存在属性。

同样,当从子排序器请求帮助消息时,将只打印该特定分析器的帮助。帮助消息将不包括父分析器或同级分析器消息。(但是,可以通过提供 help= 参数 add_parser() 如上所述)

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

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

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

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

positional arguments:
  bar     bar help

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

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

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

这个 add_subparsers() 方法也支持 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} ...

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

subcommands:
  valid subcommands

  {foo,bar}   additional help

此外, add_parser 支持附加的 aliases 参数,它允许多个字符串引用同一个子排序器。这个例子,比如 svn ,别名 co 作为 checkout ::

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

处理子命令的一种特别有效的方法是将 add_subparsers() 调用的方法 set_defaults() 以便每个子排序器都知道应该执行哪个python函数。例如::

>>> # sub-command functions
>>> def foo(args):
...     print(args.x * args.y)
...
>>> def bar(args):
...     print('((%s))' % args.z)
...
>>> # create the top-level parser
>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers()
>>>
>>> # 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() 在参数解析完成后执行调用相应函数的工作。将函数与这样的操作相关联通常是处理每个子分区的不同操作的最简单方法。但是,如果需要检查调用的子排序器的名称,则 dest 关键字参数 add_subparsers() 通话有效:

>>> 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 版更改: 新的 必修的 关键字参数。

文件类型对象

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

参数群

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() 方法返回一个参数组对象,该对象具有 add_argument() 方法就像普通的 ArgumentParser . 当一个参数添加到组中时,解析器将其视为一个普通参数,但在单独的组中显示该参数以获取帮助消息。这个 add_argument_group() 方法接受 标题description 可用于自定义此显示的参数:

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

group1:
  group1 description

  foo    foo help

group2:
  group2 description

  --bar BAR  bar help

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

相互排斥

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() 方法还接受 必修的 参数,以指示至少需要一个互斥参数::

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

请注意,当前互斥的参数组不支持 标题description 参数 add_argument_group() .

语法分析器默认值

ArgumentParser.set_defaults(**kwargs)

大多数情况下,对象的属性 parse_args() 将通过检查命令行参数和参数操作来完全确定。 set_defaults() 允许在不检查命令行的情况下确定一些附加属性:

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

请注意,解析器级别默认值始终重写参数级别默认值:

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

当使用多个解析器时,解析器级别的默认值特别有用。见 add_subparsers() 此类型的示例的方法。

ArgumentParser.get_default(dest)

获取命名空间属性的默认值,由 add_argument() 或通过 set_defaults() ::

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

打印帮助

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

ArgumentParser.print_usage(file=None)

打印如何 ArgumentParser 应该在命令行上调用。如果 fileNonesys.stdout 假设。

ArgumentParser.print_help(file=None)

打印一条帮助消息,包括程序使用情况和在 ArgumentParser . 如果 fileNonesys.stdout 假设。

这些方法还有一些变体,它们只返回字符串而不打印字符串:

ArgumentParser.format_usage()

返回一个字符串,其中包含如何 ArgumentParser 应该在命令行上调用。

ArgumentParser.format_help()

返回一个包含帮助消息的字符串,其中包括程序使用情况和在中注册的参数的信息。 ArgumentParser .

部分句法分析

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

有时,脚本可能只解析一些命令行参数,将其余参数传递给另一个脚本或程序。在这些情况下, parse_known_args() 方法是有用的。它的工作原理很像 parse_args() 但当存在额外的参数时,它不会产生错误。相反,它返回一个包含填充的名称空间和剩余参数字符串列表的两项元组。

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

警告

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

自定义文件分析

ArgumentParser.convert_arg_line_to_args(arg_line)

从文件读取的参数(请参见 fromfile_prefix_chars 关键字参数 ArgumentParser 构造函数)每行读取一个参数。 convert_arg_line_to_args() 可以被更高的阅读覆盖。

此方法采用单个参数 arg_line 它是从参数文件中读取的字符串。它返回从此字符串分析的参数列表。该方法按顺序从参数文件中每行读取一次。

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

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

退出方法

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

此方法终止程序,使用指定的 地位 如果给出,它会打印一个 消息 在那之前。用户可以重写此方法以不同方式处理这些步骤:

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

此方法打印一条使用消息,其中包括 消息 以标准错误终止程序,状态代码为2。

混合解析

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

许多UNIX命令允许用户将可选参数与位置参数混合使用。这个 parse_intermixed_args()parse_known_intermixed_args() 方法支持此分析样式。

这些分析器不支持所有argparse功能,如果使用不支持的功能,则会引发异常。特别是,子组, argparse.REMAINDER 不支持同时包含选项和位置的和互斥的组。

下面的示例显示了 parse_known_args()parse_intermixed_args() :前者返回 ['2', '3'] 作为未分析的参数,而后者将所有位置收集到 rest .地址:

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

parse_known_intermixed_args() 返回包含填充的命名空间和剩余参数字符串列表的两项元组。 parse_intermixed_args() 如果有任何剩余的未分析参数字符串,则引发错误。

3.7 新版功能.

升级optparse代码

原来, argparse 模块试图保持与 optparse .然而, optparse 很难透明地扩展,特别是在支持新的 nargs= 说明符和更好的用法消息。当一切都在 optparse 无论是复制粘贴还是猴子修补,试图保持向后兼容性似乎不再实用。

这个 argparse 模块改进了标准库 optparse 模块有多种方式,包括:

  • 处理位置参数。

  • 支持子命令。

  • 允许其他选项前缀,如 +/ .

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

  • 生成更多信息性的用法消息。

  • 为定制提供更简单的界面 typeaction .

部分升级路径 optparseargparse

  • 全部替换 optparse.OptionParser.add_option() 调用 ArgumentParser.add_argument() 调用。

  • 替换 (options, args) = parser.parse_args() 具有 args = parser.parse_args() 并添加其他 ArgumentParser.add_argument() 调用位置参数。记住之前所说的 options ,现在在 argparse 调用上下文 args .

  • 替换 optparse.OptionParser.disable_interspersed_args() 通过使用 parse_intermixed_args() 而不是 parse_args() .

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

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

  • 替换 optparse.Values 具有 Namespaceoptparse.OptionErroroptparse.OptionValueError 具有 ArgumentError .

  • 用隐式参数替换字符串,例如 %default%prog 使用标准的python语法使用字典来格式化字符串,也就是说, %(default)s%(prog)s .

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