[python] argparse — 命令行选项、参数和子命令的解析器
版本2.7 中新引入。
Lib/argparse.py
argparse模块还会自动生成帮助和使用信息并且当用户赋给程序非法的参数时产生错误信息。
15.4.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)
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'
下面的部分将带你步步深入这个示例。
15.4.1.1. 创建一个解析器
ArgumentParser对象:
>>>
>>> parser = argparse.ArgumentParser(description='Process some integers.')
ArgumentParser对象会保存把命令行解析成Python数据类型所需要的所有信息。
15.4.1.2. 添加参数
例如:
>>>
>>> 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)')
max()函数。
15.4.1.3. 解析参数
Namespace对象。
>>>
>>> parser.parse_args(['--sum', '7', '-1', '42']) Namespace(accumulate=<built-in function sum>, integers=[7, -1, 42])
sys.argv自动确定命令行参数。
15.4.2. ArgumentParser 对象
- ],formatter_class=argparse.HelpFormatter, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None,conflict_handler='error', add_help=True)
下面有对每个参数各自详细的描述,但是简短地讲它们是:
- prog - sys.argv[0])
- usage - 描述程序用法的字符串(默认:从解析器的参数生成)
- description - 参数帮助信息之前的文本(默认:空)
- epilog - 参数帮助信息之后的文本(默认:空)
- parents - ArgumentParser 对象的一个列表,这些对象的参数应该包括进去
- formatter_class - 定制化帮助信息的类
- prefix_chars - 可选参数的前缀字符集(默认:‘-‘)
- fromfile_prefix_chars - None)
- argument_default - None)
- conflict_handler - 解决冲突的可选参数的策略(通常没有必要)
- add_help - True)
下面的小节描述这些参数如何使用。
15.4.2.1. prog 参数
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提供另外一个值:
>>>
>>> parser = argparse.ArgumentParser(prog='myprogram') >>> parser.print_help() usage: myprogram [-h] optional arguments: -h, --help show this help message and exit
%(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
15.4.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
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格式指示符替代程序的名字。
15.4.2.3. 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参数。
15.4.2.4. epilog 参数
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
formatter_class参数调整这个行为。
15.4.2.5. parents 参数
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)
-h/--help 选项(一个在父解析器中,一个在子解析器中)并引发一个错误。
注意
如果在子解析器之后你改变了父解析器,这些改变不会反映在子解析器中。
15.4.2.6. formatter_class 参数
当前,有三个种这样的类:
- RawDescriptionHelpFormatter
- RawTextHelpFormatter
- ArgumentDefaultsHelpFormatter
前两个在文本信息如何显示上允许更多控制,最后一个会自动添加关于参数默认值的信息。
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
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)
15.4.2.7. prefix_chars 参数
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')
-f/--foo选项。
15.4.2.8. fromfile_prefix_chars 参数
例如:
>>>
>>> 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')
'bar']。
None,意味着参数永远不会被当做文件。
15.4.2.9. argument_default 参数
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()
15.4.2.10. conflict_handler 参数
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
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
--foo选项字符串被覆盖。
15.4.2.11. add_help 参数
myprogram.py的文件:
import argparse parser = argparse.ArgumentParser() parser.add_argument('--foo', help='foo help') args = parser.parse_args()
--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
add_help=参数实现:
>>>
>>> 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
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
15.4.3. add_argument() 方法
- ArgumentParser.add_argument(name or flags...[, action][, nargs][, const][, default][, type][, choices][, required][, help][, metavar][, dest])
下面每个参数有它们自己详细的描述,简单地讲它们是:
下面的小节描述这些参数如何使用。
15.4.3.1. name 或 flags 参数
例如,一个可选的参数可以像这样创建:
>>>
>>> parser.add_argument('-f', '--foo')
而一个位置参数可以像这样创建:
>>>
>>> parser.add_argument('bar')
- 前缀标识,剩余的参数将被假定为位置参数:
>>>
>>> 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
15.4.3.2. action 参数
支持的动作有:
例如:
>>>
>>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo') >>> parser.parse_args('--foo 1'.split()) Namespace(foo='1')
例如:
>>>
>>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo', action='store_const', const=42) >>> parser.parse_args('--foo'.split()) Namespace(foo=42)
例如:
>>>
>>> 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(bar=False, baz=True, foo=True)
示例用法:
>>>
>>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo', action='append') >>> parser.parse_args('--foo 1 --foo 2'.split()) Namespace(foo=['1', '2'])
例如:
>>>
>>> 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'>])
例如,这可用于增加详细的级别:
>>>
>>> parser = argparse.ArgumentParser() >>> parser.add_argument('--verbose', '-v', action='count') >>> parser.parse_args('-vvv'.split()) Namespace(verbose=3)
ArgumentParser以得到如何生成输出信息。
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
__call__方法应该接受四个参数:
- parser - 包含该动作的ArgumentParser对象。
- namespace - Namespace对象。大部分动作会给该对象添加一个属性。
- values - type关键字参数指定。)
- option_string - option_string参数是可选的,如果动作关联的位置参数将不会出现。
自定义动作的例子:
>>>
>>> class FooAction(argparse.Action): ... 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')
15.4.3.3. nargs 参数
它支持的值有:
例如:
>>>
>>> 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'])
这和默认的行为是不一样的,默认情况下生成的是元素自己。
用一些例子加以解释:
>>>
>>> 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'.split()) Namespace(bar='XX', foo='YY') >>> parser.parse_args('XX --foo'.split()) Namespace(bar='XX', foo='c') >>> parser.parse_args(''.split()) 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...>)
例如:
>>>
>>> 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'.split()) Namespace(foo=['a', 'b']) >>> parser.parse_args(''.split()) usage: PROG [-h] foo [foo ...] PROG: error: too few arguments
这通常用于命令行工具分发命令到其它命令行工具:
>>>
>>> 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')
通常这意味着将读取一个命令行参数并产生一个元素(不是一个列表)。
15.4.3.4. const 参数
它的两个最常见的用法是:
- action的描述。
- nargs的描述。
None。
15.4.3.5. default 参数
default的值用于选项字符串没有出现在命令行中的时候:
>>>
>>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo', default=42) >>> parser.parse_args('--foo 2'.split()) Namespace(foo='2') >>> parser.parse_args(''.split()) Namespace(foo=42)
否则,解析器就使用其原始值:
>>>
>>> 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)
default在没有其命令行参数时使用:
>>>
>>> parser = argparse.ArgumentParser() >>> parser.add_argument('foo', nargs='?', default=42) >>> parser.parse_args('a'.split()) Namespace(foo='a') >>> parser.parse_args(''.split()) 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')
15.4.3.6. type 参数
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)
type参数应用与默认参数的信息。
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'.split()) Namespace(foo=9) >>> parser.parse_args('7'.split()) 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'.split()) Namespace(foo=7) >>> parser.parse_args('11'.split()) usage: PROG [-h] {5,6,7,8,9} PROG: error: argument foo: invalid choice: 11 (choose from 5, 6, 7, 8, 9)
choices一节。
15.4.3.7. choices 参数
当解析命令行时,将检查参数的值,如果参数不是一个可接受的值则显示一个错误信息:
>>>
>>> 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指出的类型相匹配:
>>>
>>> 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)
set对象以及自定义的容器等等都支持。
15.4.3.8. 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
parse_args() 将报告一个错误。
注意
Required 选项一般情况下认为是不好的形式因为用户期望选项 是可选 的,因此应该尽可能避免这种形式。
15.4.3.9. 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'.split()) 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
%(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支持隐藏特定选项的帮助:
>>>
>>> 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
15.4.3.10. metavar 参数
一个例子:
>>>
>>> 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
dest的值决定。
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
15.4.3.11. dest 参数
add_argument():
>>>
>>> parser = argparse.ArgumentParser() >>> parser.add_argument('bar') >>> parser.parse_args('XXX'.split()) Namespace(bar='XXX')
下面的实例解释了这个行为:
>>>
>>> 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')
15.4.4. parse_args() 方法
- ArgumentParser.parse_args(args=None, namespace=None)
返回构成的命名空间。
add_argument()的文档。
Namespace对象用于保存属性。
15.4.4.1. 可选值的语法
最简单的方法是,将选项和它的值以两个分开的参数传递:
>>>
>>> parser = argparse.ArgumentParser(prog='PROG') >>> parser.add_argument('-x') >>> parser.add_argument('--foo') >>> parser.parse_args('-x X'.split()) Namespace(foo=None, x='X') >>> parser.parse_args('--foo FOO'.split()) Namespace(foo='FOO', x=None)
=分隔它们:
>>>
>>> parser.parse_args('--foo=FOO'.split()) Namespace(foo='FOO', x=None)
对于短选项(长度只有一个字符的选项),选项及其值可以连在一起:
>>>
>>> parser.parse_args('-xX'.split()) 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'.split()) Namespace(x=True, y=True, z='Z')
15.4.4.2. 非法的参数
当它遇到此类错误时,会退出并跟随用法信息一起打印出错误:
>>>
>>> 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
-
-开始:
>>>
>>> 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)
15.4.4.4. 参数的缩写(前缀匹配)
parse_args()方法允许长选项简写成一个前缀,如果简写的形式没有歧义(前缀只匹配唯一的一个选项):
>>>
>>> parser = argparse.ArgumentParser(prog='PROG') >>> parser.add_argument('-bacon') >>> parser.add_argument('-badger') >>> parser.parse_args('-bac MMM'.split()) Namespace(bacon='MMM', badger=None) >>> parser.parse_args('-bad WOOD'.split()) Namespace(bacon=None, badger='WOOD') >>> parser.parse_args('-ba BA'.split()) usage: PROG [-h] [-bacon BACON] [-badger BADGER] PROG: error: ambiguous option: -ba could match -badger, -bacon
如果参数可能匹配多个选项则生成一个错误信息。
sys.argv
这在交互式命令行中测试时很有用:
>>>
>>> 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'.split()) Namespace(accumulate=<built-in function sum>, integers=[1, 2, 3, 4])
15.4.4.6. Namespace 对象
- Namespace
parse_args() 默认使用的简单的类,用于创建一个保存属性的对象并返回该对象。
vars():
>>>
>>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo') >>> args = parser.parse_args(['--foo', 'BAR']) >>> vars(args) {'foo': 'BAR'}
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'
15.4.5. 其它实用工具
15.4.5.1. 子命令
- ArgumentParser.add_subparsers([title][, description][, prog][, parser_class][, action][, option_string][, dest][, help][,metavar])
ArgumentParser对象。
参数的描述:
- title - 在输出的帮助中子解析器组的标题;默认情况下,如果提供description参数则为“subcommands”,否则使用位置参数的标题
- description - 在输出的帮助中子解析器组的描述,默认为None
- prog - 与子命令的帮助一起显示的使用帮助信息,默认为程序的名字和子解析器参数之前的所有位置参数
- parser_class - 用于创建子解析器实例的类,默认为当前的解析器(例如ArgumentParser)
- dest - 子命令的名字应该存储的属性名称;默认为None且不存储任何值
- 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)
baz 属性。
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
例如:
>>>
>>> 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
例如:
>>>
>>> # 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))
add_subparsers() 就可以:
>>>
>>> parser = argparse.ArgumentParser() >>> subparsers = parser.add_subparsers(dest='subparser_name') >>> subparser1 = subparsers.add_parser('1') >>> subparser1.add_argument('-x') >>> subparser2 = subparsers.add_parser('2') >>> subparser2.add_argument('y') >>> parser.parse_args(['2', 'frobble']) Namespace(subparser_name='2', y='frobble')
15.4.5.2. FileType 对象
- FileType(mode='r', bufsize=None)
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对象:
>>>
>>> parser = argparse.ArgumentParser() >>> parser.add_argument('infile', type=argparse.FileType('r')) >>> parser.parse_args(['-']) Namespace(infile=<open file '<stdin>', mode 'r' at 0x...>)
15.4.5.3. Argument groups
- ArgumentParser.add_argument_group(title=None, description=None)
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()方法接受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
注意任何没有加入到你自定义的分组中的参数仍将放在通常的“位置参数”和“可选参数”部分。
15.4.5.4. 互斥分组
- ArgumentParser.add_mutually_exclusive_group(required=False)
argparse将确保互斥分组中的一个参数出现在命令行上:
>>>
>>> parser = argparse.ArgumentParser(prog='PROG') >>> group = parser.add_mutually_exclusive_group() >>> group.add_argument('--foo', action='store_true') >>> group.add_argument('--bar', action='store_false') >>> parser.parse_args(['--foo']) Namespace(bar=True, foo=True) >>> parser.parse_args(['--bar']) Namespace(bar=False, foo=False) >>> parser.parse_args(['--foo', '--bar']) usage: PROG [-h] [--foo | --bar] PROG: error: argument --bar: not allowed with argument --foo
add_mutually_exclusive_group()接受一个required 参数,用于指示互斥分组中至少有一个参数是必需的:
>>>
>>> parser = argparse.ArgumentParser(prog='PROG') >>> group = parser.add_mutually_exclusive_group(required=True) >>> group.add_argument('--foo', action='store_true') >>> group.add_argument('--bar', action='store_false') >>> parser.parse_args([]) usage: PROG [-h] (--foo | --bar) PROG: error: one of the arguments --foo --bar is required
add_argument_group()的title和description 参数。
15.4.5.5. 解析器的默认值
- ArgumentParser.set_defaults(**kwargs)
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)
set_defaults()设定:
>>>
>>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo', default='badger') >>> parser.get_default('foo') 'badger'
15.4.5.6. 打印帮助
然而,也可以使用几种格式化的方法:
- ArgumentParser.print_usage(file=None)
sys.stdout。
- ArgumentParser.print_help(file=None)
sys.stdout。
同样这些方法还有变体只是简单地返回字符串而不是打印出来:
- ArgumentParser.format_usage()
ArgumentParser的简单描述。
- ArgumentParser.format_help()
ArgumentParser注册的参数信息。
15.4.5.7. 部分解析
- ArgumentParser.parse_known_args(args=None, namespace=None)
相反,它返回一个两个元素的元组,包含构造的namespace和剩余的参数字符串的列表。
>>>
>>> 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'])
警告
解析器将消耗一个选项即使它只是一个已知选项的前缀,而不会将它留在剩余的参数列表中。
15.4.5.8. 定制文件的解析
- ArgumentParser.convert_arg_line_to_args(arg_line)
convert_arg_line_to_args()以获得更好的阅读体验。
该方法按顺序对参数文件中的每一行调用一次。
该方法的一个有用的覆盖是以空格分隔的单词作为参数:
def convert_arg_line_to_args(self, arg_line): for arg in arg_line.split(): if not arg.strip(): continue yield arg
15.4.5.9. 退出的方法
- ArgumentParser.exit(status=0, message=None)
该方法将终止程序,以指定的status退出,如果给出message,则会在此之前打印出它。
- ArgumentParser.error(message)
该方法打印一个用法信息包括message参数到标准错误输出并以状态码2终止程序。
15.4.6. 升级optparse的代码
optparse中的大部分内容已经被复制粘贴或者胡乱地打上补丁时,试图维持向后兼容性似乎不太实际。
argparse的部分升级路线:
- ArgumentParser.add_argument()调用。
- args。
- action参数。
- type关键字参数的字符串名称为相应的类型对象(例如int、float、complex等)。
- ArgumentError。
- %(prog)s。
- version>')。
- 上一篇 »Linux命令之---pwd
- 下一篇 »Python获取命令行参数