作者选择了 COVID-19 救援基金作为 Write for Donations计划的一部分接受捐款。
介绍
Python 的 ‘argparse’标准库模块是一个工具,可以帮助您在 Python 代码上编写命令行接口(CLI)。您可能已经熟悉了 CLI:诸如 git、 ls、 grep 和 find 等程序都暴露了命令行接口,允许您调用具有特定输入和选项的底层程序。 argparse 允许您调用自己的自定义 Python 代码,用命令行论点类似于您如何使用命令行调用 git、 ls、 grep 或 find。
在本教程中,您将使用Python的argparse标准库模块暴露的一些实用程序。您将写作接受定位和可选参数的命令行界面,以控制潜在程序的行为。
对于本教程,你将为一个程序写命令行界面,在虚构的水族馆中跟踪鱼类。
前提条件
为了充分利用本教程,我们建议您:
您可以查看我们的 How To Code in Python 3]教程系列以获得背景知识
编写一个接受位置参数的命令行程序
您可以使用argparse模块来编写一个接受位置参数的命令行界面。
让我们考虑一个例子CLI,它打印了被定位坦克参数识别的水族箱中的鱼。
要创建 CLI,请使用文本编辑器打开一个文件:
1nano aquarium.py
然后添加以下Python代码:
1[label aquarium.py]
2import argparse
3
4tank_to_fish = {
5 "tank_a": "shark, tuna, herring",
6 "tank_b": "cod, flounder",
7}
8
9parser = argparse.ArgumentParser(description="List fish in aquarium.")
10parser.add_argument("tank", type=str)
11args = parser.parse_args()
12
13fish = tank_to_fish.get(args.tank, "")
14print(fish)
您可以通过运行在tank_a中打印鱼:
1python3 aquarium.py tank_a
运行该命令后,您将收到如下的输出:
1[secondary_label Output]
2shark, tuna, herring
同样,如果你运行aquarium.py来打印tank_b中的鱼:
1python3 aquarium.py tank_b
你会收到如下这样的输出:
1[secondary_label Output]
2cod, flounder
让我们在aquarium.py中分解代码。
首先,您将导入argparse模块,使其可用于您的程序,接下来,您将创建一个词典数据结构tank_to_fish,该数据结构将坦克名称(如tank_a和tank_b)绘制到这些坦克中持有的鱼类的字符串描述。
您将ArgumentParser类的实例实例实例并将其绑定到parser变量中。您可以将parser视为配置命令行界面的主要输入点。为parser提供的描述字符串,正如您稍后了解的那样,用于由aquarium.py曝光的CLI的自动生成帮助文本。
在解析器上调用add_argument允许你添加你的命令行界面所接受的参数. 在这种情况下,你添加一个名为tank的单一参数,即字符串类型。调用parser.parse_args()命令parser处理并验证传给aquarium.py的命令行输入(例如,类似tank_a)。
此时,你已经编写了一个命令行界面,并执行了你的程序来打印鱼. 现在你需要描述你的 CLI 如何工作给其他开发人员。 `argparse' 有强大的支持帮助文本来记录你的 CLI。
查看帮助文本
你刚刚在上一节写的aquarium.py文件实际上比打印鱼在一个特定的坦克做得更多,因为你正在使用argparse,由aquarium.py曝光的命令行界面将自动包含帮助和使用信息,用户可以咨询以了解更多关于你的程序。
例如,如果您在命令行中提供无效参数,请考虑使用信息aquarium.py打印,试着在命令行上用错误参数调用aquarium.py来运行:
1python3 aquarium.py --not-a-valid-argument
如果您运行此命令,您将收到这样的输出:
1[secondary_label Output]
2usage: aquarium.py [-h] tank
3aquarium.py: error: the following arguments are required: tank
在命令行上打印的输出表明尝试运行aquarium.py出现了错误。输出表明用户需要用坦克参数调用aquarium.py。
现在你会发现当你用-h选项呼叫aquarium.py时会发生什么。
1python3 aquarium.py -h
如果您运行此命令,您将收到这样的输出:
1[secondary_label Output]
2usage: aquarium.py [-h] tank
3
4List fish in aquarium.
5
6positional arguments:
7 tank
8
9optional arguments:
10 -h, --help show this help message and exit
正如你可能已经猜到的那样,h选项是帮助的缩写,运行python3 aquarium.py -h(或相当于更长的变体python3 aquarium.py --help)打印了帮助文本,帮助文本实际上是前例中输出的使用文本的更长版本。
默认情况下,当您使用argparse编写一个CLI时,您将自动获得帮助和使用文本,您可以使用它来为其他开发人员记录您的CLI。
到目前为止,您已经编写了一个 CLI,它接受了所需的位置参数. 在下一节中,您将添加一个可选的参数到您的界面,以扩展其功能。
添加一个可选的论点
有时,在您的命令行界面中包含可选参数是有帮助的. 这些选项通常以两个调节字符为前缀,例如 --some-option. 让我们重写 aquarium.py 用以下调整的内容,将一个 --upper-case 选项添加到您的 CLI:
1[label aquarium.py]
2import argparse
3
4tank_to_fish = {
5 "tank_a": "shark, tuna, herring",
6 "tank_b": "cod, flounder",
7}
8
9parser = argparse.ArgumentParser(description="List fish in aquarium.")
10parser.add_argument("tank", type=str)
11parser.add_argument("--upper-case", default=False, action="store_true")
12args = parser.parse_args()
13
14fish = tank_to_fish.get(args.tank, "")
15
16if args.upper_case:
17 fish = fish.upper()
18
19print(fish)
尝试用新的--upper-case参数调用aquarium.py,运行以下操作:
1python3 aquarium.py --upper-case tank_a
如果您运行此命令,您将收到这样的输出:
1[secondary_label Output]
2SHARK, TUNA, HERRING
你通过添加一个新的 --upper-case 选项,当你调用 parser.add_argument("--upper-case", default=False, action="store_true")。
如果 CLI 用户未提供 --上级案例' 选项,则 default=False' 会确保其值默认设置为 False'。 action="store_true' 会控制当 CLI 用户提供 `--上级案例' 选项时会发生什么。
请注意,尽管参数是由一个 dash 隔开的两个单词,但在您调用parser.parse_args()后,argparse 会将其作为args.upper_case提供给您的代码,以便在您调用parse_args()后使用有效的 Python 标识符。
与以前一样,argparse 会自动创建一个--帮助选项,并记录您的命令行界面(包括您刚刚添加的--上方案例选项)。
尝试用--help选项再次召唤aquarium.py,以获取更新的帮助文本:
1python3 aquarium.py --help
您的输出将类似于:
1[secondary_label Output]
2usage: aquarium.py [-h] [--upper-case] tank
3
4List fish in aquarium.
5
6positional arguments:
7 tank
8
9optional arguments:
10 -h, --help show this help message and exit
11 --upper-case
argparse自动记录了定位的坦克参数、可选的--上级案例选项以及内置的--帮助选项。
此帮助文本有用,但您可以用额外的信息来改进它,以帮助用户更好地了解如何调用您的程序。
向您的用户展示额外的帮助文本
开发人员使用您的命令行界面提供的帮助文本来了解您的程序能做什么以及他们应该如何使用它. 让我们重新审查 aquarium.py,以便它包含更好的帮助文本. 您可以通过在 add_argument 呼叫中指定 help 字符串来指定论点级别的信息:
1[label aquarium.py]
2import argparse
3
4tank_to_fish = {
5 "tank_a": "shark, tuna, herring",
6 "tank_b": "cod, flounder",
7}
8
9parser = argparse.ArgumentParser(description="List fish in aquarium.")
10parser.add_argument("tank", type=str, help="Tank to print fish from.")
11parser.add_argument(
12 "--upper-case",
13 default=False,
14 action="store_true",
15 help="Upper case the outputted fish.",
16)
17args = parser.parse_args()
18
19fish = tank_to_fish[args.tank]
20
21if args.upper_case:
22 fish = fish.upper()
23
24print(fish)
尝试用--help选项再次召唤aquarium.py,以获取更新的帮助文本:
1python3 aquarium.py --help
您的输出将如下:
1[secondary_label Output]
2usage: aquarium.py [-h] [--upper-case] tank
3
4List fish in aquarium.
5
6positional arguments:
7 tank Tank to print fish from.
8
9optional arguments:
10 -h, --help show this help message and exit
11 --upper-case Upper case the outputted fish.
在此最新输出中,请注意,位置参数 tank 和可选参数 --upper-case 都包含自定义帮助文本. 您提供了此额外的帮助文本,通过向 add_argument 的 help 部分提供字符串。
您可以通过argparse打印您已定义的任何默认值来进一步改进您的帮助文本。
在帮助文本中显示默认值
如果您在实例化ArgumentParser实例时使用自定义formatter_class,则argparse将在帮助文本输出中包含默认值,试着将argparse.ArgumentDefaultsHelpFormatter作为您的ArgumentParser格式化类:
1[label aquarium.py]
2import argparse
3
4tank_to_fish = {
5 "tank_a": "shark, tuna, herring",
6 "tank_b": "cod, flounder",
7}
8
9parser = argparse.ArgumentParser(
10 description="List fish in aquarium.",
11 formatter_class=argparse.ArgumentDefaultsHelpFormatter,
12)
13parser.add_argument("tank", type=str, help="Tank to print fish from.")
14parser.add_argument(
15 "--upper-case",
16 default=False,
17 action="store_true",
18 help="Upper case the outputted fish.",
19)
20args = parser.parse_args()
21
22fish = tank_to_fish[args.tank]
23
24if args.upper_case:
25 fish = fish.upper()
26
27print(fish)
现在,尝试用--help选项再次调用aquarium.py来检查更新的帮助文本:
1python3 aquarium.py --help
运行此命令后,您将收到这样的输出:
1[secondary_label Output]
2usage: aquarium.py [-h] [--upper-case] tank
3
4List fish in aquarium.
5
6positional arguments:
7 tank Tank to print fish from.
8
9optional arguments:
10 -h, --help show this help message and exit
11 --upper-case Upper case the outputted fish. (default: False)
在此最新的输出中,请注意,对「--upper-case」的文档以对「--upper-case」选项的默认值(「Default: False」)的表示结束。
结论
argparse模块是Python标准库的一个强大的组成部分,允许您为您的代码编写命令行界面.本教程向您介绍了argparse的基础:您编写了一个命令行界面,它接受了定位和可选参数,并向用户展示了帮助文本。
「argparse」支持更多的功能,您可以用来编写复杂的输入和验证套件的命令行程序。从这里,您可以使用「argparse」模块的文档(https://docs.python.org/3/library/argparse.html#module-argparse)来了解更多关于其他可用的类和实用程序。