摘要：本文翻译自 Python Plumbum 开源库的官方文档 Plumbum CLI 部分，主要介绍如何使用 Plumbum CLI 工具包来开发 Python 命令行应用程序，这是一个非常 Pythonic、容易使用、功能强大的工具包，非常值得广大 Python 程序员掌握并使用。

轻松执行程序的另一方面是轻松编写 CLI 程序。Python 脚本一般使用 optparse 或者最新的 argparse 及其衍生品来开发命令行工具，但是所有这些表现力有限，而且非常不直观（甚至不够 Pythonic）。Plumbum 的 CLI 工具包提供了一个程序化的方法来构建命令行应用程序，不需要创建一个解析器对象，然后填充一系列“选项”，该 CLI 工具包使用内省机制将这些原语转义成 Pythonic 结构。

总体来看，Plumbum CLI 应用程序是一个继承自 plumbum.cli.Application 的类。这些类定义了一个 main() 方法，并且可选地公开出方法和属性来作为命令行的选项。这些选项可能需要参数，而任何剩余的位置参数会根据 main 函数的声明来将其赋予 main 方法。一个简单的 CLI 应用程序看起来像如下这样：

你可以运行该程序：

到现在为止，你只看到了非常基本的使用。我们现在开始探索该库。

新版本 1.6.1： 你可以直接运行应用程序 MyApp()，不需要参数，也不需要调用 .main()。

Application 类是你的应用程序的“容器”，该“容器”由一个你需要实现的main()方法和任何数量公开选项函数和属性。你的应用程序的入口是类方法 run，该方法实例化你的类、解析参数、调用所有的选项函数，然后使用给的位置参数来调用main()函数。为了从命令行运行你的应用程序，你所要做的是：

除了 run() 和 main()，Application 类还公开了两个内置的选项函数：help() 和 version()，分别用于显示帮助和程序的版本。默认情况下，--hep 和 -h 会调用 help()，--version 和 -v 会调用 version()，这些函数被调用后会显示相应的信息然后退出（没有处理任何其他选项）。

你可以通过定义类属性来自定义 help() 和 version() 显示的信息，比如 PROGNAME、 VERSION 和 DESCRIPTION。举例：

新版本 1.6

该库也支持终端字符颜色控制。你可以直接将 PROGNAME, VERSION 和 DESCRIPTION 变为带颜色的字符串。如果你给 PROGNAME 设置了颜色，你会得到自定义的程序名字和颜色。使用方法字符串的颜色可以通过设置 COLOR_USAGE 来生效，不同选项组的颜色可以通过设置 COLOR_GROUPS 字典来生效。

举例如下：

switch 装饰器是该 CLI 开发工具包的“灵魂”，它会公开你的 CLI 应用程序的方法来作为 CLI 命令行选项，这些方法运行通过命令行来调用。我们测试下如下应用：

当程序运行时，选项函数通过相应的参数被调用。比如，$ ./myapp.py --log-to-file=/tmp/log 将被转化成调用 app.log_to_file("/tmp/log")。在选项函数被执行后，程序的控制权会被传递到 main 方法。

如上面例子所示，选项函数可能没有参数（不包括 self）或者有一个参数。如果选项函数接受一个参数，必须指明该参数的类型。如果你不需要特殊的验证，只需传递 str，否则，您可能会传递任何类型（或实际上可调用的任何类型），该类型将接收一个字符串并将其转换为有意义的对象。如果转换是不可行的，那么会抛出 TypeError 或者 ValueError 异常。

举例：

工具包包含两个额外的“类型”（或者是是验证器）：Range 和 Set。Range 指定一个最小值和最大值，限定一个整数在该范围内（闭区间）。Set 指定一组允许的值，并且期望参数匹配这些值中的一个。示例如下：

很多时候，你需要在同一个命令行中多次指定某个选项。比如，在 gcc 中，你可能使用 -I 参数来引入多个目录。默认情况下，选项只能指定一次，除非你给 switch 装饰器传递 list = True 参数。

如果某个选项是必须的，你可以给 switch 装饰器传递 mandatory = True 来实现。这样的话，如果用户不指定该选项，那么程序是无法运行的。

很多时候，一个选项的出现依赖另一个选项，比如，如果不给定 -y 选项，那么 -x 选项是无法给定的。这种限制可以通过给 switch 装饰器传递 requires 参数来实现，该参数是一个当前选项所依赖的选项名称列表。如果不指定某个选项所依赖的其他选项，那么用户是无法运行程序的。

有些选项依赖其他选项，但是有些选项是和其他选项互斥的。比如，--verbose 和 --terse 同时存在是不合理的。为此，你可以给 switch 装饰器指定 excludes 列表来实现。

如果你希望在帮助信息中将某些选项组合在一起，你可以给 switch 装饰器指定 group = "Group Name", Group Name 可以是任意字符串。当显示帮助信息的时候，所有属于同一个组的选项会被聚合在一起。注意，分组不影响选项的处理，但是可以增强帮助信息的可读性。

很多时候只需要将选项的参数存储到类的属性中，或者当某个属性给定后设置一个标志。为此，工具包提供了 SwitchAttr，这是一个数据描述符，用来存储参数。 该工具包还提供了两个额外的 SwitchAttr:Flag（如果选项给定后，会给其赋予默认值）和 CountOf （某个选项出现的次数）。

新版本 1.6

你可以使用 envname 参数将环境变量作为 SwitchAttr 的输入。举例如下：

在命令行给定变量值会覆盖相同环境变量的值。

一旦当所有命令行参数被处理后 ，main() 方法会获取程序的控制，并且可以有任意数量的位置参数，比如，在 cp -r /foo /bar 中, /foo 和 /bar 是位置参数。程序接受位置参数的数量依赖于 main() 函数的声明：如果 main 方法有 5 个参数，2 个是有默认值的，那么用户最少需要提供 3 个位置参数并且总数量不能多于 5 个。如果 main 方法的声明中使用的是可变参数（*args），那么位置参数的个数是没有限制的。

使用可变参数：

新版本 1.6

你可以使用 cli.positional 装饰器提供的验证器来验证位置参数。只需在装饰器中传递与 main 函数中的相匹配的验证器即可。例如：

如果你的程序只在 Python 3 中运行，你可以使用注解来指定验证器，例如：

如果 positional 装饰器存在，那么注解会被忽略。

新版本 1.1

随着 CLI 应用程序的扩展，功能变的越来越多，一个通常的做法是将其逻辑分成多个子应用（或者子命令）。一个典型的例子是版本控制系统，比如 git，git 是根命令，在这之下的子命令比如 commit 或者 push 是嵌套的。git 甚至支持命令别名，这运行用户自己创建一些子命令。Plumbum 写类似这样的程序是很轻松的。

在我们开始了解代码之前，先强调两件事情：