argparse --命令行选项、参数和子命令解析器
示例
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))
1.创建一个解析器
parser = argparse.ArgumentParser(description='Process some integers.')
ArgumentParser对象包含将命令行解析成Python数据类型所需的全部信息。
2.添加参数
给一个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
属性将是一个包含一个或多个整数的列表,而 accumulate
属性当命令行中指定了 --sum
参数时将是 sum()
函数,否则则是 max()
函数。
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中确定命令行参数。
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, allow_abbrev=True, exit_on_error=True)
创建一个新的 ArgumentParser
对象。所有的参数都应当作为关键字参数传入。每个参数在下面都有它更详细的描述,但简而言之,它们是:
-
prog - 程序的名称(默认:
sys.argv[0]
) -
usage - 描述程序用途的字符串(默认值:从添加到解析器的参数生成)
-
description - 在参数帮助文档之前显示的文本(默认值:无)
-
epilog - 在参数帮助文档之后显示的文本(默认值:无)
-
parents - 一个
ArgumentParser
对象的列表,它们的参数也应包含在内 -
formatter_class - 用于自定义帮助文档输出格式的类
-
prefix_chars - 可选参数的前缀字符集合(默认值:'-')
-
fromfile_prefix_chars - 当需要从文件中读取其他参数时,用于标识文件名的前缀字符集合(默认值:
None
) -
argument_default - 参数的全局默认值(默认值:
None
) -
conflict_handler - 解决冲突选项的策略(通常是不必要的)
-
add_help - 为解析器添加一个
-h/--help
选项(默认值:True
) -
allow_abbrev - 如果缩写是无歧义的,则允许缩写长选项 (默认值:
True
) -
exit_on_error - 决定当错误发生时是否让 ArgumentParser 附带错误信息退出。 (默认值:
True
)
在 3.5 版更改: 添加 allow_abbrev 参数。
在 3.8 版更改: 在之前的版本中,allow_abbrev 还会禁用短旗标分组,例如 -vv
表示为 -v -v
。
在 3.9 版更改: 添加了 exit_on_error 形参。
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 - 命令行参数应当消耗的数目。
-
default - 当参数未在命令行中出现并且也不存在于命名空间对象时所产生的值。
-
type - 命令行参数应当被转换成的类型。
-
choices - 可用的参数的容器。
-
required - 此命令行选项是否可省略 (仅选项可用)。
-
help - 一个此选项作用的简单描述。
-
metavar - 在使用方法消息中使用的参数值示例。
-
dest - 被添加到
parse_args()
所返回对象上的属性名。
以下部分描述这些参数如何使用。
name or flags
add_argument()
方法必须知道它是否是一个选项,例如 -f
或 --foo
,或是一个位置参数,例如一组文件名。第一个传递给 add_argument()
的参数必须是一系列 flags 或者是一个简单的参数名。例如,可以选项可以被这样创建:
>>> parser.add_argument('-f', '--foo')
而位置参数可以这么创建:
>>> parser.add_argument('bar')
当 parse_args()
被调用,选项会以 -
前缀识别,剩下的参数则会被假定为位置参数:
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-f', '--foo')
>>> parser.add_argument('bar')
>>> parser.parse_args(['BAR'])
Namespace(bar='BAR', foo=None)
>>> parser.parse_args(['BAR', '--foo', 'FOO'])
Namespace(bar='BAR', foo='FOO')
>>> parser.parse_args(['--foo', 'FOO'])
usage: PROG [-h] [-f FOO] bar
PROG: error: the following arguments are required: bar
action
ArgumentParser
对象将命令行参数与动作相关联。这些动作可以做与它们相关联的命令行参数的任何事,尽管大多数动作只是简单的向 parse_args()
返回的对象上添加属性。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'
and'store_false'
- 这些是'store_const'
分别用作存储True
和False
值的特殊用例。另外,它们的默认值分别为False
和True
。例如:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='store_true')
>>> parser.add_argument('--bar', action='store_false')
>>> parser.add_argument('--baz', action='store_false')
>>> parser.parse_args('--foo --bar'.split())
Namespace(foo=True, bar=False, baz=True)
'append'
- 存储一个列表,并且将每个参数值追加到列表中。在允许多次使用选项时很有用。例如:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='append')
>>> parser.parse_args('--foo 1 --foo 2'.split())
Namespace(foo=['1', '2'])
'append_const'
- 这存储一个列表,并将 const 命名参数指定的值追加到列表中。(注意 const 命名参数默认为None
。)``'append_const'`` 动作一般在多个参数需要在同一列表中存储常数时会有用。例如:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--str', dest='types', action='append_const', const=str)
>>> parser.add_argument('--int', dest='types', action='append_const', const=int)
>>> parser.parse_args('--str --int'.split())
Namespace(types=[<class 'str'>, <class 'int'>])
'count'
- 计算一个关键字参数出现的数目或次数。例如,对于一个增长的详情等级来说有用:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--verbose', '-v', action='count', default=0)
>>> parser.parse_args(['-vvv'])
Namespace(verbose=3)
请注意,default 将为 None
,除非显式地设为 0。
'help'
- 打印所有当前解析器中的选项和参数的完整帮助信息,然后退出。默认情况下,一个 help 动作会被自动加入解析器。关于输出是如何创建的,参与ArgumentParser
。'version'
- 期望有一个version=
命名参数在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
'extend'
- 这会存储一个列表,并将每个参数值加入到列表中。 示例用法:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument("--foo", action="extend", nargs="+", type=str)
>>> parser.parse_args(["--foo", "f1", "--foo", "f2", "f3", "f4"])
Namespace(foo=['f1', 'f2', 'f3', 'f4'])
3.8 新版功能.
你还可以通过传递一个 Action 子类或实现相同接口的其他对象来指定任意操作。 BooleanOptionalAction
在 argparse
中可用并会添加对布尔型操作例如 --foo
和 --no-foo
的支持:
>>> import argparse
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action=argparse.BooleanOptionalAction)
>>> parser.parse_args(['--no-foo'])
Namespace(foo=False)
创建自定义动作的推荐方式是扩展 Action
,重载 __call__
方法以及可选的 __init__
和 format_usage
方法。
一个自定义动作的例子:
>>> class FooAction(argparse.Action):
... def __init__(self, option_strings, dest, nargs=None, **kwargs):
... if nargs is not None:
... raise ValueError("nargs not allowed")
... super().__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')
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=<_io.TextIOWrapper name='input.txt' encoding='UTF-8'>,
outfile=<_io.TextIOWrapper name='output.txt' encoding='UTF-8'>)
>>> parser.parse_args([])
Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>,
outfile=<_io.TextIOWrapper name='<stdout>' encoding='UTF-8'>)
'*'
。所有当前命令行参数被聚集到一个列表中。注意通过nargs='*'
来实现多个位置参数通常没有意义,但是多个选项是可能的。例如:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', nargs='*')
>>> parser.add_argument('--bar', nargs='*')
>>> parser.add_argument('baz', nargs='*')
>>> parser.parse_args('a b --foo x y --bar 1 2'.split())
Namespace(bar=['1', '2'], baz=['a', 'b'], foo=['x', 'y'])
'+'
。和'*'
类似,所有当前命令行参数被聚集到一个列表中。另外,当前没有至少一个命令行参数时会产生一个错误信息。例如:
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', nargs='+')
>>> parser.parse_args(['a', 'b'])
Namespace(foo=['a', 'b'])
>>> parser.parse_args([])
usage: PROG [-h] foo [foo ...]
PROG: error: the following arguments are required: foo
如果不提供 nargs
命名参数,则消耗参数的数目将被 action 决定。通常这意味着单一项目(非列表)消耗单一命令行参数。
const
add_argument()
的``const`` 参数用于保存不从命令行中读取但被各种 ArgumentParser
动作需求的常数值。最常用的两例为:
- 当
add_argument()
通过action='store_const'
或action='append_const
调用时。这些动作将const
值添加到parse_args()
返回的对象的属性中。在 action 的描述中查看案例。 - 当
add_argument()
通过选项(例如-f
或--foo
)调用并且nargs='?'
时。这会创建一个可以跟随零个或一个命令行参数的选项。当解析命令行时,如果选项后没有参数,则将用const
代替。在 nargs 描述中查看案例。
对 'store_const'
和 'append_const'
动作, const
命名参数必须给出。对其他动作,默认为 None
。
default
所有选项和一些位置参数可能在命令行中被忽略。add_argument()
的命名参数 default
,默认值为 None
,指定了在命令行参数未出现时应当使用的值。对于选项, default
值在选项未在命令行中出现时使用:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=42)
>>> parser.parse_args(['--foo', '2'])
Namespace(foo='2')
>>> parser.parse_args([])
Namespace(foo=42)
如果目标命名空间已经有一个属性集,则 default 动作不会覆盖它:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=42)
>>> parser.parse_args([], namespace=argparse.Namespace(foo=101))
Namespace(foo=101)
如果 default
值是一个字符串,解析器解析此值就像一个命令行参数。特别是,在将属性设置在 Namespace
的返回值之前,解析器应用任何提供的 type 转换参数。否则解析器使用原值:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--length', default='10', type=int)
>>> parser.add_argument('--width', default=10.5, type=int)
>>> parser.parse_args()
Namespace(length=10, width=10.5)
对于 nargs 等于 ?
或 *
的位置参数, default
值在没有命令行参数出现时使用。
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', nargs='?', default=42)
>>> parser.parse_args(['a'])
Namespace(foo='a')
>>> parser.parse_args([])
Namespace(foo=42)
提供 default=argparse.SUPPRESS
导致命令行参数未出现时没有属性被添加:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=argparse.SUPPRESS)
>>> parser.parse_args([])
Namespace()
>>> parser.parse_args(['--foo', '1'])
Namespace(foo='1')
type
默认情况下,解析器会将命令行参数当作简单字符串读入。 然而,命令行字符串经常应当被解读为其他类型,例如 float
或 int
。 add_argument()
的 type
关键字允许执行任何必要的类型检查和类型转换。
如果 type 关键字使用了 default 关键字,则类型转换器仅会在默认值为字符串时被应用。
传给 type
的参数可以是任何接受单个字符串的可调用对象。 如果函数引发了 ArgumentTypeError
, TypeError
或 ValueError
,异常会被捕获并显示经过良好格式化的错误消息。 其他异常类型则不会被处理。
普通内置类型和函数可被用作类型转换器
import argparse
import pathlib
parser = argparse.ArgumentParser()
parser.add_argument('count', type=int)
parser.add_argument('distance', type=float)
parser.add_argument('street', type=ascii)
parser.add_argument('code_point', type=ord)
parser.add_argument('source_file', type=open)
parser.add_argument('dest_file', type=argparse.FileType('w', encoding='latin-1'))
parser.add_argument('datapath', type=pathlib.Path)
用户自定义的函数也可以被使用:
>>> def hyphenated(string):
... return '-'.join([word[:4] for word in string.casefold().split()])
...
>>> parser = argparse.ArgumentParser()
>>> _ = parser.add_argument('short_title', type=hyphenated)
>>> parser.parse_args(['"The Tale of Two Cities"'])
Namespace(short_title='"the-tale-of-two-citi')
不建议将 bool()
函数用作类型转换器。 它所做的只是将空字符串转为 False
而将非空字符串转为 True
。 这通常不是用户所想要的。
通常,type
关键字是仅应被用于只会引发上述三种被支持的异常的简单转换的便捷选项。 任何具有更复杂错误处理或资源管理的转换都应当在参数被解析后由下游代码来完成。
例如,JSON 或 YAML 转换具有复杂的错误情况,要求给出比 type
关键字所能给出的更好的报告。 JSONDecodeError
将不会被良好地格式化而 FileNotFound
异常则完全不会被处理。
即使 FileType
在用于 type
关键字时也存在限制。 如果一个参数使用了 FileType 并且有一个后续参数出错,则将报告一个错误但文件并不会被自动关闭。 在此情况下,更好的做法是等待直到解析器运行完毕再使用 with
语句来管理文件。
对于简单地检查一组固定值的类型检查器,请考虑改用 choices 关键字。
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')
请注意 choices 容器包含的内容会在执行任意 type 转换之后被检查,因此 choices 容器中对象的类型应当与指定的 type 相匹配:
>>> parser = argparse.ArgumentParser(prog='doors.py')
>>> parser.add_argument('door', type=int, choices=range(1, 4))
>>> print(parser.parse_args(['3']))
Namespace(door=3)
>>> parser.parse_args(['4'])
usage: doors.py [-h] {1,2,3}
doors.py: error: argument door: invalid choice: 4 (choose from 1, 2, 3)
任何容器都可作为 choices 值传入,因此 list
对象,set
对象以及自定义容器都是受支持的。
不建议使用 enum.Enum
,因为要控制其在用法、帮助和错误消息中的外观是很困难的。
已格式化的选项会覆盖默认的 metavar,该值一般是派生自 dest。 这通常就是你所需要的,因为用户永远不会看到 dest 形参。 如果不想要这样的显示(或许因为有很多选择),只需指定一个显式的 metavar。
required
通常,argparse
模块会认为 -f
和 --bar
等旗标是指明 可选的 参数,它们总是可以在命令行中被忽略。 要让一个选项成为 必需的,则可以将 True
作为 required=
关键字参数传给 add_argument()
:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', required=True)
>>> parser.parse_args(['--foo', 'BAR'])
Namespace(foo='BAR')
>>> parser.parse_args([])
usage: [-h] --foo FOO
: error: the following arguments are required: --foo
如这个例子所示,如果一个选项被标记为 required
,则当该选项未在命令行中出现时,parse_args()
将会报告一个错误。
注解 必需的选项通常被认为是不适宜的,因为用户会预期 options 都是 可选的,因此在可能的情况下应当避免使用它们。
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
字符串可包括各种格式描述符以避免重复使用程序名称或参数 default 等文本。 有效的描述符包括程序名称 %(prog)s
和传给 add_argument()
的大部分关键字参数,例如 %(default)s
, %(type)s
等等:
>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('bar', nargs='?', type=int, default=42,
... help='the bar to %(prog)s (default: %(default)s)')
>>> parser.print_help()
usage: frobble [-h] [bar]
positional arguments:
bar the bar to frobble (default: 42)
optional arguments:
-h, --help show this help message and exit
由于帮助字符串支持 %-formatting,如果你希望在帮助字符串中显示 %
字面值,你必须将其转义为 %%
。
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
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 被多次使用。 提供一个元组给 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
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
会通过接受第一个长选项字符串并去掉开头的 --
字符串来生成 dest
的值。 如果没有提供长选项字符串,则 dest
将通过接受第一个短选项字符串并去掉开头的 -
字符来获得。 任何内部的 -
字符都将被转换为 _
字符以确保字符串是有效的属性名称。 下面的例子显示了这种行为:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('-f', '--foo-bar', '--foo')
>>> parser.add_argument('-x', '-y')
>>> parser.parse_args('-f 1 -x 2'.split())
Namespace(foo_bar='1', x='2')
>>> parser.parse_args('--foo 1 -y 2'.split())
Namespace(foo_bar='1', x='2')
dest
允许提供自定义属性名称:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', dest='bar')
>>> parser.parse_args('--foo XXX'.split())
Namespace(bar='XXX')
parse_args() 方法
ArgumentParser.
parse_args
(args=None, namespace=None)¶
将参数字符串转换为对象并将其设为命名空间的属性。 返回带有成员的命名空间。
之前对 add_argument()
的调用决定了哪些对象被创建以及它们如何被赋值。 请参阅 add_argument()
的文档了解详情。
选项值语法
parse_args()
方法支持多种指定选项值的方式(如果它接受选项的话)。 在最简单的情况下,选项和它的值是作为两个单独参数传入的:
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x')
>>> parser.add_argument('--foo')
>>> parser.parse_args(['-x', 'X'])
Namespace(foo=None, x='X')
>>> parser.parse_args(['--foo', 'FOO'])
Namespace(foo='FOO', x=None)
对于长选项(名称长度超过一个字符的选项),选项和值也可以作为单个命令行参数传入,使用 =
分隔它们即可:
>>> parser.parse_args(['--foo=FOO'])
Namespace(foo='FOO', x=None)
对于短选项(长度只有一个字符的选项),选项和它的值可以拼接在一起:
>>> parser.parse_args(['-xX'])
Namespace(foo=None, x='X')
有些短选项可以使用单个 -
前缀来进行合并,如果仅有最后一个选项(或没有任何选项)需要值的话:
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x', action='store_true')
>>> parser.add_argument('-y', action='store_true')
>>> parser.add_argument('-z')
>>> parser.parse_args(['-xyzZ'])
Namespace(x=True, y=True, z='Z')
无效的参数
在解析命令行时,parse_args()
会检测多种错误,包括有歧义的选项、无效的类型、无效的选项、错误的位置参数个数等等。 当遇到这种错误时,它将退出并打印出错误文本同时附带用法消息:
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo', type=int)
>>> parser.add_argument('bar', nargs='?')
>>> # invalid type
>>> parser.parse_args(['--foo', 'spam'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: argument --foo: invalid int value: 'spam'
>>> # invalid option
>>> parser.parse_args(['--bar'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: no such option: --bar
>>> # wrong number of arguments
>>> parser.parse_args(['spam', 'badger'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: extra arguments found: badger
包含 -
的参数
parse_args()
方法会在用户明显出错时尝试给出错误信息,但某些情况本身就存在歧义。 例如,命令行参数 -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)
参数缩写(前缀匹配)
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
可产生一个以上选项的参数会引发错误。 此特定可通过将 allow_abbrev 设为 False
来禁用。
在 sys.argv
以外
有时在 sys.argv
以外用 ArgumentParser 解析参数也是有用的。 这可以通过将一个字符串列表传给 parse_args()
来实现。 它适用于在交互提示符下进行检测:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument(
... 'integers', metavar='int', type=int, choices=range(10),
... nargs='+', help='an integer in the range 0..9')
>>> parser.add_argument(
... '--sum', dest='accumulate', action='store_const', const=sum,
... default=max, help='sum the integers (default: find the max)')
>>> parser.parse_args(['1', '2', '3', '4'])
Namespace(accumulate=<built-in function max>, integers=[1, 2, 3, 4])
>>> parser.parse_args(['1', '2', '3', '4', '--sum'])
Namespace(accumulate=<built-in function sum>, integers=[1, 2, 3, 4])
命名空间对象
class argparse.
Namespace
由 parse_args()
默认使用的简单类,可创建一个存放属性的对象并将其返回。
这个类被有意做得很简单,只是一个具有可读字符串表示形式的 object
。 如果你更喜欢类似字典的属性视图,你可以使用标准 Python 中惯常的 vars()
:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> args = parser.parse_args(['--foo', 'BAR'])
>>> vars(args)
{'foo': 'BAR'}
另一个用处是让 ArgumentParser
为一个已存在对象而不是为一个新的 Namespace
对象的属性赋值。 这可以通过指定 namespace=
关键字参数来实现:
>>> class C:
... pass
...
>>> c = C()
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.parse_args(args=['--foo', 'BAR'], namespace=c)
>>> c.foo
'BAR'