如何使用 argparse 在 Python 中编写命令行程序

作者选择了COVID-19 救济基金来接受捐赠，作为Write for DOnations计划的一部分。

介绍

Python 的argparse标准库模块是一种工具，可帮助您通过 Python 代码编写命令行界面 (CLI)。您可能已经熟悉 CLI：诸如git、ls、grep和 之类的程序find都公开了命令行界面，允许您使用特定的输入和选项调用底层程序。argparse允许你调用类似于你怎么可能调用命令行参数自定义的Python代码git，ls，grep，或者find使用命令行。如果您希望允许其他开发人员从命令行运行您的代码，您可能会发现这很有用。

在本教程中，您将使用 Python 的argparse标准库模块公开的一些实用程序。您将编写接受位置和可选参数的命令行接口来控制底层程序的行为。您还将通过提供可以显示给使用您的 CLI 的其他开发人员的帮助文本来自行记录 CLI。

在本教程中，您将为跟踪虚构水族馆中的鱼的程序编写命令行界面。

先决条件

为了充分利用本教程，我们建议您：

  • 对 Python 3 编程有一定的了解。您可以查看我们的How To Code in Python 3系列教程以了解背景知识。

编写接受位置参数的命令行程序

您可以使用该argparse模块编写接受位置参数的命令行界面。位置参数（与可选参数相反，我们将在后续部分中探讨）通常用于指定程序所需的输入。

让我们考虑一个示例 CLI，它打印由位置tank参数标识的水族箱中的鱼。

要创建 CLI，请使用文本编辑器打开一个文件：

  • nano aquarium.py

然后，添加以下 Python 代码：

水族馆.py
import argparse

tank_to_fish = {
    "tank_a": "shark, tuna, herring",
    "tank_b": "cod, flounder",
}

parser = argparse.ArgumentParser(description="List fish in aquarium.")
parser.add_argument("tank", type=str)
args = parser.parse_args()

fish = tank_to_fish.get(args.tank, "")
print(fish)

您可以tank_a通过运行以下命令打印出鱼：

  • python3 aquarium.py tank_a

运行该命令后，您将收到如下输出：

Output
shark, tuna, herring

同样，如果你运行aquarium.py打印出鱼tank_b：

  • python3 aquarium.py tank_b

您将收到如下输出：

Output
cod, flounder

让我们分解aquarium.py.

首先，您导入argparse模块以使其可用于您的程序。接下来，您将创建一个字典数据结构tank_to_fish，将水箱名称（如tank_a和tank_b）映射到这些水箱中鱼的字符串描述。

您实例化ArgumentParser类的一个实例并将其绑定到parser变量。您可以将其parser视为配置命令行界面的主要入口点。description提供给的字符串（parser稍后您将了解到）用于由 公开的 CLI 的自动生成帮助文本aquarium.py。

调用add_argument解析器允许您添加命令行界面接受的参数。在这种情况下，您添加一个名为tank字符串类型的参数。调用parser.parse_args()指示parser处理和验证传递给aquarium.py（例如，类似tank_a）的命令行输入。访问args返回的 byparser.parse_args()允许您检索传入tank参数的值，并使用它来print找出该坦克中的鱼。

此时，您已经编写了一个命令行界面并执行了打印fish 的程序。现在您需要向其他开发人员描述您的 CLI 如何工作。argparse强烈支持帮助文本来记录您的 CLI。接下来，您将了解有关帮助文本的更多信息。

查看帮助文本

aquarium.py您刚刚在上一节中编写的文件实际上不仅仅是打印特定坦克中的鱼。由于您使用的是argparse，由 公开的命令行界面aquarium.py将自动包含帮助和使用消息，用户可以查阅这些消息以了解有关您的程序的更多信息。

例如，考虑一下，aquarium.py如果您在命令行上提供无效参数，则会打印使用消息。尝试aquarium.py通过运行以下命令在命令行上使用错误的参数进行调用：

  • python3 aquarium.py --not-a-valid-argument

