[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])

下面每个参数有它们自己详细的描述，简单地讲它们是：

• name or flags - --foo。
• action - 在命令行遇到该参数时采取的基本动作类型。
• nargs - 应该读取的命令行参数数目。
• const - nargs选项要求的常数值。
• default - 如果命令行中没有出现该参数时的默认值。
• type - 命令行参数应该被转换成的类型。
• choices - 参数可允许的值的一个容器。
• required - 该命令行选项是否可以省略（只针对可选参数）。
• help - 参数的简短描述。
• metavar - 参数在帮助信息中的名字。
• dest - parse_args()返回的对象要添加的属性名称。

下面的小节描述这些参数如何使用。

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