参考官方文档(python2.7):https://docs.python.org/2/library/argparse.html 欢迎转载???
目录
4.1 Option value syntax(选项值语法)
4.4 Argument abbreviations(prefix matching)参数缩写(前缀匹配)
5.8 Customizing file parsing(自定义文件解析)
argparse模块使得编写用户友好的命令行界面变得容易。程序定义了它需要的参数,argparse将找出如何从sys.argv中解析这些参数。argparse模块还自动生成帮助和使用消息,并在用户给出程序无效参数时发出错误。
1.例子
下面的代码是一个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'
下面几节将介绍这个示例。
1.1 创建一个parser
使用argparse的第一步是创建一个ArgumentParser对象:
>>> parser = argparse.ArgumentParser(description='Process some integers.')
ArgumentParser对象将保持所有的信息首先进入parse的命令行的Python数据类型。
1.2 添加 arguments
向ArgumentParser填充有关程序参数的信息是通过调用add_argument()方法完成的。通常,这些调用告诉ArgumentParser如何获取命令行上的字符串并将它们转换为对象。此信息在调用parse_args()时存储和使用。例如:
>>> parser.add_argument('integers', metavar='N', type=int, nargs='+',
... help='an integer for the accumulator')
>>> parser.add_argument('--sum', dest='accumulate', action='store_const',
... const=sum, default=max,
... help='sum the integers (default: find the max)')
稍后,调用parse_args()将返回一个具有两个属性(integers和accumulate)的对象。integers属性是一个或多个int的列表,如果--sum在命令行中指定,那么累加属性将是sum()函数,如果不指定,则为max()函数。
1.3 解析参数
ArgumentParser通过parse_args()方法解析参数。这将检查命令行,将每个参数转换为适当的类型,然后调用适当的操作。在大多数情况下,这意味着一个简单的Namespace对象将由从命令行解析出来的属性构建:
>>> parser.parse_args(['--sum', '7', '-1', '42'])
Namespace(accumulate=<built-in function sum>, integers=[7, -1, 42])
在脚本中,parse_args()通常没有参数调用,ArgumentParser将自动从sys.argv确定命令行参数。
2.ArgumentParser对象
class argparse.
ArgumentParser
(prog=None, usage=None, description=None, epilog=None, parents=[], formatter_class=argparse.HelpFormatter, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True)
创建一个新的ArgumentParser对象。所有参数都应该作为关键字参数传递。每个参数在下面都有它自己的更详细的描述,但是简而言之,它们是:
prog:程序的名称(默认:sys.argv [ 0 ]) |
usage:使用的字符串描述的程序使用(默认:由添加到parser的参数生成) |
description:显示在参数帮助之前的文本(默认:None) |
epilog:显示在参数帮助之后的文本(默认:None) |
parents:ArgumentParser对象的列表,其参数也应该包含其中 |
formatter_class:用于自定义帮助输出的类 |
prefix_chars:为可选参数前缀的字符集(默认值:-) |
fromfile_prefix_chars:前缀文件的字符集,应该从该文件读取其他参数(默认:None) |
argument_default:参数的全局默认值(默认:None) |
conflict_handler:解决冲突选项的策略(通常是不必要的) |
add_help:向解析器添加-h/--help选项(默认:True) |
以下各节描述如何使用这些内容。
2.1 prog
默认情况下,ArgumentParser对象使用sys.argv[0]来确定如何在帮助消息中显示程序的名称。这个默认值几乎总是需要的,因为它将使帮助消息与命令行上调用程序的方式匹配。例如,考虑一个名为myprogram.py的文件,其代码如下:
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--foo', help='foo help')
args = parser.parse_args()
此程序的帮助将myprogram.py显示为程序名(无论从何处调用程序):
$ python myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]
optional arguments:
-h, --help show this help message and exit
--foo FOO foo help
$ cd ..
$ python subdir/myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]
optional arguments:
-h, --help show this help message and exit
--foo FOO foo help
要更改此默认行为,可以使用prog=参数向ArgumentParser提供另一个值:
>>> parser = argparse.ArgumentParser(prog='myprogram')
>>> parser.print_help()
usage: myprogram [-h]
optional arguments:
-h, --help show this help message and exit
注意,无论是从sys.argv[0]还是从prog=参数确定的程序名,可使用 %(prog)s 格式说明符获得帮助消息。
>>> parser = argparse.ArgumentParser(prog='myprogram')
>>> parser.add_argument('--foo', help='foo of the %(prog)s program')
>>> parser.print_help()
usage: myprogram [-h] [--foo FOO]
optional arguments:
-h, --help show this help message and exit
--foo FOO foo of the myprogram program
2.2 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
可以使用 %(prog)s 格式说明符来填写使用消息中的程序名。
2.3 description
对ArgumentParser构造函数的大多数调用将使用description=关键字参数。这个参数简要描述了程序的功能和工作原理。在帮助消息中,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参数。
2.4 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= 文本在缺省情况下是行包装的,但是可以通过ArgumentParser的formatter_class参数来调整此行为。
2.5 parents
有时,几个解析器共享一组参数。与其重复这些参数的定义,还不如使用一个具有所有共享参数的解析器,并将其传递给 parents= 参数给ArgumentParser。parents= 参数获取ArgumentParser对象的列表,收集其中的所有位置和可选操作,并将这些操作添加到正在构造的ArgumentParser对象中:
>>> parent_parser = argparse.ArgumentParser(add_help=False)
>>> parent_parser.add_argument('--parent', type=int)
>>> foo_parser = argparse.ArgumentParser(parents=[parent_parser])
>>> foo_parser.add_argument('foo')
>>> foo_parser.parse_args(['--parent', '2', 'XXX'])
Namespace(foo='XXX', parent=2)
>>> bar_parser = argparse.ArgumentParser(parents=[parent_parser])
>>> bar_parser.add_argument('--bar')
>>> bar_parser.parse_args(['--bar', 'YYY'])
Namespace(bar='YYY', parent=None)
注意,大多数父解析器将指定add_help=False。否则,ArgumentParser将看到两个h/--help选项(一个在父选项中,一个在子选项中),并引发错误。
注意,在通过 parents= 解析器之前,必须对其进行完全初始化。如果在子解析器之后更改父解析器,则这些更改将不会反映在子解析器中。
2.6 formatter_class
ArgumentParser对象允许通过指定替代格式化类来定制帮助格式。目前,有三种这样的类:
class argparse.
RawDescriptionHelpFormatter
class argparse.
RawTextHelpFormatter
class argparse.
ArgumentDefaultsHelpFormatter
前两个允许对如何显示文本描述进行更多的控制,而最后一个则自动添加关于参数默认值的信息。默认情况下,ArgumentParser对象在命令行帮助消息中行包装 description 和 epilog 文本:
>>> parser = argparse.ArgumentParser(
... prog='PROG',
... description='''this description
... was indented weird
... but that is okay''',
... epilog='''
... likewise for this epilog whose whitespace will
... be cleaned up and whose words will be wrapped
... across a couple lines''')
>>> parser.print_help()
usage: PROG [-h]
this description was indented weird but that is okay
optional arguments:
-h, --help show this help message and exit
likewise for this epilog whose whitespace will be cleaned up and whose words
will be wrapped across a couple lines
将RawDescriptionHelpFormatter传递为formatter_class=表明 description 和 epilog 的格式已经正确,并且不应该被行包装:
>>> parser = argparse.ArgumentParser(
... prog='PROG',
... formatter_class=argparse.RawDescriptionHelpFormatter,
... description=textwrap.dedent('''\
... Please do not mess up this text!
... --------------------------------
... I have indented it
... exactly the way
... I want it
... '''))
>>> parser.print_help()
usage: PROG [-h]
Please do not mess up this text!
--------------------------------
I have indented it
exactly the way
I want it
optional arguments:
-h, --help show this help message and exit
RawTextHelpFormatter为各种帮助文本(包括参数描述)保留空格。然而,多个新行被替换为一行。如果希望保留多个空行,请在换行之间添加空格。
其他可用的格式化程序类,ArgumentDefaultsHelpFormatter,将对每一个默认的参数添加信息:
>>> parser = argparse.ArgumentParser(
... prog='PROG',
... formatter_class=argparse.ArgumentDefaultsHelpFormatter)
>>> parser.add_argument('--foo', type=int, default=42, help='FOO!')
>>> parser.add_argument('bar', nargs='*', default=[1, 2, 3], help='BAR!')
>>> parser.print_help()
usage: PROG [-h] [--foo FOO] [bar [bar ...]]
positional arguments:
bar BAR! (default: [1, 2, 3])
optional arguments:
-h, --help show this help message and exit
--foo FOO FOO! (default: 42)
2.7 prefix_chars
大多数命令行选项将使用 - 作为前缀,例如 -f/-foo。需要支持不同或附加前缀字符(例如 +f 或 /foo 选项)的解析器可以使用ArgumentParser构造函数的 prefix_chars= 参数指定它们:
>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='-+')
>>> parser.add_argument('+f')
>>> parser.add_argument('++bar')
>>> parser.parse_args('+f X ++bar Y'.split())
Namespace(bar='Y', f='X')
prefix_chars= 参数默认为“-”。提供不包括 - 将导致 -f/-foo 选项的字符集。
2.8 fromfile_prefix_chars
有时,例如,在处理特别长的参数列表时,将参数列表保存在文件中而不是在命令行中输入是有意义的。如果fromfile_prefix_chars= 参数被提供给ArgumentParser构造函数,那么以任何指定字符开始的参数将被视为文件,并将被它们包含的参数替换。例如:
>>> with open('args.txt', 'w') as fp:
... fp.write('-f\nbar')
>>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@')
>>> parser.add_argument('-f')
>>> parser.parse_args(['-f', 'foo', '@args.txt'])
Namespace(f='bar')
默认情况下,从文件读取的参数必须是每行一个(但也请参阅convert_arg_line_to_args()),并且被当作与命令行上的原始文件引用参数位于相同的位置来对待。因此,在上面的示例中,表达式['-f','foo','@args.txt']被认为等同于表达式['-f','foo','-f','bar']。
fromfile_prefix_chars= 参数默认为None,这意味着参数永远不会被当作文件引用。
2.9 argument_default
通常,参数缺省值是通过将缺省值传递给add_argument()或通过使用特定的一组 name-value 调用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()
2.10 conflict_handler
ArgumentParser对象不允许两个具有相同选项字符串的操作。默认情况下,如果尝试使用已经使用的选项字符串创建参数,则ArgumentParser对象引发异常:
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-f', '--foo', help='old foo help')
>>> parser.add_argument('--foo', help='new foo help')
Traceback (most recent call last):
..
ArgumentError: argument --foo: conflicting option string(s): --foo
有时(例如,当使用 parents ),简单地用相同的选项字符串覆盖任何旧的参数是有用的。为了获得这种行为,可以将值“resolve”提供给ArgumentParser的 confilct_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选项字符串被重写。
2.11 add_help
默认情况下,ArgumentParser对象添加一个选项,该选项仅显示解析器的帮助消息。例如,考虑一个名为myprogram.py的文件,其中包含以下代码:
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--foo', help='foo help')
args = parser.parse_args()
如果在命令行中提供-h或--help,则将打印ArgumentParser帮助:
$ python myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]
optional arguments:
-h, --help show this help message and exit
--foo FOO foo help
有时,禁用添加此帮助选项可能有用。这可以通过将False作为add_help= 的参数传递给ArgumentParser来实现:
>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
>>> parser.add_argument('--foo', help='foo help')
>>> parser.print_help()
usage: PROG [--foo FOO]
optional arguments:
--foo FOO foo help
帮助选项通常是 -h/--help。例外情况是,如果 prefix_chars= 被指定并且不包括 -,在这种情况下 -h 和 -help 不是有效的选项。在这种情况下,prefix_chars 中的第一个字符用于帮助选项的前缀:
>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='+/')
>>> parser.print_help()
usage: PROG [+h]
optional arguments:
+h, ++help show this help message and exit
3.add_argument()方法
ArgumentParser.
add_argument
(name or flags...[, action][, nargs][, const][, default][, type][, choices][, required][, help][, metavar][, dest])
定义应该如何解析单个命令行参数。每个参数在下面都有它自己的更详细的描述,但是简而言之,它们是:
name or flags:选项字符串的名称或列表,例如,foo或-f,--foo。 |
action:在命令行遇到此参数时要采取的基本操作类型。 |
nargs:应该使用的命令行参数的数量。 |
const:某些action和nargs选择所需的常数值。 |
default:如果命令行中没有参数,则默认生成的值。 |
type:命令行参数应该转换到的类型。 |
choices:参数允许值的容器。 |
required:是否可以省略命令行选项(仅是可选的)。 |
help:参数作用的简短描述。 |
metavar:使用消息中参数的名称。 |
dest:要添加到 parse_args() 返回的对象的属性的名称。 |
以下各节描述如何使用这些内容。
3.1 name or flags
add_argument()方法必须知道是否需要可选参数,如 -f 或 -foo,还是位置参数,如文件名列表。因此,传递给 add_argument()的第一个参数必须是一系列标志或简单的参数名称。例如,可以如下创建可选参数:
>>> parser.add_argument('-f', '--foo')
位置参数将如下创建:
>>> parser.add_argument('bar')
当调用parse_args()时,可选的参数将由 - 前缀标识,并且剩余的参数将认为是 positional:
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-f', '--foo')
>>> parser.add_argument('bar')
>>> parser.parse_args(['BAR'])
Namespace(bar='BAR', foo=None)
>>> parser.parse_args(['BAR', '--foo', 'FOO'])
Namespace(bar='BAR', foo='FOO')
>>> parser.parse_args(['--foo', 'FOO'])
usage: PROG [-h] [-f FOO] bar
PROG: error: too few arguments
3.2 action
ArgumentParser对象将命令行参数与操作关联。尽管大多数操作只是向parse_args()返回的对象添加一个属性,但是这些操作几乎可以对与它们相关联的命令行参数执行任何操作。action关键字参数指定应该如何处理命令行参数。提供的操作包括:
- 'store':这只是存储了参数的值。默认操作。例如:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.parse_args('--foo 1'.split())
Namespace(foo='1')
- 'store_const':这存储了const关键字参数指定的值。“store_const”操作通常与指定某种标志的可选参数一起使用。例如:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='store_const', const=42)
>>> parser.parse_args(['--foo'])
Namespace(foo=42)
- 'store_true' 和 'store_false':这些是用于分别存储值True和False的'store_const'的特殊情况。此外,它们分别创建False和True的默认值。例如:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='store_true') # default=False
>>> parser.add_argument('--bar', action='store_false') # default=True
>>> parser.add_argument('--baz', action='store_false') # default= True
>>> parser.parse_args('--foo --bar'.split())
# --foo --bar显示创建的值,其它参数显示默认值
Namespace(bar=False, baz=True, foo=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=[<type 'str'>, <type 'int'>])
- 'count':这将计算关键字参数发生的次数。例如,这对于增加冗长级别是有用的:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--verbose', '-v', action='count')
>>> parser.parse_args(['-vvv'])
Namespace(verbose=3)
- 'help':这将打印当前解析器中所有选项的完整帮助消息,然后退出。默认情况下,将自动向解析器添加帮助操作。有关如何创建输出的详细信息,请参见ArgumentParser。
- 'version':这将在 add_argument() 调用中得到 version= 关键参数,并在调用时打印版本信息并退出:
>>> import argparse
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--version', action='version', version='%(prog)s 2.0')
>>> parser.parse_args(['--version'])
PROG 2.0
还可以通过传递实现相同接口的Action子类或其他对象来指定任意操作。推荐的方法是扩展Action,覆盖 _call_ 方法和可选的_init_ 方法。
自定义操作的示例:
>>> class FooAction(argparse.Action):
... def __init__(self, option_strings, dest, nargs=None, **kwargs):
... if nargs is not None:
... raise ValueError("nargs not allowed")
... super(FooAction, self).__init__(option_strings, dest, **kwargs)
... def __call__(self, parser, namespace, values, option_string=None):
... print '%r %r %r' % (namespace, values, option_string)
... setattr(namespace, self.dest, values)
...
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action=FooAction)
>>> parser.add_argument('bar', action=FooAction)
>>> args = parser.parse_args('1 --foo 2'.split())
Namespace(bar=None, foo=None) '1' None
Namespace(bar='1', foo=None) '2' '--foo'
>>> args
Namespace(bar='1', foo='2')
更多细节,点击这里。
3.3 nargs
ArgumentParser对象通常将单个命令行参数与要采取的单个操作关联。nargs关键字参数将不同数量的命令行参数与单个操作关联。支持的值是:
- N(一个整数)。命令行中的N个参数将被收集到一个列表中。例如:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', nargs=2)
>>> parser.add_argument('bar', nargs=1)
>>> parser.parse_args('c --foo a b'.split())
Namespace(bar=['c'], foo=['a', 'b'])
注意,nargs=1产生一个项目的列表。这与缺省不同,缺省情况下,项本身生成。
- '?' 如果可能,一个参数将从命令行中消耗,并作为单个项生成。如果没有命令行参数,则将生成 default 默认值。注意,对于可选参数,还有另外一种情况—选项字符串存在,但是后面没有命令行参数。在这种情况下,将生成const的值。举例说明这一点:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', nargs='?', const='c', default='d')
>>> parser.add_argument('bar', nargs='?', default='d')
>>> parser.parse_args(['XX', '--foo', 'YY'])
Namespace(bar='XX', foo='YY')
>>> parser.parse_args(['XX', '--foo'])
Namespace(bar='XX', foo='c')
>>> parser.parse_args([])
Namespace(bar='d', foo='d')
nargs='?'的一个更常见的用法。允许可选的输入和输出文件:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('infile', nargs='?', type=argparse.FileType('r'),
... default=sys.stdin)
>>> parser.add_argument('outfile', nargs='?', type=argparse.FileType('w'),
... default=sys.stdout)
>>> parser.parse_args(['input.txt', 'output.txt'])
Namespace(infile=<open file 'input.txt', mode 'r' at 0x...>,
outfile=<open file 'output.txt', mode 'w' at 0x...>)
>>> parser.parse_args([])
Namespace(infile=<open file '<stdin>', mode 'r' at 0x...>,
outfile=<open file '<stdout>', mode 'w' at 0x...>)
- ‘*’。所有存在的命令行参数都被收集到一个列表中。注意,使用nargs='*'具有多个位置参数通常没有多大意义,但是使用nargs='*'可以有多个可选参数。例如:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', nargs='*')
>>> parser.add_argument('--bar', nargs='*')
>>> parser.add_argument('baz', nargs='*')
>>> parser.parse_args('a b --foo x y --bar 1 2'.split())
Namespace(bar=['1', '2'], baz=['a', 'b'], foo=['x', 'y'])
- “+”。与“*”一样,所有存在的命令行参数都被收集到一个列表中。此外,如果没有至少一个命令行参数存在,将生成错误消息。例如:
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', nargs='+')
>>> parser.parse_args(['a', 'b'])
Namespace(foo=['a', 'b'])
>>> parser.parse_args([])
usage: PROG [-h] foo [foo ...]
PROG: error: too few arguments
- argparse.REMAINDER 所有剩余的命令行参数都被收集到一个列表中。这对于向其他命令行实用程序分派的命令行实用程序通常很有用:
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo')
>>> parser.add_argument('command')
>>> parser.add_argument('args', nargs=argparse.REMAINDER)
>>> print parser.parse_args('--foo B cmd --arg1 XX ZZ'.split())
Namespace(args=['--arg1', 'XX', 'ZZ'], command='cmd', foo='B')
如果没有提供nargs关键字参数,则使用的参数数量由操作决定。一般来说,这意味着将使用单个命令行参数,并生成单个项(而不是列表)。
3.4 const
add_argument()的const参数用于保存不从命令行读取但各种ArgumentParser操作所需的常量值。它最常用的两个用途是:
- 当 action='store_const' 或 action='append_const' 调用 add_argument() 时。这些操作将 const 值添加到 parse_args() 返回的对象的属性之一。有关示例,请参阅 action 描述。
- 当使用选项字符串(如 -f 或 --foo)和 nargs='?' 调用add_argument()时,这将创建一个可选的参数,后面跟着零个或一个命令行参数。在解析命令行时,如果遇到选项字符串,并且后面没有命令行参数,那么将采用const的值。有关示例,请参阅nargs描述。
对于“store_const”和“append_const”操作,必须给出const关键字参数。对于其他操作,默认为None。
3.5 default
在命令行中可以省略所有可选参数和一些位置参数。add_argument()的default关键字参数,其值默认为None,指定如果没有命令行参数,应该使用什么值。对于可选参数,当命令行中不存在选项字符串时使用默认值:
>>> 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 等于 ? 的位置参数或者 * ,当不存在命令行参数时使用默认值:
>>> 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')
3.6 type
默认情况下,ArgumentParser对象以简单字符串的形式读取命令行参数。但是,命令行字符串通常应该被解释为另一种类型,如float 或int. add_argument() 的 type 关键字参数允许执行任何必要的类型检查和类型转换。通用内置类型和函数可以直接用作类型参数的值:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', type=int)
>>> parser.add_argument('bar', type=file)
>>> parser.parse_args('2 temp.txt'.split())
Namespace(bar=<open file 'temp.txt', mode 'r' at 0x...>, foo=2)
有关何时将类型参数应用于默认参数的信息,请参阅有关 default 关键字参数的部分。
为了简化各种类型的文件的使用,argparse 模块提供了工厂 FileType,它接受文件对象的 mode= 和 bufsize= 参数。例如,FileType('w') 可用于创建可写文件:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('bar', type=argparse.FileType('w'))
>>> parser.parse_args(['out.txt'])
Namespace(bar=<open file 'out.txt', mode 'w' at 0x...>)
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=xrange(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.
3.7 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对象、定制容器等都受到支持。
3.8 required
通常,argparse 模块假定 -f 和 -bar 等标记指示可选参数,这些参数在命令行中总是可以省略。为了生成所需的选项,可以为required=关键字参数以 add_argument() 指定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
如示例所示,如果一个选项被标记为必需的,那么parse_args()将在命令行中不存在该选项时报告错误。
注意:Required选项通常被认为是不好的形式,因为用户希望选项是可选的,因此应该尽可能避免使用它们。
3.9 help
help 值是一个字符串,包含参数的简要描述。当用户请求 help 时(通常在命令行中使用 -h 或 --help ),这些 help 描述将随每个参数一起显示:
>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('--foo', action='store_true',
... help='foo the bars before frobbling')
>>> parser.add_argument('bar', nargs='+',
... help='one of the bars to be frobbled')
>>> parser.parse_args(['-h'])
usage: frobble [-h] [--foo] bar [bar ...]
positional arguments:
bar one of the bars to be frobbled
optional arguments:
-h, --help show this help message and exit
--foo foo the bars before frobbling
help 字符串可以包括各种格式说明符,以避免重复程序名或参数默认值。可用的指定符包括程序名、%(prog)s 和 add_argument() 的大多数关键字参数,例如 %(default)s、%(type)s 等:
>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('bar', nargs='?', type=int, default=42,
... help='the bar to %(prog)s (default: %(default)s)')
>>> parser.print_help()
usage: frobble [-h] [bar]
positional arguments:
bar the bar to frobble (default: 42)
optional arguments:
-h, --help show this help message and exit
argparse 支持通过将 help 值设置为 argparse.SUPPRESS:
>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('--foo', help=argparse.SUPPRESS)
>>> parser.print_help()
usage: frobble [-h]
optional arguments:
-h, --help show this help message and exit
3.10 metavar
当 ArgumentParser 生成帮助消息时,它需要一些方法来引用每个预期的参数。默认情况下,ArgumentParser 对象使用 dest 值作为每个对象的“name”。默认情况下,对于位置参数操作,直接使用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 元变量提供元组为每个参数指定不同的显示:
>>> 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
3.11 dest
大多数ArgumentParser操作都会添加一些值作为parse_args()返回的对象的属性。此属性的名称由add_argument()的dest关键字参数确定。对于位置参数操作,通常将dest作为第一个参数提供给add_argument():
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('bar')
>>> parser.parse_args(['XXX'])
Namespace(bar='XXX')
对于可选的参数操作,dest的值通常从选项字符串推断出来。ArgumentParser 通过获取第一个长选项字符串并删除初始--string,生成dest的值。如果没有提供长选项字符串,则通过剥离初始字符,从第一个短选项字符串派生dest。任何内部-characters将被转换为_characters,以确保字符串是有效的属性名。下面的示例说明了这种行为:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('-f', '--foo-bar', '--foo')
_StoreAction(option_strings=['-f', '--foo-bar', '--foo'], dest='foo_bar', nargs=None, default=None, type=None, choices=None, help=None, metavar=None)
>>> parser.add_argument('-x', '-y')
_StoreAction(option_strings=['-x', '-y'], dest='-x', nargs=None, default=None, type=None, choices=None, help=None, metavar=None)
>>> 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')
3.12 Action 类
Action类实现Action API,该API是可调用的,返回从命令行处理参数的可调用。遵循这个API的任何对象都可以作为动作参数传递给 add_argument()。
class argparse.
Action
(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)
操作对象由ArgumentParser用于表示从命令行中的一个或多个字符串解析单个参数所需的信息。Action类必须接受两个位置参数以及传递给ArgumentParser.add_argument()的任何关键字参数,但action本身除外。
Action实例(或对action参数可调用的返回值)应该具有属性“dest”,“option_strings”,“default”,“type”,“required”,“help”等定义。确保定义这些属性的最简单方法是调用Action._init_。
action 实例应该是可调用的,因此子类必须覆盖_call_方法,该方法应该接受四个参数:
- parser:包含此操作的ArgumentParser对象。
- namespace:将由parse_args()返回的Namespace对象。大多数操作使用setattr()向该对象添加属性。
- values:应用任何类型转换的相关命令行参数。使用add_argument()的 type 关键字参数指定类型转换。
- option_string:用于调用此操作的选项字符串。optipn_string参数是可选的,如果操作与位置参数相关联,则将不存在。
_call_方法可以执行任意操作,但通常将基于dest和values设置 namespace 上的属性。
4.parse_args()方法
ArgumentParser.
parse_args
(args=None, namespace=None)
将参数字符串转换为对象并将它们作为名称空间的属性分配。返回填充的命名空间。
前面对add_argument()的调用准确地确定了创建了哪些对象以及如何分配它们。有关详细信息,请参阅add_argument()的文档。
- args:要解析的字符串列表。默认值取自sys.argv。
- namespace:获取属性的对象。默认值是一个新的空Namespace对象。
4.1 Option value syntax(选项值语法)
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')
4.2 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
4.3 Arguments containing -
parse_args()方法试图在用户明显犯错时给出错误,但有些情况本质上是模糊的。例如,命令行参数-1可以是指定选项的尝试,也可以是提供位置参数的尝试。parse_args()方法在这里是谨慎的:位置参数可能仅从 - 如果它们看起来像负数,并且解析器中没有看起来像负数的选项:
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x')
>>> parser.add_argument('foo', nargs='?')
>>> # no negative number options, so -1 is a positional argument
>>> parser.parse_args(['-x', '-1'])
Namespace(foo=None, x='-1')
>>> # no negative number options, so -1 and -5 are positional arguments
>>> parser.parse_args(['-x', '-1', '-5'])
Namespace(foo='-5', x='-1')
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-1', dest='one')
>>> parser.add_argument('foo', nargs='?')
>>> # negative number options present, so -1 is an option
>>> parser.parse_args(['-1', 'X'])
Namespace(foo=None, one='X')
>>> # negative number options present, so -2 is an option
>>> parser.parse_args(['-2'])
usage: PROG [-h] [-1 ONE] [foo]
PROG: error: no such option: -2
>>> # negative number options present, so both -1s are options
>>> parser.parse_args(['-1', '-1'])
usage: PROG [-h] [-1 ONE] [foo]
PROG: error: argument -1: expected one argument
如果位置参数必须以 '-' 开始并且看起来不像负数,则可以插入伪参数'--',该伪参数告诉 parse_args()之后的所有内容都是位置参数:
>>> parser.parse_args(['--', '-f'])
Namespace(foo='-f', one=None)
4.4 Argument abbreviations(prefix matching)参数缩写(前缀匹配)
parse_args()方法允许将长选项缩写为前缀,如果缩写是明确的(前缀匹配唯一的选项):
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-bacon')
>>> parser.add_argument('-badger')
>>> parser.parse_args('-bac MMM'.split())
Namespace(bacon='MMM', badger=None)
>>> parser.parse_args('-bad WOOD'.split())
Namespace(bacon=None, badger='WOOD')
>>> parser.parse_args('-ba BA'.split())
usage: PROG [-h] [-bacon BACON] [-badger BADGER]
PROG: error: ambiguous option: -ba could match -badger, -bacon
对于可能产生多个选项的参数,将产生一个错误。
4.5 Beyond sys.argv
有时,除了sys.argv.的参数之外,使用ArgumentParser解析参数可能有用。这可以通过将一个字符串列表传递给parse_args()来实现。这对于交互式提示符下的测试很有用:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument(
... 'integers', metavar='int', type=int, choices=xrange(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])
4.6 Namespace 对象
class argparse.
Namespace
parse_args()默认情况下用于创建对象保持属性并返回它的简单类。
这个类很简单,只是一个具有可读字符串表示的对象子类。如果希望具有类似的属性视图,可以使用标准Python习惯用法vars():
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> args = parser.parse_args(['--foo', 'BAR'])
>>> vars(args)
{'foo': 'BAR'}
让ArgumentParser为已经存在的对象而不是新的Namespace对象分配属性也是有用的。这可以通过指定namespace=关键字参数来实现:
>>> class C(object):
... pass
...
>>> c = C()
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.parse_args(args=['--foo', 'BAR'], namespace=c)
>>> c.foo
'BAR'
5.其它
5.1 sub-commands
ArgumentParser.
add_subparsers
([title][, description][, prog][, parser_class][, action][, option_string][, dest][, help][, metavar])
许多程序将它们的功能分成许多子命令,例如,svn 程序可以调用子命令,如svn checkout、svn update和svn commit。当程序需要不同类型命令行参数的几个不同函数执行时,以这种方式分割功能可能是一个特别好的主意。ArgumentParser 支持使用add_subparsers() 方法创建这样的子命令。add_subparsers() 方法通常不带参数地调用,并返回一个特殊操作对象。这个对象有一个方法add_parser(),它接受命令名和任何 ArgumentParser 构造函数参数,并返回一个 ArgumentParser 对象,该对象可以像往常一样修改。
参数描述:
- title-帮助输出中的子解析器组的标题;默认情况下,如果提供了描述,则为“subcommands”,否则使用title作为位置参数
- description-在帮助输出中对子解析器组的描述,默认情况下为None
- prog-使用信息,该信息将在子命令帮助下显示,默认情况下是程序的名称和子解析器参数之前的任何位置参数
- parser_class-类用于创建子解析器实例,默认情况下是当前解析器的类(例如,ArgumentParser)
- action-当在命令行遇到此参数时要采取的基本操作类型
- dest-存储子命令名的属性的名称;默认情况下不存储任何值
- 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属性。
类似地,当从子解析器请求帮助消息时,将只打印该特定解析器的帮助。帮助消息将不包括父解析器或兄弟解析器消息。(但是,可以通过向 add_parser() 提供 help= 参数来给出每个子解析器命令的帮助消息)。
>>> parser.parse_args(['--help'])
usage: PROG [-h] [--foo] {a,b} ...
positional arguments:
{a,b} sub-command help
a a help
b b help
optional arguments:
-h, --help show this help message and exit
--foo foo help
>>> parser.parse_args(['a', '--help'])
usage: PROG a [-h] bar
positional arguments:
bar bar help
optional arguments:
-h, --help show this help message and exit
>>> parser.parse_args(['b', '--help'])
usage: PROG b [-h] [--baz {X,Y,Z}]
optional arguments:
-h, --help show this help message and exit
--baz {X,Y,Z} baz help
add_subparsers()方法还支持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_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')
5.2 FileType objects
class argparse.
FileType
(mode='r', bufsize=None)
FileType工厂创建可以传递给ArgumentParser.add_argument()的类型参数的对象。具有FileType对象作为其类型的参数将打开命令行参数,作为具有所请求模式和缓冲区大小的文件:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--output', type=argparse.FileType('wb', 0))
>>> parser.parse_args(['--output', 'out'])
Namespace(output=<open file 'out', mode 'wb' at 0x...>)
FileType对象理解伪参数“-”,并自动将其转换为可读FileType对象的sys.stdin和可写FileType对象的sys.stdout:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('infile', type=argparse.FileType('r'))
>>> parser.parse_args(['-'])
Namespace(infile=<open file '<stdin>', mode 'r' at 0x...>)
5.3 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()方法返回一个参数组对象,该对象具有与常规ArgumentParser相同的add_argument()方法。当向组中添加参数时,解析器像对待普通参数一样对待它,但是将参数显示在单独的组中以获取帮助消息。add_argument_group()方法接受可用于定制此显示的标题和描述参数:
>>> 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
注意,任何不在用户定义组中的参数都将返回到通常的“位置参数”和“可选参数”部分。
5.4 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_.ve_group()方法还接受所需的参数,以指示需要至少一个互斥参数:
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> group = parser.add_mutually_exclusive_group(required=True)
>>> group.add_argument('--foo', action='store_true')
>>> group.add_argument('--bar', action='store_false')
>>> parser.parse_args([])
usage: PROG [-h] (--foo | --bar)
PROG: error: one of the arguments --foo --bar is required
注意,当前互斥参数组不支持add_argument_group()的标题和描述参数。
5.5 Parser defaults
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'
5.6 Printing help(打印帮助)
在大多数典型应用程序中,parse_args()将负责格式化和打印任何使用或错误消息。然而,有几种格式化方法可用:
ArgumentParser.
print_usage
(file=None)
在命令行上打印如何调用ArgumentParser的简要说明。如果文件为None,则假定为sys.stdout。
ArgumentParser.
print_help
(file=None)
打印帮助消息,包括程序使用情况和在ArgumentParser中注册的参数信息。如果文件为None,则假定为sys.stdout。
还有这些方法的变体,只是返回一个字符串而不是打印它:
ArgumentParser.
format_usage
()
返回一个字符串,该字符串包含如何在命令行上调用ArgumentParser的简要描述。
ArgumentParser.
format_help
()
返回包含帮助消息的字符串,包括程序使用情况和关于向ArgumentParser注册的参数的信息。
5.7 Partial parsing(部分解析)
ArgumentParser.
parse_known_args
(args=None, namespace=None)
有时,脚本可能只解析一些命令行参数,将剩余的参数传递给另一个脚本或程序。在这些情况下,parse_known_args()方法很有用。它的工作方式与parse_args()非常相似,只是当存在额外的参数时它不会产生错误。相反,它返回一个包含填充的名称空间和剩余参数字符串列表的两个项元组。
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='store_true')
>>> parser.add_argument('bar')
>>> parser.parse_known_args(['--foo', '--badger', 'BAR', 'spam'])
(Namespace(bar='BAR', foo=True), ['--badger', 'spam'])
警告
前缀匹配规则应用于parse_known_args()。解析器可能使用一个选项,即使它只是其一个已知选项的前缀,而不是将其保留在剩余的参数列表中。
5.8 Customizing file parsing(自定义文件解析)
ArgumentParser.
convert_arg_line_to_args
(arg_line)
从文件中读取的参数(参见 ArgumentParser 构造函数的 from file_prefix_chars 关键字参数)每行读取一个参数。convert_arg_line_to_args()可以重写,以便进行更随意的读取。
此方法采用单个参数 arg_line,该参数 arg_line 是从参数文件中读取的字符串。它返回从该字符串解析的参数列表。按照顺序,从参数文件中读取的每行调用该方法一次。
此方法的一个有用的重写是将每个空格分隔的单词作为参数:
def convert_arg_line_to_args(self, arg_line):
return arg_line.split()
5.9 Exiting methods(退出方法)
ArgumentParser.
exit
(status=0, message=None)
此方法终止程序,以指定的状态退出,如果给定,则在此之前打印消息。
ArgumentParser.
error
(message)
此方法将包括该消息的使用消息打印到标准错误,并以状态码 2 终止程序。
6.改进 optparse 代码
最初,argparse模块试图保持与optparse的兼容性。然而,optparse很难透明地扩展,特别是对于支持新的nargs= 说明符和更好的使用消息所需的更改。当optparse中的大多数内容都被复制粘贴或猴子补丁时,试图保持向后兼容性似乎不再实用。
argparse模块以多种方式改进了标准库optparse模块,包括:
- 处理位置参数。
- 支持子命令。
- 允许其他选项前缀,如+和/。
- 处理零个或多个以及一个或多个样式参数。
- 产生更多信息用法消息。
- 为自定义类型和操作提供更简单的接口。
从optparse到argparse的部分升级路径:
- Replace all
optparse.OptionParser.add_option()
calls withArgumentParser.add_argument()
calls. - Replace
(options, args) = parser.parse_args()
withargs = parser.parse_args()
and add additionalArgumentParser.add_argument()
calls for the positional arguments. Keep in mind that what was previously calledoptions
, now in theargparse
context is calledargs
. - Replace
optparse.OptionParser.disable_interspersed_args()
by settingnargs
of a positional argument to argparse.REMAINDER, or useparse_known_args()
to collect unparsed argument strings in a separate list. - Replace callback actions and the
callback_*
keyword arguments withtype
oraction
arguments. - Replace string names for
type
keyword arguments with the corresponding type objects (e.g. int, float, complex, etc). - Replace
optparse.Values
withNamespace
andoptparse.OptionError
andoptparse.OptionValueError
withArgumentError
. - Replace strings with implicit arguments such as
%default
or%prog
with the standard Python syntax to use dictionaries to format strings, that is,%(default)s
and%(prog)s
. - Replace the OptionParser constructor
version
argument with a call toparser.add_argument('--version', action='version', version='<the version>')
.