Argparse 教程¶
- 作者:
Tshepang Mbambo
本教程旨在作为 Python 标准库中推荐的命令行解析模块 argparse
的入门介绍。
注意
还有另外两个模块可以完成相同的任务,分别是 getopt
(C 语言中 getopt()
的等效项)和已弃用的 optparse
。还要注意,argparse
是基于 optparse
的,因此在使用方面非常相似。
概念¶
让我们通过使用 ls 命令来展示我们将在本入门教程中探索的功能类型。
$ ls
cpython devguide prog.py pypy rm-unused-function.patch
$ ls pypy
ctypes_configure demo dotviewer include lib_pypy lib-python ...
$ ls -l
total 20
drwxr-xr-x 19 wena wena 4096 Feb 18 18:51 cpython
drwxr-xr-x 4 wena wena 4096 Feb 8 12:04 devguide
-rwxr-xr-x 1 wena wena 535 Feb 19 00:05 prog.py
drwxr-xr-x 14 wena wena 4096 Feb 7 00:59 pypy
-rw-r--r-- 1 wena wena 741 Feb 18 01:01 rm-unused-function.patch
$ ls --help
Usage: ls [OPTION]... [FILE]...
List information about the FILEs (the current directory by default).
Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.
...
我们可以从这四个命令中学习一些概念。
ls 命令在没有任何选项的情况下运行时非常有用。它默认显示当前目录的内容。
如果我们想要超出默认提供的功能,我们需要告诉它更多信息。在本例中,我们希望它显示不同的目录,
pypy
。我们所做的是指定了所谓的“位置参数”。之所以这样命名,是因为程序应该仅根据它在命令行中的位置来知道如何处理该值。这个概念与 cp 这样的命令更相关,它的最基本用法是cp SRC DEST
。第一个位置是“要复制的内容”,第二个位置是“要复制到的位置”。现在,假设我们想要更改程序的行为。在我们的示例中,我们显示每个文件的更多信息,而不是只显示文件名。在这种情况下,
-l
被称为“可选参数”。这是帮助文本的片段。它非常有用,因为你可以遇到一个以前从未使用过的程序,并且可以通过阅读它的帮助文本来弄清楚它是如何工作的。
基础¶
让我们从一个非常简单的示例开始,它几乎什么也不做。
import argparse
parser = argparse.ArgumentParser()
parser.parse_args()
以下是运行代码的结果。
$ python prog.py
$ python prog.py --help
usage: prog.py [-h]
options:
-h, --help show this help message and exit
$ python prog.py --verbose
usage: prog.py [-h]
prog.py: error: unrecognized arguments: --verbose
$ python prog.py foo
usage: prog.py [-h]
prog.py: error: unrecognized arguments: foo
以下是发生的事情。
在没有任何选项的情况下运行脚本不会在 stdout 中显示任何内容。不太有用。
第二个开始显示
argparse
模块的用处。我们几乎没有做任何事情,但已经得到了一个很好的帮助消息。--help
选项可以缩写为-h
,是我们免费获得的唯一选项(即不需要指定它)。指定任何其他内容都会导致错误。但即使这样,我们也免费获得了有用的用法消息。
介绍位置参数¶
一个例子
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("echo")
args = parser.parse_args()
print(args.echo)
以及运行代码
$ python prog.py
usage: prog.py [-h] echo
prog.py: error: the following arguments are required: echo
$ python prog.py --help
usage: prog.py [-h] echo
positional arguments:
echo
options:
-h, --help show this help message and exit
$ python prog.py foo
foo
以下是发生的事情
我们添加了
add_argument()
方法,这是我们用来指定程序愿意接受哪些命令行选项的方法。在本例中,我将其命名为echo
,以便它与其功能一致。现在调用我们的程序需要我们指定一个选项。
该
parse_args()
方法实际上从指定的选项中返回一些数据,在本例中为echo
。该变量是
argparse
免费执行的某种“魔法”(即无需指定存储该值的变量)。您还会注意到它的名称与传递给该方法的字符串参数echo
相匹配。
但是请注意,尽管帮助显示看起来很不错,但它目前并没有像它可以的那样有用。例如,我们看到我们得到了 echo
作为位置参数,但我们不知道它做什么,除了猜测或阅读源代码。因此,让我们使其更有用。
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("echo", help="echo the string you use here")
args = parser.parse_args()
print(args.echo)
我们得到
$ python prog.py -h
usage: prog.py [-h] echo
positional arguments:
echo echo the string you use here
options:
-h, --help show this help message and exit
现在,如何做一些更有用的事情
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", help="display a square of a given number")
args = parser.parse_args()
print(args.square**2)
以下是运行代码的结果。
$ python prog.py 4
Traceback (most recent call last):
File "prog.py", line 5, in <module>
print(args.square**2)
TypeError: unsupported operand type(s) for ** or pow(): 'str' and 'int'
这不太好。这是因为 argparse
将我们提供的选项视为字符串,除非我们另行说明。因此,让我们告诉 argparse
将该输入视为整数
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", help="display a square of a given number",
type=int)
args = parser.parse_args()
print(args.square**2)
以下是运行代码的结果。
$ python prog.py 4
16
$ python prog.py four
usage: prog.py [-h] square
prog.py: error: argument square: invalid int value: 'four'
这很顺利。该程序现在甚至在继续之前,会在遇到非法输入时提供帮助并退出。
介绍可选参数¶
到目前为止,我们一直在玩位置参数。让我们看看如何添加可选参数。
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("--verbosity", help="increase output verbosity")
args = parser.parse_args()
if args.verbosity:
print("verbosity turned on")
以及输出
$ python prog.py --verbosity 1
verbosity turned on
$ python prog.py
$ python prog.py --help
usage: prog.py [-h] [--verbosity VERBOSITY]
options:
-h, --help show this help message and exit
--verbosity VERBOSITY
increase output verbosity
$ python prog.py --verbosity
usage: prog.py [-h] [--verbosity VERBOSITY]
prog.py: error: argument --verbosity: expected one argument
以下是发生的事情。
该程序被编写为在指定
--verbosity
时显示某些内容,而在未指定时不显示任何内容。为了表明该选项实际上是可选的,在没有该选项的情况下运行程序时不会出现错误。请注意,默认情况下,如果未使用可选参数,则相关变量(在本例中为
args.verbosity
)将被赋予None
作为值,这就是它无法通过if
语句的真值测试的原因。帮助消息略有不同。
使用
--verbosity
选项时,还必须指定一些值,任何值。
上面的示例接受 --verbosity
的任意整数值,但对于我们的简单程序,实际上只有两个值有用,True
或 False
。让我们相应地修改代码。
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("--verbose", help="increase output verbosity",
action="store_true")
args = parser.parse_args()
if args.verbose:
print("verbosity turned on")
以及输出
$ python prog.py --verbose
verbosity turned on
$ python prog.py --verbose 1
usage: prog.py [-h] [--verbose]
prog.py: error: unrecognized arguments: 1
$ python prog.py --help
usage: prog.py [-h] [--verbose]
options:
-h, --help show this help message and exit
--verbose increase output verbosity
以下是发生的事情。
该选项现在更像是一个标志,而不是需要值的选项。我们甚至更改了选项的名称以匹配该想法。请注意,我们现在指定了一个新关键字
action
,并将其值设置为"store_true"
。这意味着,如果指定了该选项,则将值True
分配给args.verbose
。未指定它意味着False
。当您指定一个值时,它会抱怨,这完全符合标志的实际含义。
注意不同的帮助文本。
简短选项¶
如果您熟悉命令行使用,您会注意到我还没有触及选项的简短版本。这很简单
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("-v", "--verbose", help="increase output verbosity",
action="store_true")
args = parser.parse_args()
if args.verbose:
print("verbosity turned on")
现在开始
$ python prog.py -v
verbosity turned on
$ python prog.py --help
usage: prog.py [-h] [-v]
options:
-h, --help show this help message and exit
-v, --verbose increase output verbosity
请注意,新功能也反映在帮助文本中。
组合位置参数和可选参数¶
我们的程序在复杂性方面不断增长
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", type=int,
help="display a square of a given number")
parser.add_argument("-v", "--verbose", action="store_true",
help="increase output verbosity")
args = parser.parse_args()
answer = args.square**2
if args.verbose:
print(f"the square of {args.square} equals {answer}")
else:
print(answer)
现在是输出
$ python prog.py
usage: prog.py [-h] [-v] square
prog.py: error: the following arguments are required: square
$ python prog.py 4
16
$ python prog.py 4 --verbose
the square of 4 equals 16
$ python prog.py --verbose 4
the square of 4 equals 16
我们恢复了一个位置参数,因此出现了抱怨。
请注意,顺序无关紧要。
我们如何让我们的程序恢复具有多个详细程度值的能力,并实际使用它们
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", type=int,
help="display a square of a given number")
parser.add_argument("-v", "--verbosity", type=int,
help="increase output verbosity")
args = parser.parse_args()
answer = args.square**2
if args.verbosity == 2:
print(f"the square of {args.square} equals {answer}")
elif args.verbosity == 1:
print(f"{args.square}^2 == {answer}")
else:
print(answer)
以及输出
$ python prog.py 4
16
$ python prog.py 4 -v
usage: prog.py [-h] [-v VERBOSITY] square
prog.py: error: argument -v/--verbosity: expected one argument
$ python prog.py 4 -v 1
4^2 == 16
$ python prog.py 4 -v 2
the square of 4 equals 16
$ python prog.py 4 -v 3
16
这些看起来都很好,除了最后一个,它暴露了我们程序中的一个错误。让我们通过限制 --verbosity
选项可以接受的值来修复它
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", type=int,
help="display a square of a given number")
parser.add_argument("-v", "--verbosity", type=int, choices=[0, 1, 2],
help="increase output verbosity")
args = parser.parse_args()
answer = args.square**2
if args.verbosity == 2:
print(f"the square of {args.square} equals {answer}")
elif args.verbosity == 1:
print(f"{args.square}^2 == {answer}")
else:
print(answer)
以及输出
$ python prog.py 4 -v 3
usage: prog.py [-h] [-v {0,1,2}] square
prog.py: error: argument -v/--verbosity: invalid choice: 3 (choose from 0, 1, 2)
$ python prog.py 4 -h
usage: prog.py [-h] [-v {0,1,2}] square
positional arguments:
square display a square of a given number
options:
-h, --help show this help message and exit
-v {0,1,2}, --verbosity {0,1,2}
increase output verbosity
请注意,更改也反映在错误消息和帮助字符串中。
现在,让我们使用不同的方法来玩详细程度,这很常见。它也与 CPython 可执行文件处理其自身详细程度参数的方式相匹配(检查 python --help
的输出)
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", type=int,
help="display the square of a given number")
parser.add_argument("-v", "--verbosity", action="count",
help="increase output verbosity")
args = parser.parse_args()
answer = args.square**2
if args.verbosity == 2:
print(f"the square of {args.square} equals {answer}")
elif args.verbosity == 1:
print(f"{args.square}^2 == {answer}")
else:
print(answer)
我们引入了另一个操作“count”,用于计算特定选项出现的次数。
$ python prog.py 4
16
$ python prog.py 4 -v
4^2 == 16
$ python prog.py 4 -vv
the square of 4 equals 16
$ python prog.py 4 --verbosity --verbosity
the square of 4 equals 16
$ python prog.py 4 -v 1
usage: prog.py [-h] [-v] square
prog.py: error: unrecognized arguments: 1
$ python prog.py 4 -h
usage: prog.py [-h] [-v] square
positional arguments:
square display a square of a given number
options:
-h, --help show this help message and exit
-v, --verbosity increase output verbosity
$ python prog.py 4 -vvv
16
是的,它现在更像是一个标志(类似于我们脚本先前版本中的
action="store_true"
)。这应该解释了抱怨。它的行为也类似于“store_true”操作。
现在,这里演示了“count”操作带来的效果。您可能以前见过这种用法。
如果您没有指定
-v
标志,则该标志被认为具有None
值。正如预期的那样,指定标志的长格式,我们应该得到相同的输出。
遗憾的是,我们的帮助输出对我们脚本获得的新功能没有太多信息,但这可以通过改进我们脚本的文档来解决(例如,通过
help
关键字参数)。最后一个输出暴露了我们程序中的一个错误。
让我们修复
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", type=int,
help="display a square of a given number")
parser.add_argument("-v", "--verbosity", action="count",
help="increase output verbosity")
args = parser.parse_args()
answer = args.square**2
# bugfix: replace == with >=
if args.verbosity >= 2:
print(f"the square of {args.square} equals {answer}")
elif args.verbosity >= 1:
print(f"{args.square}^2 == {answer}")
else:
print(answer)
这就是它带来的效果
$ python prog.py 4 -vvv
the square of 4 equals 16
$ python prog.py 4 -vvvv
the square of 4 equals 16
$ python prog.py 4
Traceback (most recent call last):
File "prog.py", line 11, in <module>
if args.verbosity >= 2:
TypeError: '>=' not supported between instances of 'NoneType' and 'int'
第一个输出很好,并修复了我们之前遇到的错误。也就是说,我们希望任何值 >= 2 都尽可能详细。
第三个输出不太好。
让我们修复那个错误
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", type=int,
help="display a square of a given number")
parser.add_argument("-v", "--verbosity", action="count", default=0,
help="increase output verbosity")
args = parser.parse_args()
answer = args.square**2
if args.verbosity >= 2:
print(f"the square of {args.square} equals {answer}")
elif args.verbosity >= 1:
print(f"{args.square}^2 == {answer}")
else:
print(answer)
我们刚刚引入了另一个关键字 default
。我们将其设置为 0
以便使其可与其他 int 值进行比较。请记住,默认情况下,如果未指定可选参数,它将获得 None
值,而该值无法与 int 值进行比较(因此出现了 TypeError
异常)。
以及
$ python prog.py 4
16
到目前为止,您已经学到了很多东西,而我们只是触及了皮毛。 argparse
模块非常强大,在我们结束本教程之前,我们将进一步探索它。
变得更高级¶
如果我们想扩展我们的小程序以执行其他幂运算,而不仅仅是平方运算,该怎么办
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("x", type=int, help="the base")
parser.add_argument("y", type=int, help="the exponent")
parser.add_argument("-v", "--verbosity", action="count", default=0)
args = parser.parse_args()
answer = args.x**args.y
if args.verbosity >= 2:
print(f"{args.x} to the power {args.y} equals {answer}")
elif args.verbosity >= 1:
print(f"{args.x}^{args.y} == {answer}")
else:
print(answer)
输出
$ python prog.py
usage: prog.py [-h] [-v] x y
prog.py: error: the following arguments are required: x, y
$ python prog.py -h
usage: prog.py [-h] [-v] x y
positional arguments:
x the base
y the exponent
options:
-h, --help show this help message and exit
-v, --verbosity
$ python prog.py 4 2 -v
4^2 == 16
请注意,到目前为止,我们一直在使用详细程度级别来更改显示的文本。以下示例使用详细程度级别来显示更多文本
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("x", type=int, help="the base")
parser.add_argument("y", type=int, help="the exponent")
parser.add_argument("-v", "--verbosity", action="count", default=0)
args = parser.parse_args()
answer = args.x**args.y
if args.verbosity >= 2:
print(f"Running '{__file__}'")
if args.verbosity >= 1:
print(f"{args.x}^{args.y} == ", end="")
print(answer)
输出
$ python prog.py 4 2
16
$ python prog.py 4 2 -v
4^2 == 16
$ python prog.py 4 2 -vv
Running 'prog.py'
4^2 == 16
指定模棱两可的参数¶
当在决定参数是位置参数还是可选参数时存在歧义时,可以使用 --
来告诉 parse_args()
,它之后的所有内容都是位置参数。
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-n', nargs='+')
>>> parser.add_argument('args', nargs='*')
>>> # ambiguous, so parse_args assumes it's an option
>>> parser.parse_args(['-f'])
usage: PROG [-h] [-n N [N ...]] [args ...]
PROG: error: unrecognized arguments: -f
>>> parser.parse_args(['--', '-f'])
Namespace(args=['-f'], n=None)
>>> # ambiguous, so the -n option greedily accepts arguments
>>> parser.parse_args(['-n', '1', '2', '3'])
Namespace(args=[], n=['1', '2', '3'])
>>> parser.parse_args(['-n', '1', '--', '2', '3'])
Namespace(args=['2', '3'], n=['1'])
冲突选项¶
到目前为止,我们一直在使用 argparse.ArgumentParser
实例的两种方法。现在让我们介绍第三种方法,add_mutually_exclusive_group()
。它允许我们指定相互冲突的选项。我们也修改程序的其余部分,使新功能更有意义:我们将引入 --quiet
选项,它将与 --verbose
选项相反。
import argparse
parser = argparse.ArgumentParser()
group = parser.add_mutually_exclusive_group()
group.add_argument("-v", "--verbose", action="store_true")
group.add_argument("-q", "--quiet", action="store_true")
parser.add_argument("x", type=int, help="the base")
parser.add_argument("y", type=int, help="the exponent")
args = parser.parse_args()
answer = args.x**args.y
if args.quiet:
print(answer)
elif args.verbose:
print(f"{args.x} to the power {args.y} equals {answer}")
else:
print(f"{args.x}^{args.y} == {answer}")
我们的程序现在更简单了,为了演示,我们失去了一些功能。无论如何,以下是输出。
$ python prog.py 4 2
4^2 == 16
$ python prog.py 4 2 -q
16
$ python prog.py 4 2 -v
4 to the power 2 equals 16
$ python prog.py 4 2 -vq
usage: prog.py [-h] [-v | -q] x y
prog.py: error: argument -q/--quiet: not allowed with argument -v/--verbose
$ python prog.py 4 2 -v --quiet
usage: prog.py [-h] [-v | -q] x y
prog.py: error: argument -q/--quiet: not allowed with argument -v/--verbose
这应该很容易理解。我添加了最后一个输出,这样你就可以看到你得到的灵活性,例如将长格式选项与短格式选项混合使用。
在我们结束之前,你可能想告诉你的用户你的程序的主要目的,以防他们不知道。
import argparse
parser = argparse.ArgumentParser(description="calculate X to the power of Y")
group = parser.add_mutually_exclusive_group()
group.add_argument("-v", "--verbose", action="store_true")
group.add_argument("-q", "--quiet", action="store_true")
parser.add_argument("x", type=int, help="the base")
parser.add_argument("y", type=int, help="the exponent")
args = parser.parse_args()
answer = args.x**args.y
if args.quiet:
print(answer)
elif args.verbose:
print(f"{args.x} to the power {args.y} equals {answer}")
else:
print(f"{args.x}^{args.y} == {answer}")
注意使用文本中的细微差别。注意 [-v | -q]
,它告诉我们我们可以使用 -v
或 -q
,但不能同时使用两者。
$ python prog.py --help
usage: prog.py [-h] [-v | -q] x y
calculate X to the power of Y
positional arguments:
x the base
y the exponent
options:
-h, --help show this help message and exit
-v, --verbose
-q, --quiet
如何翻译 argparse 输出¶
argparse
模块的输出,例如它的帮助文本和错误消息,都是使用 gettext
模块进行翻译的。这使应用程序能够轻松地本地化由 argparse
生成的消息。另请参阅 国际化你的程序和模块。
例如,在这个 argparse
输出中
$ python prog.py --help
usage: prog.py [-h] [-v | -q] x y
calculate X to the power of Y
positional arguments:
x the base
y the exponent
options:
-h, --help show this help message and exit
-v, --verbose
-q, --quiet
字符串 usage:
、positional arguments:
、options:
和 show this help message and exit
都是可翻译的。
为了翻译这些字符串,它们必须首先被提取到一个 .po
文件中。例如,使用 Babel,运行以下命令
$ pybabel extract -o messages.po /usr/lib/python3.12/argparse.py
此命令将从 argparse
模块中提取所有可翻译的字符串,并将它们输出到名为 messages.po
的文件中。此命令假设你的 Python 安装在 /usr/lib
中。
你可以使用以下脚本找出系统上 argparse
模块的位置
import argparse
print(argparse.__file__)
结论¶
argparse
模块提供了比这里展示的更多功能。它的文档非常详细和全面,并包含大量示例。在完成本教程后,您应该能够轻松地理解它们,而不会感到不知所措。