如果您运行此命令，您将收到如下输出：

Output
usage: aquarium.py [-h] tank
aquarium.py: error: the following arguments are required: tank

命令行上打印的输出表明尝试运行时出错aquarium.py。输出表明用户需要aquarium.py使用tank参数进行调用。您可能会注意到的另一件事是-h中间[]字符。这表示这-h是您也可以提供的可选参数。

现在您将了解当您aquarium.py使用该-h选项跟注时会发生什么。尝试调用aquarium.py与-h运行在命令行参数：

  • python3 aquarium.py -h

如果您运行此命令，您将收到如下输出：

Output
usage: aquarium.py [-h] tank

List fish in aquarium.

positional arguments:
  tank

optional arguments:
  -h, --help  show this help message and exit

您可能已经猜到了，该-h选项是“帮助”的缩写。运行python3 aquarium.py -h（或等效地，更长的变体python3 aquarium.py --help）打印出帮助文本。实际上，帮助文本是上一个示例中当您提供无效参数时输出的用法文本的较长版本。值得注意的是，帮助文本还包括您在本教程前面实例化的自定义description字符串。List fish in an aquariumArgumentParser

默认情况下，当您使用编写 CLI 时，argparse您将自动获得帮助和使用文本，您可以使用这些文本为其他开发人员记录您的 CLI。

到目前为止，您已经编写了一个接受所需位置参数的 CLI。在下一部分中，您将向接口添加一个可选参数以扩展其功能。

添加可选参数

有时，在命令行界面中包含可选参数会很有帮助。这些选项通常以两个破折号字符为前缀，例如--some-option。让我们aquarium.py用以下调整后的内容重写，--upper-case为您的 CLI添加一个选项：

水族馆.py
import argparse

tank_to_fish = {
    "tank_a": "shark, tuna, herring",
    "tank_b": "cod, flounder",
}

parser = argparse.ArgumentParser(description="List fish in aquarium.")
parser.add_argument("tank", type=str)
parser.add_argument("--upper-case", default=False, action="store_true")
args = parser.parse_args()

fish = tank_to_fish.get(args.tank, "")

if args.upper_case:
    fish = fish.upper()

print(fish)

尝试通过运行以下命令aquarium.py使用新--upper-case参数进行调用：

  • python3 aquarium.py --upper-case tank_a

如果您运行此命令，您将收到如下输出：

Output
SHARK, TUNA, HERRING

输入的鱼tank_a现在以大写形式输出。您通过--upper-case在调用 时添加一个新选项来实现这一点parser.add_argument("--upper-case", default=False, action="store_true")。该"--upper-case"字符串是您要添加的参数的名称。

如果--upper-caseCLI 的用户未提供该选项，请default=False确保将其值设置为False默认值。action="store_true"控制当--upper-caseCLI 用户提供选项时会发生什么。参数支持action许多不同的可能字符串，但如果在命令行上提供，则将"store_true"值存储True到参数中。

需要注意的是，尽管这些说法是两个词分开一个破折号（upper-case），argparse使其可用于您的代码args.upper_case（用下划线分隔），之后您调用parser.parse_args()。通常，argparse 将提供的参数中的任何破折号转换为下划线，以便在调用parse_args().

和以前一样，argparse自动创建一个--help选项并记录您的命令行界面（包括--upper-case您刚刚添加的选项）。

尝试再次调用aquarium.py该--help选项以接收更新的帮助文本：

  • python3 aquarium.py --help

您的输出将类似于：

Output
usage: aquarium.py [-h] [--upper-case] tank

List fish in aquarium.

positional arguments:
  tank

optional arguments:
  -h, --help    show this help message and exit
  --upper-case

argparse自动记录位置tank参数、可选--upper-case选项和内置--help选项。

