Python标准库argparse命令行选项、参数和子命令解析器

子命令¶

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

许多程序都会将其功能拆分为一系列子命令，例如，svn 程序包含的子命令有 svncheckout, svnupdate 和 svncommit。 当一个程序能执行需要多组不同种类命令行参数时这种拆分功能的方式是一个非常好的主意。 ArgumentParser 通过 add_subparsers() 方法支持创建这样的子命令。 add_subparsers() 方法通常不带参数地调用并返回一个特殊的动作对象。 这种对象只有一个方法 add_parser()，它接受一个命令名称和任意多个 ArgumentParser 构造器参数，并返回一个可以通常方式进行修改的 ArgumentParser 对象。

形参的描述

• title - 输出帮助的子解析器分组的标题；如果提供了描述则默认为 "subcommands"，否则使用位置参数的标题

• description - 输出帮助中对子解析器的描述，默认为 None

• prog - 将与子命令帮助一同显示的用法信息，默认为程序名称和子解析器参数之前的任何位置参数。

• 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 属性。

类似地，当从一个子解析器请求帮助消息时，只有该特定解析器的帮助消息会被打印出来。 帮助消息将不包括父解析器或同级解析器的消息。 （每个子解析器命令一条帮助消息，但是，也可以像上面那样通过提供 help= 参数给 add_parser() 来给出。）

>>> parser.parse_args(['--help'])
usage: PROG [-h] [--foo] {a,b} ...
positional arguments:
  {a,b}   sub-command help
    a     a help
    b     b help
optional arguments:
  -h, --help  show this help message and exit
  --foo   foo help
>>> parser.parse_args(['a','--help'])
usage: PROG a [-h] bar
positional arguments:
  bar     bar help
optional arguments:
  -h, --help  show this help message and exit
>>> parser.parse_args(['b','--help'])
usage: PROG b [-h] [--baz {X,Y,Z}]
optional arguments:
  -h, --help     show this help message and exit
  --baz {X,Y,Z}  baz help

add_subparsers() 方法也支持 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
>>> deffoo(args):
... print(args.x*args.y)
...
>>> defbar(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 对象¶

class argparse.FileType(mode='r', bufsize=-1, encoding=None, errors=None)¶

FileType 工厂类用于创建可作为 ArgumentParser.add_argument() 的 type 参数传入的对象。 以 FileType 对象作为其类型的参数将使用命令行参数以所请求模式、缓冲区大小、编码格式和错误处理方式打开文件（请参阅 open() 函数了解详情）:

>>> parser=argparse.ArgumentParser()
>>> parser.add_argument('--raw',type=argparse.FileType('wb',0))
>>> parser.add_argument('out',type=argparse.FileType('w',encoding='UTF-8'))
>>> parser.parse_args(['--raw','raw.dat','file.txt'])
Namespace(out=<_io.TextIOWrapper name='file.txt' mode='w' encoding='UTF-8'>, raw=<_io.FileIO name='raw.dat' mode='wb'>)

FileType 对象能理解伪参数 '-' 并会自动将其转换为 sys.stdin 用于可读的 FileType 对象，或是 sys.stdout 用于可写的 FileType 对象:

>>> parser=argparse.ArgumentParser()
>>> parser.add_argument('infile',type=argparse.FileType('r'))
>>> parser.parse_args(['-'])
Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>)

3.4 新版功能: encodings 和 errors 关键字参数。

参数组¶

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

请注意任意不在你的自定义分组中的参数最终都将回到通常的“位置参数”和“可选参数”分组中。

互斥¶

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

解析器默认值¶

ArgumentParser.set_defaults(**kwargs)¶

在大多数时候，parse_args() 所返回对象的属性将完全通过检查命令行参数和参数动作来确定。 set_defaults() 则允许加入一些无须任何命令行检查的额外属性:

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

请注意解析器层级的默认值总是会覆盖参数层级的默认值:

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

解析器层级默认值在需要多解析器时会特别有用。 请参阅 add_subparsers() 方法了解此类型的一个示例。

ArgumentParser.get_default(dest)¶

获取一个命名空间属性的默认值，该值是由 add_argument() 或 set_defaults() 设置的:

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

打印帮助¶

在大多数典型应用中，parse_args() 将负责任何用法和错误消息的格式化和打印。 但是，也可使用某些其他格式化方法:

ArgumentParser.print_usage(file=None)¶

打印一段简短描述，说明应当如何在命令行中发起调用 ArgumentParser。 如果 file 为 None，则默认使用 sys.stdout。

ArgumentParser.print_help(file=None)¶

打印一条帮助消息，包括程序用法和通过 ArgumentParser 注册的相关参数信息。 如果 file 为 None，则默认使用 sys.stdout。

还存在这些方法的几个变化形式，它们只返回字符串而不打印消息:

ArgumentParser.format_usage()¶

返回一个包含简短描述的字符串，说明应当如何在命令行中发起调用 ArgumentParser。

ArgumentParser.format_help()¶

反回一个包含帮助消息的字符串，包括程序用法和通过 ArgumentParser 注册的相关参数信息。