On this page
argparse —解析器,用于命令行选项,参数和子命令
3.2 版中的新Function。
源代码: Lib/argparse.py
Tutorial
此页面包含 API 参考信息。有关 Python 命令行解析的更详尽介绍,请查看argparse tutorial。
argparse模块可轻松编写用户友好的命令行界面。该程序定义了所需的参数,而argparse将找出如何从sys.argv中解析出这些参数。 argparse模块还会自动生成帮助和使用消息,并在用户为程序提供无效参数时发出错误。
Example
以下代码是一个 Python 程序,它接收一个整数列表并产生总和或最大值:
import argparse
parser = argparse.ArgumentParser(description='Process some integers.')
parser.add_argument('integers', metavar='N', type=int, nargs='+',
help='an integer for the accumulator')
parser.add_argument('--sum', dest='accumulate', action='store_const',
const=sum, default=max,
help='sum the integers (default: find the max)')
args = parser.parse_args()
print(args.accumulate(args.integers))
假设上面的 Python 代码已保存到名为prog.py
的文件中,则可以在命令行中运行它并提供有用的帮助消息:
$ python prog.py -h
usage: prog.py [-h] [--sum] N [N ...]
Process some integers.
positional arguments:
N an integer for the accumulator
optional arguments:
-h, --help show this help message and exit
--sum sum the integers (default: find the max)
使用适当的参数运行时,它会打印命令行整数的总和或最大值:
$ python prog.py 1 2 3 4
4
$ python prog.py 1 2 3 4 --sum
10
如果传入了无效的参数,则会发出错误:
$ python prog.py a b c
usage: prog.py [-h] [--sum] N [N ...]
prog.py: error: argument N: invalid int value: 'a'
以下各节将引导您完成此示例。
创建解析器
使用argparse的第一步是创建ArgumentParser对象:
>>> parser = argparse.ArgumentParser(description='Process some integers.')
ArgumentParser对象将保存将命令行解析为 Python 数据类型所需的所有信息。
Adding arguments
pass调用add_argument()方法来完成有关程序参数信息的ArgumentParser的填充。通常,这些调用告诉ArgumentParser如何在命令行中获取字符串并将其转换为对象。调用parse_args()时,将存储并使用此信息。例如:
>>> parser.add_argument('integers', metavar='N', type=int, nargs='+',
... help='an integer for the accumulator')
>>> parser.add_argument('--sum', dest='accumulate', action='store_const',
... const=sum, default=max,
... help='sum the integers (default: find the max)')
稍后,调用parse_args()将返回具有两个属性integers
和accumulate
的对象。 integers
属性将是一个或多个整数的列表,而accumulate
属性将是sum()函数(如果在命令行中指定了--sum
),或者是max()函数(如果未在命令行中指定)。
Parsing arguments
ArgumentParserpassparse_args()方法解析参数。这将检查命令行,将每个参数转换为适当的类型,然后调用适当的操作。在大多数情况下,这意味着将pass从命令行外解析的属性来构建一个简单的Namespace对象:
>>> parser.parse_args(['--sum', '7', '-1', '42'])
Namespace(accumulate=<built-in function sum>, integers=[7, -1, 42])
在脚本中,通常会不带任何参数调用parse_args(),而ArgumentParser会根据sys.argv自动确定命令行参数。
ArgumentParser objects
-
- class *
argparse.
ArgumentParser
(* prog = None , usage = None , description = None , epilog = None , parents = [] , formatter_class = argparse.HelpFormatter , prefix_chars ='- ', fromfile_prefix_chars = None , argument_default = None , conflict_handler ='error', add_help = True , allow_abbrev = True *)
- 创建一个新的ArgumentParser对象。所有参数都应作为关键字参数传递。每个参数在下面都有自己的更详细的描述,但简而言之,它们是:
- class *
prog-程序名称(默认值:
sys.argv[0]
)usage-描述程序用法的字符串(默认值:从添加到解析器的参数生成)
description-在参数帮助前显示的文本(默认值:无)
epilog-在参数 help 之后显示的文本(默认值:无)
parents-ArgumentParser个对象的列表,其参数也应包括在内
formatter_class-用于自定义帮助输出的类
prefix_chars-前缀可选参数的字符集(默认值:“-”)
fromfile_prefix_chars-前缀文件的字符集,应从中读取其他参数(默认值:
None
)argument_default-参数的全局默认值(默认值:
None
)conflict_handler-解决冲突的可选项目的策略(通常是不必要的)
add_help-向解析器添加
-h/--help
选项(默认值:True
)allow_abbrev-如果缩写是明确的,则允许缩写长选项。 (默认值:
True
)
在版本 3.5 中更改:添加了* allow_abbrev *参数。
在 3.8 版中进行了更改:在以前的版本中,* allow_abbrev *还禁用了对短标记(例如-vv
表示-v -v
)的分组。
以下各节描述了如何使用它们。
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
要更改此默认行为,可以使用ArgumentParser的prog=
参数提供另一个值:
>>> parser = argparse.ArgumentParser(prog='myprogram')
>>> parser.print_help()
usage: myprogram [-h]
optional arguments:
-h, --help show this help message and exit
请注意,程序名称(无论是从sys.argv[0]
还是从prog=
参数确定)可用于使用%(prog)s
格式说明符的帮助消息。
>>> parser = argparse.ArgumentParser(prog='myprogram')
>>> parser.add_argument('--foo', help='foo of the %(prog)s program')
>>> parser.print_help()
usage: myprogram [-h] [--foo FOO]
optional arguments:
-h, --help show this help message and exit
--foo FOO foo of the myprogram program
usage
默认情况下,ArgumentParser根据其包含的参数计算使用情况消息:
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo', nargs='?', help='foo help')
>>> parser.add_argument('bar', nargs='+', help='bar help')
>>> parser.print_help()
usage: PROG [-h] [--foo [FOO]] bar [bar ...]
positional arguments:
bar bar help
optional arguments:
-h, --help show this help message and exit
--foo [FOO] foo help
可以使用usage=
关键字参数覆盖默认消息:
>>> parser = argparse.ArgumentParser(prog='PROG', usage='%(prog)s [options]')
>>> parser.add_argument('--foo', nargs='?', help='foo help')
>>> parser.add_argument('bar', nargs='+', help='bar help')
>>> parser.print_help()
usage: PROG [options]
positional arguments:
bar bar help
optional arguments:
-h, --help show this help message and exit
--foo [FOO] foo help
%(prog)s
格式说明符可用于在使用情况消息中填写程序名称。
description
对ArgumentParser构造函数的大多数调用将使用description=
关键字参数。该参数简要说明了程序的Function及其工作方式。在帮助消息中,描述显示在命令行用法字符串和各种参数的帮助消息之间:
>>> 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
某些程序喜欢在参数说明之后显示该程序的其他说明。可以使用ArgumentParser的epilog=
参数指定此类文本:
>>> parser = argparse.ArgumentParser(
... description='A foo that bars',
... epilog="And that's how you'd foo a bar")
>>> parser.print_help()
usage: argparse.py [-h]
A foo that bars
optional arguments:
-h, --help show this help message and exit
And that's how you'd foo a bar
与description参数一样,epilog=
文本默认情况下用行换行,但是可以passArgumentParser的formatter_class参数来调整此行为。
parents
有时,几个解析器共享一组公共参数。不必重复这些参数的定义,可以使用具有所有共享参数并传递给ArgumentParser的parents=
参数的单个解析器。 parents=
参数获取ArgumentParser对象的列表,从它们中收集所有位置和可选动作,并将这些动作添加到正在构造的ArgumentParser对象中:
>>> parent_parser = argparse.ArgumentParser(add_help=False)
>>> parent_parser.add_argument('--parent', type=int)
>>> foo_parser = argparse.ArgumentParser(parents=[parent_parser])
>>> foo_parser.add_argument('foo')
>>> foo_parser.parse_args(['--parent', '2', 'XXX'])
Namespace(foo='XXX', parent=2)
>>> bar_parser = argparse.ArgumentParser(parents=[parent_parser])
>>> bar_parser.add_argument('--bar')
>>> bar_parser.parse_args(['--bar', 'YYY'])
Namespace(bar='YYY', parent=None)
请注意,大多数父解析器将指定add_help=False
。否则,ArgumentParser将看到两个-h/--help
选项(一个在父级中,一个在子级中),并引发错误。
Note
您必须完全初始化解析器,然后才能passparents=
传递解析器。如果在子解析器之后更改父解析器,则这些更改将不会反映在子解析器中。
formatter_class
ArgumentParser对象允许pass指定备用格式设置类来自定义帮助格式。当前,有四个此类类:
- 类别
argparse.
RawDescriptionHelpFormatter
- 类别
argparse.
RawTextHelpFormatter
- 类别
argparse.
ArgumentDefaultsHelpFormatter
- 类别
argparse.
MetavarTypeHelpFormatter
RawDescriptionHelpFormatter和RawTextHelpFormatter可以更好地控制文本说明的显示方式。默认情况下,ArgumentParser个对象将命令行帮助消息中的description和epilogtextwrap:
>>> parser = argparse.ArgumentParser(
... prog='PROG',
... description='''this description
... was indented weird
... but that is okay''',
... epilog='''
... likewise for this epilog whose whitespace will
... be cleaned up and whose words will be wrapped
... across a couple lines''')
>>> parser.print_help()
usage: PROG [-h]
this description was indented weird but that is okay
optional arguments:
-h, --help show this help message and exit
likewise for this epilog whose whitespace will be cleaned up and whose words
will be wrapped across a couple lines
将RawDescriptionHelpFormatter传递为formatter_class=
表示description和epilog已正确格式化,因此不应进行换行:
>>> parser = argparse.ArgumentParser(
... prog='PROG',
... formatter_class=argparse.RawDescriptionHelpFormatter,
... description=textwrap.dedent('''\
... Please do not mess up this text!
... --------------------------------
... I have indented it
... exactly the way
... I want it
... '''))
>>> parser.print_help()
usage: PROG [-h]
Please do not mess up this text!
--------------------------------
I have indented it
exactly the way
I want it
optional arguments:
-h, --help show this help message and exit
RawTextHelpFormatter维护各种帮助文本的空格,包括参数说明。但是,将多个新行替换为一个。如果您希望保留多个空白行,请在换行符之间添加空格。
ArgumentDefaultsHelpFormatter自动将有关默认值的信息添加到每个参数帮助消息中:
>>> parser = argparse.ArgumentParser(
... prog='PROG',
... formatter_class=argparse.ArgumentDefaultsHelpFormatter)
>>> parser.add_argument('--foo', type=int, default=42, help='FOO!')
>>> parser.add_argument('bar', nargs='*', default=[1, 2, 3], help='BAR!')
>>> parser.print_help()
usage: PROG [-h] [--foo FOO] [bar [bar ...]]
positional arguments:
bar BAR! (default: [1, 2, 3])
optional arguments:
-h, --help show this help message and exit
--foo FOO FOO! (default: 42)
MetavarTypeHelpFormatter使用每个参数的type参数的名称作为其值的显示名称(而不是像常规格式化程序一样使用dest):
>>> parser = argparse.ArgumentParser(
... prog='PROG',
... formatter_class=argparse.MetavarTypeHelpFormatter)
>>> parser.add_argument('--foo', type=int)
>>> parser.add_argument('bar', type=float)
>>> parser.print_help()
usage: PROG [-h] [--foo int] float
positional arguments:
float
optional arguments:
-h, --help show this help message and exit
--foo int
prefix_chars
大多数命令行选项将使用-
作为前缀,例如-f/--foo
。需要支持其他或其他前缀字符的解析器,例如对于+f
或/foo
之类的选项,可以使用 ArgumentParser 构造函数的prefix_chars=
参数指定它们:
>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='-+')
>>> parser.add_argument('+f')
>>> parser.add_argument('++bar')
>>> parser.parse_args('+f X ++bar Y'.split())
Namespace(bar='Y', f='X')
prefix_chars=
参数默认为'-'
。提供一组不包含-
的字符将导致-f/--foo
选项被禁止。
fromfile_prefix_chars
有时,例如,当处理特别长的参数列表时,将参数列表保留在文件中而不是在命令行中将其键入可能是有意义的。如果将fromfile_prefix_chars=
参数提供给ArgumentParser构造函数,则以任何指定字符开头的参数将被视为文件,并将被包含的参数替换。例如:
>>> with open('args.txt', 'w') 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
通常,参数默认值是pass将默认值传递给add_argument()或pass使用一组特定的名称/值对调用set_defaults()方法来指定的。但是有时候,为参数指定单个解析器范围的默认值可能会很有用。这可以pass将argument_default=
关键字参数传递给ArgumentParser来实现。例如,要全局禁止在parse_args()调用上创建属性,我们提供argument_default=SUPPRESS
:
>>> parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS)
>>> parser.add_argument('--foo')
>>> parser.add_argument('bar', nargs='?')
>>> parser.parse_args(['--foo', '1', 'BAR'])
Namespace(bar='BAR', foo='1')
>>> parser.parse_args([])
Namespace()
allow_abbrev
通常,当您将参数列表传递给ArgumentParser的parse_args()方法时,它将recognizes abbreviations用作长选项。
可以pass将allow_abbrev
设置为False
来禁用此Function:
>>> 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 版中的新Function。
conflict_handler
ArgumentParser对象不允许两个操作使用相同的选项字符串。默认情况下,如果try使用已使用的选项字符串创建参数,则ArgumentParser个对象会引发异常:
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-f', '--foo', help='old foo help')
>>> parser.add_argument('--foo', help='new foo help')
Traceback (most recent call last):
..
ArgumentError: argument --foo: conflicting option string(s): --foo
有时(例如,使用parents时),使用相同的选项字符串简单地覆盖所有较旧的参数可能会很有用。要获得此行为,可以将值'resolve'
提供给ArgumentParser的conflict_handler=
参数:
>>> parser = argparse.ArgumentParser(prog='PROG', conflict_handler='resolve')
>>> parser.add_argument('-f', '--foo', help='old foo help')
>>> parser.add_argument('--foo', help='new foo help')
>>> parser.print_help()
usage: PROG [-h] [-f FOO] [--foo FOO]
optional arguments:
-h, --help show this help message and exit
-f FOO old foo help
--foo FOO new foo help
请注意,ArgumentParser对象仅在其所有选项字符串均被覆盖时才删除操作。因此,在上面的示例中,旧的-f/--foo
动作保留为-f
动作,因为仅--foo
选项字符串被覆盖。
add_help
默认情况下,ArgumentParser 对象添加一个选项,该选项仅显示解析器的帮助消息。例如,考虑一个名为myprogram.py
的文件,其中包含以下代码:
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--foo', help='foo help')
args = parser.parse_args()
如果在命令行提供-h
或--help
,则将打印 ArgumentParser 帮助:
$ python myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]
optional arguments:
-h, --help show this help message and exit
--foo FOO foo help
有时,禁用此帮助选项的添加可能很有用。这可以pass将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
。exception 是如果指定了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_argument
(*名称或标志... * [,* action *] [,* nargs *] [,* const *] [,* default *] [,* type *] [,* choices *] [,必填] [,帮助] [,元变量] [,目标])- 定义应如何解析单个命令行参数。每个参数在下面都有自己的更详细的描述,但简而言之,它们是:
名称或标志-名称或选项字符串列表,例如
foo
或-f, --foo
。action-在命令行中遇到此参数时要采取的基本操作类型。
nargs-应该使用的命令行参数的数量。
default-如果命令行中不存在参数,则生成该值。
type-命令行参数应转换为的类型。
choices-包含参数允许值的容器。
required-是否可以Ellipsis命令行选项(仅可选)。
help-关于自变量的简要说明。
metavar-使用情况消息中参数的名称。
dest-要添加到parse_args()返回的对象的属性的名称。
以下各节描述了如何使用它们。
名称或标志
add_argument()方法必须知道是否需要可选参数,例如-f
或--foo
或位置参数,例如文件名列表。因此,传递给add_argument()的第一个参数必须是一系列标志或简单的参数名称。例如,可以创建一个可选参数,例如:
>>> parser.add_argument('-f', '--foo')
而位置参数可以像这样创建:
>>> parser.add_argument('bar')
调用parse_args()时,可选参数将由-
前缀标识,其余参数将假定为位置:
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-f', '--foo')
>>> parser.add_argument('bar')
>>> parser.parse_args(['BAR'])
Namespace(bar='BAR', foo=None)
>>> parser.parse_args(['BAR', '--foo', 'FOO'])
Namespace(bar='BAR', foo='FOO')
>>> parser.parse_args(['--foo', 'FOO'])
usage: PROG [-h] [-f FOO] bar
PROG: error: the following arguments are required: bar
action
ArgumentParser个对象将命令行参数与操作相关联。尽管大多数操作只是向parse_args()返回的对象添加属性,但这些操作几乎可以pass与之关联的命令行参数执行任何操作。 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'
的特殊情况,分别用于存储值True
和False
。此外,它们分别创建默认值False
和True
。例如:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='store_true')
>>> parser.add_argument('--bar', action='store_false')
>>> parser.add_argument('--baz', action='store_false')
>>> parser.parse_args('--foo --bar'.split())
Namespace(foo=True, bar=False, baz=True)
'append'
-这将存储一个列表,并将每个参数值附加到列表中。这对于允许多次指定选项很有用。用法示例:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='append')
>>> parser.parse_args('--foo 1 --foo 2'.split())
Namespace(foo=['1', '2'])
'append_const'
-这将存储一个列表,并将const关键字参数指定的值附加到列表中。 (请注意,const关键字参数默认为None
。)当多个参数需要将常量存储到同一列表时,'append_const'
操作通常很有用。例如:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--str', dest='types', action='append_const', const=str)
>>> parser.add_argument('--int', dest='types', action='append_const', const=int)
>>> parser.parse_args('--str --int'.split())
Namespace(types=[<class 'str'>, <class 'int'>])
'count'
-计算关键字参数出现的次数。例如,这对于提高详细程度很有用:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--verbose', '-v', action='count', default=0)
>>> parser.parse_args(['-vvv'])
Namespace(verbose=3)
注意,除非默认设置为* 0 ,否则 default *将为None
。
'help'
-这会为当前解析器中的所有选项打印完整的帮助消息,然后退出。默认情况下,帮助操作会自动添加到解析器中。有关如何创建输出的详细信息,请参见ArgumentParser。'version'
-这将在add_argument()调用中使用version=
关键字参数,并打印版本信息并在调用时退出:
>>> import argparse
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--version', action='version', version='%(prog)s 2.0')
>>> parser.parse_args(['--version'])
PROG 2.0
'extend'
-这将存储一个列表,并将每个参数值扩展到该列表。用法示例:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument("--foo", action="extend", nargs="+", type=str)
>>> parser.parse_args(["--foo", "f1", "--foo", "f2", "f3", "f4"])
Namespace(foo=['f1', 'f2', 'f3', 'f4'])
3.8 版的新Function。
您还可以pass传递 Action 子类或实现相同接口的其他对象来指定任意动作。推荐的方法是扩展Action,覆盖__call__
方法和可选的__init__
方法。
自定义操作的示例:
>>> class FooAction(argparse.Action):
... def __init__(self, option_strings, dest, nargs=None, **kwargs):
... if nargs is not None:
... raise ValueError("nargs not allowed")
... super(FooAction, self).__init__(option_strings, dest, **kwargs)
... def __call__(self, parser, namespace, values, option_string=None):
... print('%r %r %r' % (namespace, values, option_string))
... setattr(namespace, self.dest, values)
...
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action=FooAction)
>>> parser.add_argument('bar', action=FooAction)
>>> args = parser.parse_args('1 --foo 2'.split())
Namespace(bar=None, foo=None) '1' None
Namespace(bar='1', foo=None) '2' '--foo'
>>> args
Namespace(bar='1', foo='2')
有关更多详细信息,请参见Action。
nargs
ArgumentParser 对象通常将单个命令行参数与要执行的单个操作相关联。 nargs
关键字参数将不同数量的命令行参数与单个操作相关联。支持的值为:
N
(整数)。命令行中的N
个参数将一起收集到一个列表中。例如:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', nargs=2)
>>> parser.add_argument('bar', nargs=1)
>>> parser.parse_args('c --foo a b'.split())
Namespace(bar=['c'], foo=['a', 'b'])
请注意,nargs=1
会产生一项的列表。这与默认情况不同,在默认情况下,项目是自己生产的。
'?'
。如果可能,将从命令行使用一个参数,并将其作为单个项目产生。如果不存在命令行参数,则将产生default的值。请注意,对于可选参数,还有另外一种情况-选项字符串存在,但后面没有命令行参数。在这种情况下,将产生const的值。一些例子来说明这一点:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', nargs='?', const='c', default='d')
>>> parser.add_argument('bar', nargs='?', default='d')
>>> parser.parse_args(['XX', '--foo', 'YY'])
Namespace(bar='XX', foo='YY')
>>> parser.parse_args(['XX', '--foo'])
Namespace(bar='XX', foo='c')
>>> parser.parse_args([])
Namespace(bar='d', foo='d')
nargs='?'
的较常见用法之一是允许可选的 Importing 和输出文件:
>>> 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
argparse.REMAINDER
。其余所有命令行参数都收集到一个列表中。这对于分派到其他命令行 Util 的命令行 Util 通常很有用:
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo')
>>> parser.add_argument('command')
>>> parser.add_argument('args', nargs=argparse.REMAINDER)
>>> print(parser.parse_args('--foo B cmd --arg1 XX ZZ'.split()))
Namespace(args=['--arg1', 'XX', 'ZZ'], command='cmd', foo='B')
如果未提供nargs
关键字参数,则消耗的参数数量由action确定。通常,这意味着将使用单个命令行参数,并且将生成单个项目(而不是列表)。
const
add_argument()的const
参数用于保存常量值,该常量值不是从命令行读取的,但是对于各种ArgumentParser操作而言是必需的。它的两个最常见的用途是:
当使用
action='store_const'
或action='append_const'
调用add_argument()时。这些操作将const
值添加到parse_args()返回的对象的属性之一。有关示例,请参见action描述。当使用选项字符串(例如
-f
或--foo
)和nargs='?'
调用add_argument()时。这将创建一个可选参数,后跟零个或一个命令行参数。解析命令行时,如果遇到选项字符串,但后面没有命令行参数,则将使用const
的值。有关示例,请参见nargs说明。
对于'store_const'
和'append_const'
操作,必须提供const
关键字参数。对于其他操作,它默认为None
。
default
在命令行可以Ellipsis所有可选参数和某些位置参数。 add_argument()的default
关键字参数(其默认值为None
)指定在不存在命令行参数的情况下应使用的值。对于可选参数,当命令行中不存在选项字符串时,使用default
值:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=42)
>>> parser.parse_args(['--foo', '2'])
Namespace(foo='2')
>>> parser.parse_args([])
Namespace(foo=42)
如果default
值为字符串,则解析器将解析该值,就好像它是命令行参数一样。特别是,解析器会在设置Namespace返回值上的属性之前应用任何type转换参数(如果提供)。否则,解析器将按原样使用该值:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--length', default='10', type=int)
>>> parser.add_argument('--width', default=10.5, type=int)
>>> parser.parse_args()
Namespace(length=10, width=10.5)
对于nargs等于?
或*
的位置参数,当不存在命令行参数时使用default
值:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', nargs='?', default=42)
>>> parser.parse_args(['a'])
Namespace(foo='a')
>>> parser.parse_args([])
Namespace(foo=42)
如果不存在命令行参数,则提供default=argparse.SUPPRESS
不会添加任何属性:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=argparse.SUPPRESS)
>>> parser.parse_args([])
Namespace()
>>> parser.parse_args(['--foo', '1'])
Namespace(foo='1')
type
默认情况下,ArgumentParser个对象以简单字符串的形式读取命令行参数。但是,通常应该将命令行字符串解释为另一种类型,例如float或int。 add_argument()的type
关键字参数允许执行任何必要的类型检查和类型转换。常见的内置类型和函数可以直接用作type
参数的值:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', type=int)
>>> parser.add_argument('bar', type=open)
>>> parser.parse_args('2 temp.txt'.split())
Namespace(bar=<_io.TextIOWrapper name='temp.txt' encoding='UTF-8'>, foo=2)
有关何时将type
参数应用于默认参数的信息,请参见default关键字参数部分。
为了简化各种文件的使用,argparse 模块提供了工厂 FileType,它使用open()函数的mode=
,bufsize=
,encoding=
和errors=
参数。例如,FileType('w')
可用于创建可写文件:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('bar', type=argparse.FileType('w'))
>>> parser.parse_args(['out.txt'])
Namespace(bar=<_io.TextIOWrapper name='out.txt' encoding='UTF-8'>)
type=
可以接受带有单个字符串参数并返回转换后值的任何可调用对象:
>>> def perfect_square(string):
... value = int(string)
... sqrt = math.sqrt(value)
... if sqrt != int(sqrt):
... msg = "%r is not a perfect square" % string
... raise argparse.ArgumentTypeError(msg)
... return value
...
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', type=perfect_square)
>>> parser.parse_args(['9'])
Namespace(foo=9)
>>> parser.parse_args(['7'])
usage: PROG [-h] foo
PROG: error: argument foo: '7' is not a perfect square
对于只检查一系列值的类型检查器,choices关键字参数可能更方便:
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', type=int, choices=range(5, 10))
>>> parser.parse_args(['7'])
Namespace(foo=7)
>>> parser.parse_args(['11'])
usage: PROG [-h] {5,6,7,8,9}
PROG: error: argument foo: invalid choice: 11 (choose from 5, 6, 7, 8, 9)
有关更多详细信息,请参见choices部分。
choices
某些命令行参数应从一组受限制的值中选择。这些可以pass将容器对象作为关键字的* choices *传递给add_argument()来处理。解析命令行时,将检查参数值,如果参数不是可接受的值之一,则将显示错误消息:
>>> parser = argparse.ArgumentParser(prog='game.py')
>>> parser.add_argument('move', choices=['rock', 'paper', 'scissors'])
>>> parser.parse_args(['rock'])
Namespace(move='rock')
>>> parser.parse_args(['fire'])
usage: game.py [-h] {rock,paper,scissors}
game.py: error: argument move: invalid choice: 'fire' (choose from 'rock',
'paper', 'scissors')
请注意,在执行任何type转换后,将检查是否包含在* choices 容器中,因此, choices *容器中的对象类型应与指定的type相匹配:
>>> parser = argparse.ArgumentParser(prog='doors.py')
>>> parser.add_argument('door', type=int, choices=range(1, 4))
>>> print(parser.parse_args(['3']))
Namespace(door=3)
>>> parser.parse_args(['4'])
usage: doors.py [-h] {1,2,3}
doors.py: error: argument door: invalid choice: 4 (choose from 1, 2, 3)
任何容器都可以作为* choices *值传递,因此,list对象,set对象和自定义容器均受支持。
required
通常,argparse模块假定-f
和--bar
之类的标志表示* optional 参数,这些参数始终可以在命令行中Ellipsis。要必需*提供选项,可以为add_argument()的required=
关键字参数指定True
:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', required=True)
>>> parser.parse_args(['--foo', 'BAR'])
Namespace(foo='BAR')
>>> parser.parse_args([])
usage: argparse.py [-h] [--foo FOO]
argparse.py: error: option --foo is required
如示例所示,如果将选项标记为required
,则如果命令行中不存在该选项,则parse_args()将报告错误。
Note
必需选项通常被认为是不好的形式,因为用户期望* options 是 optional *,因此应尽可能避免使用。
help
help
值是一个字符串,其中包含参数的简短说明。当用户请求帮助时(通常pass在命令行上使用-h
或--help
),这些help
描述将与每个参数一起显示:
>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('--foo', action='store_true',
... help='foo the bars before frobbling')
>>> parser.add_argument('bar', nargs='+',
... help='one of the bars to be frobbled')
>>> parser.parse_args(['-h'])
usage: frobble [-h] [--foo] bar [bar ...]
positional arguments:
bar one of the bars to be frobbled
optional arguments:
-h, --help show this help message and exit
--foo foo the bars before frobbling
help
字符串可以包含各种格式说明符,以避免重复程序名称或自变量default之类的内容。可用的说明符包括程序名称%(prog)s
和add_argument()的大多数关键字参数,例如%(default)s
,%(type)s
等:
>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('bar', nargs='?', type=int, default=42,
... help='the bar to %(prog)s (default: %(default)s)')
>>> parser.print_help()
usage: frobble [-h] [bar]
positional arguments:
bar the bar to frobble (default: 42)
optional arguments:
-h, --help show this help message and exit
由于帮助字符串支持%格式,因此,如果希望 Literals_出现在帮助字符串中,则必须以%%
对其进行转义。
argparsepass将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 对象使用dest值作为每个对象的“名称”。默认情况下,对于位置参数操作,dest值直接使用,对于可选参数操作,dest值是大写的。因此,具有dest='bar'
的单个位置参数将称为bar
。单个可选参数--foo
(其后应跟单个命令行参数)将被称为FOO
。一个例子:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.add_argument('bar')
>>> parser.parse_args('X --foo Y'.split())
Namespace(bar='X', foo='Y')
>>> parser.print_help()
usage: [-h] [--foo FOO] bar
positional arguments:
bar
optional arguments:
-h, --help show this help message and exit
--foo FOO
备用名称可以用metavar
指定:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', metavar='YYY')
>>> parser.add_argument('bar', metavar='XXX')
>>> parser.parse_args('X --foo Y'.split())
Namespace(bar='X', foo='Y')
>>> parser.print_help()
usage: [-h] [--foo YYY] XXX
positional arguments:
XXX
optional arguments:
-h, --help show this help message and exit
--foo YYY
请注意,metavar
仅更改显示名称-parse_args()对象上的属性名称仍由dest值确定。
nargs
的不同值可能会使 metavar 多次使用。为metavar
提供 Tuples 会为每个参数指定不同的显示方式:
>>> 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操作都会为parse_args()返回的对象的属性添加一些值。此属性的名称由add_argument()的dest
关键字参数确定。对于位置参数操作,通常将dest
作为第一个参数提供给add_argument():
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('bar')
>>> parser.parse_args(['XXX'])
Namespace(bar='XXX')
对于可选参数操作,通常从选项字符串中推断出dest
的值。 ArgumentParserpass获取第一个长选项字符串并去除初始--
字符串来生成dest
的值。如果未提供任何长选项字符串,则将pass剥离开头的-
字符从第一个短选项字符串派生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 classes
动作类实现 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 *)
- class *
ArgumentParser 使用动作对象表示从命令行的一个或多个字符串解析单个参数所需的信息。 Action 类必须接受两个位置参数以及传递给ArgumentParser.add_argument()的任何关键字参数,但action
本身除外。
Action 实例(或可调用action
参数的返回值)应具有定义的属性“ dest”,“ option_strings”,“ default”,“ type”,“ required”,“ help”等。确保定义这些属性的最简单方法是调用Action.__init__
。
操作实例应该是可调用的,因此子类必须重写__call__
方法,该方法应接受四个参数:
parser
-包含此操作的 ArgumentParser 对象。namespace
-parse_args()返回的Namespace对象。大多数操作都使用setattr()向该对象添加属性。values
-关联的命令行参数,应用了任何类型转换。类型转换passadd_argument()的type关键字参数指定。option_string
-用于调用此操作的选项字符串。option_string
参数是可选的,如果操作与位置参数相关联,则option_string
参数将不存在。
__call__
方法可以执行任意操作,但是通常会基于dest
和values
在namespace
上设置属性。
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')
Invalid arguments
解析命令行时,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()方法try在用户明显犯错时给出错误,但是某些情况固有地模棱两可。例如,命令行参数-1
可以是try指定选项,也可以是提供位置参数。 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
对于可能产生多个选项的参数会产生错误。可以pass将allow_abbrev设置为False
来禁用此Function。
Beyond sys.argv
有时,让 ArgumentParser 解析除sys.argv之外的参数可能会很有用。这可以pass将字符串列表传递给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])
命名空间对象
- 类别
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对象也可能很有用。这可以pass指定namespace=
关键字参数来实现:
>>> class C:
... pass
...
>>> c = C()
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.parse_args(args=['--foo', 'BAR'], namespace=c)
>>> c.foo
'BAR'
Other utilities
Sub-commands
ArgumentParser.
add_subparsers
([* title *] [,* description *] [,* prog *] [,* parser_class *] [,* action *] [,* option_string *] [,* dest *] [,必需] [,* help *] [,* metavar *])- 许多程序将其Function分成许多子命令,例如
svn
程序可以调用svn checkout
,svn update
和svn commit
之类的子命令。当程序执行需要不同种类命令行参数的几种不同Function时,以这种方式拆分Function可能是一个特别好的主意。 ArgumentParser支持使用add_subparsers()方法创建此类子命令。 add_subparsers()方法通常不带任何参数调用,并返回一个特殊的操作对象。该对象具有一个方法add_parser()
,该方法采用命令名称和任何ArgumentParser构造函数参数,并返回ArgumentParser对象,该对象可以照常进行修改。
- 许多程序将其Function分成许多子命令,例如
参数说明:
title-帮助输出中的子解析器组的标题;默认情况下为“子命令”(如果提供了说明),否则使用标题作为位置参数
description-帮助输出中子解析器组的描述,默认为
None
prog-将在子命令帮助中显示的用法信息,默认情况下为程序名称以及 subparser 参数之前的任何位置参数
parser_class-用于创建子解析器实例的类,默认情况下为当前解析器的类(例如 ArgumentParser)
action-在命令行中遇到此参数时要采取的基本操作类型
dest-将在其下存储子命令名称的属性名称;默认情况下
None
,并且不存储任何值required-默认情况下是否必须提供子命令
False
(在 3.7 中添加)help-帮助输出中的子解析器组的帮助,默认情况下
None
metavar-在帮助中显示可用子命令的字符串;默认情况下为
None
并以\ {cmd1, cmd2, ..}形式显示子命令
一些示例用法:
>>> # create the top-level parser
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo', action='store_true', help='foo help')
>>> subparsers = parser.add_subparsers(help='sub-command help')
>>>
>>> # create the parser for the "a" command
>>> parser_a = subparsers.add_parser('a', help='a help')
>>> parser_a.add_argument('bar', type=int, help='bar help')
>>>
>>> # create the parser for the "b" command
>>> parser_b = subparsers.add_parser('b', help='b help')
>>> parser_b.add_argument('--baz', choices='XYZ', help='baz help')
>>>
>>> # parse some argument lists
>>> parser.parse_args(['a', '12'])
Namespace(bar=12, foo=False)
>>> parser.parse_args(['--foo', 'b', '--baz', 'Z'])
Namespace(baz='Z', foo=True)
请注意,由parse_args()返回的对象将仅包含主解析器和命令行选择的子解析器的属性(而不包含任何其他子解析器)。因此,在上面的示例中,当指定a
命令时,仅存在foo
和bar
属性,而当指定b
命令时,仅存在foo
和baz
属性。
同样,当从子解析器请求帮助消息时,将仅打印该特定解析器的帮助。帮助消息将不包括父解析器或同级解析器消息。 (但是,可以pass如上所述向add_parser()
提供help=
参数来为每个 subparser 命令提供帮助消息.)
>>> 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()方法还支持title
和description
关键字参数。如果存在两者之一,则子解析器的命令将出现在帮助输出中的它们自己的组中。例如:
>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers(title='subcommands',
... description='valid subcommands',
... help='additional help')
>>> subparsers.add_parser('foo')
>>> subparsers.add_parser('bar')
>>> parser.parse_args(['-h'])
usage: [-h] {foo,bar} ...
optional arguments:
-h, --help show this help message and exit
subcommands:
valid subcommands
{foo,bar} additional help
此外,add_parser
支持附加的aliases
参数,该参数允许多个字符串引用同一子解析器。此示例与svn
类似,别名co
作为checkout
的简写:
>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers()
>>> checkout = subparsers.add_parser('checkout', aliases=['co'])
>>> checkout.add_argument('foo')
>>> parser.parse_args(['co', 'bar'])
Namespace(foo='bar')
处理子命令的一种特别有效的方法是将add_subparsers()方法的使用与对set_defaults()的调用结合起来,以便每个子解析器都知道应该执行哪个 Python 函数。例如:
>>> # sub-command functions
>>> def foo(args):
... print(args.x * args.y)
...
>>> def bar(args):
... print('((%s))' % args.z)
...
>>> # create the top-level parser
>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers()
>>>
>>> # create the parser for the "foo" command
>>> parser_foo = subparsers.add_parser('foo')
>>> parser_foo.add_argument('-x', type=int, default=1)
>>> parser_foo.add_argument('y', type=float)
>>> parser_foo.set_defaults(func=foo)
>>>
>>> # create the parser for the "bar" command
>>> parser_bar = subparsers.add_parser('bar')
>>> parser_bar.add_argument('z')
>>> parser_bar.set_defaults(func=bar)
>>>
>>> # parse the args and call whatever function was selected
>>> args = parser.parse_args('foo 1 -x 2'.split())
>>> args.func(args)
2.0
>>>
>>> # parse the args and call whatever function was selected
>>> args = parser.parse_args('bar XYZYX'.split())
>>> args.func(args)
((XYZYX))
这样,您可以让parse_args()完成参数解析后调用适当函数的工作。将函数与这样的动作相关联通常是为每个子解析器处理不同动作的最简单方法。但是,如果有必要检查被调用的子解析器的名称,则add_subparsers()调用的dest
关键字参数将起作用:
>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers(dest='subparser_name')
>>> subparser1 = subparsers.add_parser('1')
>>> subparser1.add_argument('-x')
>>> subparser2 = subparsers.add_parser('2')
>>> subparser2.add_argument('y')
>>> parser.parse_args(['2', 'frobble'])
Namespace(subparser_name='2', y='frobble')
在 3.7 版中更改:新的* required *关键字参数。
FileType objects
-
- class *
argparse.
FileType
(* mode ='r', bufsize = -1 , encoding = None , errors = None *)
- FileType工厂创建可以传递给ArgumentParser.add_argument()类型参数的对象。具有FileType对象作为其类型的参数将以文件的形式打开命令行参数,这些文件具有所请求的模式,缓冲区大小,编码和错误处理(有关更多详细信息,请参见open()函数):
- class *
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--raw', type=argparse.FileType('wb', 0))
>>> parser.add_argument('out', type=argparse.FileType('w', encoding='UTF-8'))
>>> parser.parse_args(['--raw', 'raw.dat', 'file.txt'])
Namespace(out=<_io.TextIOWrapper name='file.txt' mode='w' encoding='UTF-8'>, raw=<_io.FileIO name='raw.dat' mode='wb'>)
FileType 对象了解伪参数'-'
,对于可读的FileType对象自动将其转换为sys.stdin
,对于可写的FileType对象则自动转换为sys.stdout
:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('infile', type=argparse.FileType('r'))
>>> parser.parse_args(['-'])
Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>)
3.4 版中的新Function:* encodings 和 errors *关键字参数。
Argument groups
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()方法接受* title 和 description *参数,这些参数可用于自定义此显示:
>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
>>> group1 = parser.add_argument_group('group1', 'group1 description')
>>> group1.add_argument('foo', help='foo help')
>>> group2 = parser.add_argument_group('group2', 'group2 description')
>>> group2.add_argument('--bar', help='bar help')
>>> parser.print_help()
usage: PROG [--bar BAR] foo
group1:
group1 description
foo foo help
group2:
group2 description
--bar BAR bar help
请注意,不在用户定义组中的所有参数都将返回到通常的“位置参数”和“可选参数”部分。
Mutual exclusion
ArgumentParser.
add_mutually_exclusive_group
(* required = False *)- 创建一个互斥的组。 argparse将确保在命令行上仅存在互斥组中的一个参数:
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> group = parser.add_mutually_exclusive_group()
>>> group.add_argument('--foo', action='store_true')
>>> group.add_argument('--bar', action='store_false')
>>> parser.parse_args(['--foo'])
Namespace(bar=True, foo=True)
>>> parser.parse_args(['--bar'])
Namespace(bar=False, foo=False)
>>> parser.parse_args(['--foo', '--bar'])
usage: PROG [-h] [--foo | --bar]
PROG: error: argument --bar: not allowed with argument --foo
add_mutually_exclusive_group()方法还接受一个* required *参数,以指示至少一个互斥参数是必需的:
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> group = parser.add_mutually_exclusive_group(required=True)
>>> group.add_argument('--foo', action='store_true')
>>> group.add_argument('--bar', action='store_false')
>>> parser.parse_args([])
usage: PROG [-h] (--foo | --bar)
PROG: error: one of the arguments --foo --bar is required
请注意,当前互斥的参数组不支持add_argument_group()的* title 和 description *参数。
Parser defaults
ArgumentParser.
set_defaults
(*** kwargs *)- 在大多数情况下,parse_args()返回的对象的属性将pass检查命令行参数和参数操作来完全确定。 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'
Printing help
在大多数典型应用程序中,parse_args()将负责格式化和打印所有用法或错误消息。但是,有几种格式化方法可用:
ArgumentParser.
print_usage
(* file = None *)- 打印有关如何在命令行上调用ArgumentParser的简要说明。如果* file *为
None
,则假定为sys.stdout。
- 打印有关如何在命令行上调用ArgumentParser的简要说明。如果* file *为
ArgumentParser.
print_help
(* file = None *)- 打印帮助消息,包括程序使用情况以及有关在ArgumentParser中注册的参数的信息。如果* file *为
None
,则假定为sys.stdout。
- 打印帮助消息,包括程序使用情况以及有关在ArgumentParser中注册的参数的信息。如果* file *为
这些方法也有一些变体,它们仅返回一个字符串而不是将其打印出来:
ArgumentParser.
format_usage
( )- 返回一个字符串,其中包含有关如何在命令行上调用ArgumentParser的简要说明。
ArgumentParser.
format_help
( )- 返回一个包含帮助消息的字符串,其中包括程序用法以及有关在ArgumentParser中注册的参数的信息。
Partial parsing
ArgumentParser.
parse_known_args
(* args = None , namespace = None *)
有时,一个脚本可能仅解析一些命令行参数,将其余的参数传递给另一个脚本或程序。在这些情况下,parse_known_args()方法可能会有用。它的工作方式与parse_args()相似,不同之处在于当存在其他参数时它不会产生错误。相反,它将返回包含填充的名称空间和剩余参数字符串列表的两个 Tuples。
>>> 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
Prefix matching规则适用于parse_known_args()
。解析器可能会消耗一个选项,即使它只是其已知选项之一的前缀,而不是将其保留在其余参数列表中。
自定义文件解析
ArgumentParser.
convert_arg_line_to_args
(* arg_line *)- 从文件中读取的参数(请参见ArgumentParser构造函数的* fromfile_prefix_chars *关键字参数)每行读取一个参数。 convert_arg_line_to_args()可以被覆盖以进行更高级的阅读。
此方法采用单个参数* arg_line *,这是从参数文件读取的字符串。它返回从该字符串解析的参数列表。从参数文件读取的每一行依次调用该方法一次。
该方法的一个有用替代是将每个以空格分隔的单词当作自变量的方法。下面的示例演示如何执行此操作:
class MyArgumentParser(argparse.ArgumentParser):
def convert_arg_line_to_args(self, arg_line):
return arg_line.split()
Exiting methods
ArgumentParser.
exit
(* status = 0 , message = None *)- 该方法终止程序,以指定的* status 退出,并在此之前输出 message *。用户可以重写此方法以不同方式处理这些步骤:
class ErrorCatchingArgumentParser(argparse.ArgumentParser):
def exit(self, status=0, message=None):
if status:
raise Exception(f'Exiting because of an error: {message}')
exit(status)
ArgumentParser.
error
(* message *)- 此方法将包括* message *的用法消息打印到标准错误,并以状态代码 2 终止程序。
Intermixed parsing
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 Function,如果使用了不受支持的Function,则会引发异常。特别是,不支持子解析器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()返回两个项目的 Tuples,其中包含已填充的名称空间和其余参数字符串的列表。如果还有剩余的未解析的参数字符串,则parse_intermixed_args()会引发错误。
3.7 版中的新Function。
升级 optparse 代码
最初,argparse模块曾try与optparse保持兼容性。但是,optparse很难透明地扩展,尤其是在支持新的nargs=
说明符和更好的用法消息所需的更改方面。当optparse中的大多数内容都被复制粘贴或用猴子修补时,try保持向后兼容性似乎不再可行。
argparse模块以多种方式对标准库optparse模块进行了改进,包括:
处理位置参数。
Supporting sub-commands.
允许使用其他选项前缀,例如
+
和/
。处理零个或多个和一个或多个样式参数。
产生更多有用的使用消息。
为自定义
type
和action
提供更简单的界面。
将所有optparse.OptionParser.add_option()个呼叫替换为ArgumentParser.add_argument()个呼叫。
将
(options, args) = parser.parse_args()
替换为args = parser.parse_args()
,并为位置参数添加其他ArgumentParser.add_argument()调用。请记住,以前在_上下文中称为options
的现在称为args
。使用parse_intermixed_args()而不是parse_args()代替optparse.OptionParser.disable_interspersed_args()。
将回调操作和
callback_*
关键字参数替换为type
或action
参数。将
type
关键字参数的字符串名称替换为相应的类型对象(例如,int,float,complex 等)。将
optparse.Values
替换为Namespace和optparse.OptionError
并将optparse.OptionValueError
替换为ArgumentError
。用标准 Python 语法用隐式参数(例如
%default
或%prog
)替换字符串,以使用字典来格式化字符串,即%(default)s
和%(prog)s
。用对
parser.add_argument('--version', action='version', version='<the version>')
的调用替换 OptionParser 构造函数version
的参数。