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

版本3.2中的新增.

源代码: Lib / argparse.py


argparse模块可以轻松编写用户友好的命令行界面。程序定义了它需要的参数argparse将弄清楚如何解析sys.argv中的参数argparse模块还会自动生成帮助和使用消息,并在用户给程序提供无效参数时发出错误.

示例

下面的代码是一个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'

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

创建解析器

使用argparse正在创造一个ArgumentParserobject:

>>> 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()将返回一个具有两个属性的对象,integersaccumulateintegers属性将是一个或多个整数的列表,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.ArgumentParserprog=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]
  • 用法 – 描述程序用法(默认:生成的fromarguments添加到解析器中)
  • description – 在参数help之前显示的文本(默认值:无)
  • epilog – 参数help后显示的文本(默认值:无)
  • parents – ArgumentParser对象的列表,其参数也应包括在内
  • formatter_class – 用于自定义的类help output
  • prefix_chars – 前缀可选参数的字符集(默认值:’ – ‘)
  • fromfile_prefix_chars – 应该读取其他参数的文件前缀的字符集(默认值:None)
  • argument_default – 参数的全局默认值(默认值:None
  • conflict_handler – 解决冲突选项的策略(通常是不必要的)
  • add_help – 在解析器中添加一个-h/--help选项(默认值:True
  • allow_abbrev – 如果缩写是明确的,则允许缩写长选项。(默认:True

在版本3.5中更改:allow_abbrev参数已添加.

以下部分介绍了如何使用这些参数.

prog

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

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

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

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

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

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

要更改此默认行为,可以使用prog=参数提供另一个值ArgumentParser

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

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

注意程序名称,是否确定来自sys.argv[0]prog=参数,可以使用%(prog)s formatspecifier.

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

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

usage

来帮助消息,默认情况下,ArgumentParser从它包含的参数中计算用法消息:

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

positional arguments:
 bar          bar help

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

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

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

positional arguments:
 bar          bar help

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

%(prog)s格式说明符可用于填写你的用法信息中的程序名称.

description

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参数.

epilog

有些程序喜欢在参数描述后显示程序的其他描述。可以使用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

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

And that's how you'd foo a bar

description参数一样,epilog=文本是默认行包装的,但是这个行为可以用formatter_classargument调整为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对象在命令行帮助消息中对描述andepilog文本进行换行:

>>> 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=表示描述和epilog已经正确格式化,不应该换行:

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

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

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

RawTextHelpFormatter为各种帮助文本维护空格,包括参数描述。但是,多个新行将替换为one。如果你想保留多个空行,在newlines之间添加空格.

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使用eachargument的类型参数的名称作为显示其值的名称(而不是使用常规格式化程序执行的destas):

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

positional arguments:
  float

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

prefix_chars

大多数命令行选项将使用-作为前缀,例如-f/--foo.Parsers需要支持不同的或额外的前缀字符,例如对于类似+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选项到bedisallowed.

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,这意味着参数永远不会被视为文件references.

argument_default

一般来说,参数默认值是通过将默认值传递给add_argument()或通过调用set_defaults()具有一组特定名称 – 值对的方法。但是,有时为参数指定单个解析器范围的默认值可能很有用。这可以通过argument_default=关键字参数ArgumentParser。例如,要在parse_args()来电,我们供应argument_default=SUPPRESS

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

 

allow_abbrev

通常,当您将参数列表传递给parse_args()一个方法ArgumentParser,它识别缩写长期选择

可以通过设置allow_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对象不允许具有相同optionstring的两个动作。默认情况下,如果使用已经使用的选项字符串创建一个参数,则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

有时(例如,当使用父项时),使用相同的选项字符串简单地覆盖anyolder参数可能是有用的。为了得到这种行为,值"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]

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 optionstring被覆盖了

//add_help

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

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

如果在命令行中提供了-h--help,则将打印ArgumentParserhelp:

$ 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

add_argument()方法

ArgumentParser.add_argumentname or flags… [, action] [, nargs] [, const] [, default] [, type] [, choices] [, required] [, help] [, metavar] [, dest]
定义单个命令行参数应该如何被解析。每个参数在下面都有自己更详细的描述,但简而言之,它们是:

  • name或flags – 一个名称或一个选项字符串列表,例如:foo-f, --foo.
  • action – 在命令行中遇到此参数时要采取的基本操作类型.
  • nargs – 应该是命令行参数的数量consume.
  • const – 某些动作所需的常数值和nargs selections.
  • default – 如果命令行中没有参数,则产生的值.
  • type – The应该转换命令行参数的类型.
  • choices – 参数允许值的容器.
  • required – 是否可以省略命令行选项(仅限选项).
  • help – 对参数的作用的简要说明.
  • metavar – 使用信息中的参数名称.
  • dest – 要添加到parse_args().

返回的对象的属性的名称以下部分描述了如何使用这些属性.

名称或标志

add_argument()方法必须知道是否需要一个optionalargument,比如-f--foo,或者一个位置参数,如列表offilenames。第一个参数传递给add_argument()因此必须是一系列的offlags,或简单的参数名称。例如,可以创建一个可选参数,如:

>>> 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()actionkeyword参数指定应该如何处理命令行参数。提供的操作是:

  • "store" – 这只存储参数的值。这是defaultaction。例如:

    >>> 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 keywordargument默认为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" – 这需要version=调用中的add_argument()关键字参数,并打印版本信息并在调用时退出:

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

您还可以通过传递Action子类或实现相同接口的其他对象来指定任意操作。推荐的dothis方式是扩展Action,覆盖__call__方法和任选的__init__方法。

自定义操作的示例

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

有关详细信息,请参阅Action.

NARGS

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

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

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

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

  • "?"。如果可能,将从命令行使用一个参数,并将其生成为单个项目。如果不存在命令行参数,则将生成来自默认值的值。请注意,对于可选参数,还有一个附加的情况 – 选项字符串存在但后面没有acommand-line参数。在这种情况下,将生成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="*"的多个可选参数ispossible。例如:

    >>> 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'])
  • "+"。就像 "*",所有命令行args都会被收集到alist中。此外,如果没有至少一个命令行参数,将生成错误消息。例如:

    >>> 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
  • 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未提供关键字参数,消耗的参数数量由操作决定。通常这意味着将使用单个命令行参数,并且将生成单个项目(不是列表).

const

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

  • add_argument()action="store_const"调用action="append_const"时。这些操作将const值添加到parse_args()返回的对象的一个​​属性中。请参阅示例的操作说明.
  • 使用选项字符串(如add_argument()-f)和--foo调用nargs="?"。这会创建一个optionalargument,后面可以跟零或一个命令行参数。解析命令行时,如果遇到选项字符串后面跟着nocommand-line参数,则会假定const的值为参见例子的叙述说明.

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

默认值

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

如果default value是一个字符串,解析器将该值解析为它是一个命令行参数。特别是,在设置Namespace返回值的属性之前,解析器应用任何typeconversion参数(如果提供)。否则,解析器使用的值为:

>>> 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 value-行参数存在:

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

如果命令行参数不存在,则提供default=argparse.SUPPRESS导致无法添加属性:

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

type

默认情况下,ArgumentParser对象以简单字符串形式读取命令行参数。但是,通常命令行字符串应该被解释为另一种类型,如floatinttype add_argument()允许执行任何必要的类型检查和类型转换。常见的内置类型和函数可以直接用作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模块提供了一个带有mode=, bufsize=, encoding=函数的errors=open()参数的文件类型。例如,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=可以接受任何带有单个字符串参数的callable并返回转换后的值:

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

对于类型检查器而言,选择关键字参数可能更方便,只需检查一系列值:

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

有关详细信息,请参阅选项部分.

choices

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

请注意包含在选择在执行任何类型转换后检查容器,因此选择容器中的对象类型应与指定的类型匹配:

>>> 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对象,自定义容器等。都支持.

需要

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

示例所示,如果选项被标记为required,parse_args(),如果命令行中没有该选项,则会报错.

注意

所需的选项通常被认为是不好的形式,因为用户希望optionsoptional,因此应尽可能避免它们.

help

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

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

positional arguments:
 bar     one of the bars to be frobbled

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

help字符串可以包含各种格式说明符,以避免重复诸如程序名称或参数默认值之类的内容。可用的指针包括程序名称,%(prog)sadd_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

由于帮助字符串支持%-formatting,如果你想要一个文字%要出现在帮助字符串中,你必须将它作为%%.

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

metavar

ArgumentParser生成帮助消息,它需要一些方法来参考每个预期的参数。默认情况下,ArgumentParser对象使用destvalue作为每个对象的“名称”。默认情况下,对于位置参数化,直接使用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

dest

大多数ArgumentParser actions添加一些值作为parse_args()时。thisattribute的名称由destadd_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,一个callable,它返回一个callable,它从命令行处理参数。遵循此API的任何对象都可以作为action参数传递给add_argument().

class argparse.Actionoption_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None

ArgumentParser使用Action对象来表示从命令行中解析一个或多个字符串中的单个参数所需的信息。Action类必须接受两个位置argumentsplus传递给ArgumentParser.add_argument()除了action本身.

行动的实际情况(或任何可赎回的价值到action参数)应该具有属性“dest”,“option_strings”,“default”,“type”,“required”,“help”等定义。确保定义这些属性的最简单方法是调用Action.__init__.

Action实例应该是可调用的,所以子类必须覆盖__call__方法,它应该接受四个参数:

  • parser – 包含这个动作的ArgumentParser对象.
  • namespaceNamespace将由parse_args()返回的对象。大多数操作使用setattr().
  • values– 关联的命令行参数,应用任何类型的转换。使用类型关键字参数add_argument().
  • option_string– 用于调用此动作的选项字符串.option_string参数是可选的,如果动作与位置参数相关,则不存在.

__call__方法可以执行任意操作,但通常会根据namespacedestvalues.

上设置paat_args()方法

ArgumentParser.parse_argsargs=None, namespace=None
将参数字符串转换为对象并将它们指定为thenamespace的属性。返回填充的命名空间.

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

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

选择值语法

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)

对于长选项(名称长于单个字符的选项),option和value也可以作为单个命令行参数传递,使用= toseparate:

>>> 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()方法很谨慎:如果它们看起来像负数而且没有选项,则positionalarguments可能只以-开头在解析器中看起来像负数:

>>> 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()方法 bydefault 允许将长选项缩写为前缀,如果缩写是不明确的(前缀匹配唯一选项):

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

为可能产生多个选项的参数生成错误。可以通过将 allow_abbrev 设置为False.

 

来禁用此功能。超出sys.argv

有时,使用ArgumentParser解析参数可能非常有用// sys.argv。这可以通过将字符串列表传递给parse_args()来完成。这对于在交互式提示符下进行测试非常有用:

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

 

Namespace对象

class argparse.Namespace
默认情况下由parse_args()用于创建对象保持属性并返回它的简单类.

这个类是故意简单的,只是一个带有areadable字符串表示的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程序可以调用像svncheckout, svn updatesvn commit。当程序执行需要不同类型的命令行参数的各种函数时,以这种方式拆分功能可能是一个特别好的主意.ArgumentParser支持使用add_subparsers()方法创建这样的子命令。add_subparsers()方法通常不带参数,并返回一个特殊的操作对象。这个对象有一个方法,add_parser(),它取名字和任何ArgumentParser构造函数的参数,并返回一个ArgumentParser对象,可以照常修改.

参数描述:

  • title – 帮助输出中子解析器组的标题;默认情况下为“subcommands”,如果提供了description,则使用title forpositional arguments
  • description – 对帮助输出中的sub-parser组的描述,bydefault None
  • prog – 将显示的用法信息子命令帮助,默认情况下程序的名称和子分析器参数之前的任何位置参数
  • parser_class – 用于创建子解析器实例的类,通过默认当前解析器的类(例如ArgumentParser)
  • action – 在命令行中遇到此参数时要采取的基本操作类型
  • dest – 子命令名称所依据的属性的名称;默认情况下 None并且没有存储值
  • required – 默认情况下是否必须提供子命令False.
  • help – 帮助输出中的子解析器组的帮助,默认情况下None
  • metavar – 在帮助中显示可用子命令的字符串;默认情况下它是None并以{cmd1,cmd2,..}形式显示子命令

一些示例用法:

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

注意parse_args()将仅包含主命令行和由命令行(而不是任何其他子分析符)选择的子分析器的属性。所以在上面的例子中,a命令被指定,只有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

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关键字参数。当存在任何一个时,subparser的命令将在帮助输出中的各自组中进行操作。例如:

>>> 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()完成参数解析后调用适当函数的工作。将函数与此类操作相关联通常是处理每个子分析程序的不同操作的最简单方法。但是,如果需要检查被调用的子分析器的名称,dest调用的add_subparsers() keywordargument将起作用:

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

FileType对象

class argparse.FileTypemode=”r”, bufsize=-1, encoding=None, errors=None
FileType工厂创建的对象可以传递给ArgumentParser.add_argument()的typeargument。将FileType对象作为其类型的参数将打开命令行参数asfiles,其中包含所请求的模式,缓冲区大小,编码和错误处理(有关详细信息,请参阅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关键字参数

Argument groups

ArgumentParser.add_argument_grouptitle=None, description=None
默认情况下,ArgumentParser在显示helpmessages时将命令行参数分组为“位置参数”和“可选参数”。当有一个更好的概念分组参数而不是这个默认分组时,可以使用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。当一个参数被添加到组中时,parsertreats就像一个普通的参数,但是在一个单独的组中显示参数以获取帮助消息。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

请注意,不在用户定义的组中的任何参数将最终支持通常的“位置参数”和“可选参数”部分.

相互排斥

ArgumentParser.add_mutually_exclusive_grouprequired=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

注意当前互斥的参数组不支持titledescription的论据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_usagefile=None
打印一个关于如何在命令行中调用ArgumentParser的简短描述。如果fileNone, sys.stdout isassumed.
ArgumentParser.print_help(file=None)
打印一条帮助信息,包括程序用法和有关注册参数的信息用ArgumentParser。如果fileNone, sys.stdout被假定

这些方法的变体只是返回一个字符串而不是打印它:

ArgumentParser.format_usage
返回一个字符串,其中包含如何在命令行调用ArgumentParser的简要说明.
ArgumentParser.format_help (
返回一个包含帮助信息的字符串,包括程序用法和关于ArgumentParser.

部分解析

ArgumentParser.parse_known_argsargs=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'])

Warning

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

自定义文件解析

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

这个方法只需要一个参数arg_line这是一个从参数文件中读取的字符串。它返回从该字符串解析的参数列表。从参数文件读取的每行调用一次方法,按顺序

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

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

退出方法

ArgumentParser.exitstatus=0, message=None
这个方法终止程序,以指定的status退出,如果给出,它在那之前打印message.
ArgumentParser.error(message)
此方法打印包含message到标准错误并终止程序,状态代码为2.

混合解析

ArgumentParser.parse_intermixed_argsargs=None, namespace=None
ArgumentParser.parse_known_intermixed_argsargs=None, namespace=None

许多Unix命令允许用户使用临时参数混合可选参数parse_intermixed_args()parse_known_intermixed_args()方法支持这种解析风格.

这些解析器不支持所有argparse功能,如果使用不支持的功能,则会引发异常。特别是,subparsers,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()返回一个两项tupleconin填充的命名空间和剩余的参数字符串列表.parse_intermixed_args()如果有任何剩余的未解析的参数字符串会引发错误.

版本3.7.

 

升级optparse代码

原来,argparse模块试图保持与optparse的兼容性。然而,optparse很难突出,尤其是支持新的nargs=说明符和更好的用法消息。当optparse中的大部分内容都被复制粘贴或猴子修补时,试图保持向后兼容性似乎不太合适.

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

  • 处理位置参数
  • 支持子命令.
  • 允许使用替代选项前缀,如+/.
  • 处理零或多和一个或多个样式参数.
  • 产生更多信息用法消息.
  • 为定制提供更简单的界面typeaction.

来自optparseargparse

  • 全部替换 optparse.OptionParser.add_option()ArgumentParser.add_argument()calls.
  • 替换(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_*type arguments action替换回调动作和
  • 关键字参数替换type带有相应类型对象的关键字参数(例如int,float,complex等).
  • optparse.ValuesNamespace替换optparse.OptionErroroptparse.OptionValueError with ArgumentError.
  • 用隐式参数替换字符串,例如%default%prog使用标准Python语法使用字典格式化字符串,即%(default)s%(prog)s.
  • 替换OptionParser构造函数version调用parser.add_argument("--version", action="version", version="<the version>").

评论被关闭。