此帮助文本很有用，但您可以使用其他信息对其进行改进，以帮助用户更好地了解他们如何调用您的程序。您将在下一部分探索如何增强帮助文本。

向用户公开其他帮助文本

开发人员使用您的命令行界面提供的帮助文本来了解您的程序的功能以及他们应该如何使用它。让我们aquarium.py再次修改，使其包含更好的帮助文本。您可以通过help在add_argument调用中指定字符串来指定参数级信息：

水族馆.py
import argparse

tank_to_fish = {
    "tank_a": "shark, tuna, herring",
    "tank_b": "cod, flounder",
}

parser = argparse.ArgumentParser(description="List fish in aquarium.")
parser.add_argument("tank", type=str, help="Tank to print fish from.")
parser.add_argument(
    "--upper-case",
    default=False,
    action="store_true",
    help="Upper case the outputted fish.",
)
args = parser.parse_args()

fish = tank_to_fish[args.tank]

if args.upper_case:
    fish = fish.upper()

print(fish)

尝试再次调用aquarium.py该--help选项以接收更新的帮助文本：

  • python3 aquarium.py --help

您的输出将如下所示：

Output
usage: aquarium.py [-h] [--upper-case] tank

List fish in aquarium.

positional arguments:
  tank          Tank to print fish from.

optional arguments:
  -h, --help    show this help message and exit
  --upper-case  Upper case the outputted fish.

在这个最新的输出中，请注意tank位置参数和--upper-case可选参数都包含自定义帮助文本。您可以通过给供应串提供这些额外的帮助文本help的一部分add_argument。（例如，parser.add_argument("tank", type=str, help="Tank to print fish from.").）argparse获取这些字符串并在帮助文本输出中为您呈现它们。

您可以通过argparse打印出您定义的任何默认值来进一步改进您的帮助文本。

在帮助文本中显示默认值

如果formatter_class在实例化ArgumentParser实例时使用自定义，argparse将在帮助文本输出中包含默认值。尝试添加argparse.ArgumentDefaultsHelpFormatter为您的ArgumentParser格式化程序类：

水族馆.py
import argparse

tank_to_fish = {
    "tank_a": "shark, tuna, herring",
    "tank_b": "cod, flounder",
}

parser = argparse.ArgumentParser(
    description="List fish in aquarium.",
    formatter_class=argparse.ArgumentDefaultsHelpFormatter,
)
parser.add_argument("tank", type=str, help="Tank to print fish from.")
parser.add_argument(
    "--upper-case",
    default=False,
    action="store_true",
    help="Upper case the outputted fish.",
)
args = parser.parse_args()

fish = tank_to_fish[args.tank]

if args.upper_case:
    fish = fish.upper()

print(fish)

现在，尝试再次调用aquarium.py该--help选项以检查更新的帮助文本：

  • python3 aquarium.py --help

运行此命令后，您将收到如下输出：

Output
usage: aquarium.py [-h] [--upper-case] tank

List fish in aquarium.

positional arguments:
  tank          Tank to print fish from.

optional arguments:
  -h, --help    show this help message and exit
  --upper-case  Upper case the outputted fish. (default: False)

在这个最新的输出中，请注意 的文档以选项 ( )--upper-case的默认值的指示结束。通过包括为你的，会自动开始在它的帮助文本渲染默认值的信息。--upper-casedefault: Falseargparse.ArgumentDefaultsHelpFormatterformatter_classArgumentParserargparse

结论

该argparse模块是 Python 标准库的一个强大部分，它允许您为代码编写命令行界面。本教程向您介绍了以下基础argparse：您编写了一个命令行界面，该界面接受位置和可选参数，并向用户公开帮助文本。

argparse支持更多功能，您可以使用这些功能编写具有复杂输入和验证集的命令行程序。在这里，您可以使用该argparse模块的文档，详细了解其他可用的类和公用事业。

觉得文章有用？

点个广告表达一下你的爱意吧 ！😁