车标大全,用 Plumbum 开发 Python 命令行东西,皇后

本文翻译自 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 办法。

留意

办法的文档字符串和参数姓名会被用来烘托协助信息,尽量坚持你的代码DRY

autoswitch 能够从函数姓名中推断出选项的称号,举例如下:

这会将选项函数和 --log-to-file 绑定。

选项参数

如上面比方所示,选项函数或许没有参数(不包括 self)或许有一个参数。假如选项函数承受一个参数,有必要指明该参数的类型。假如你不需求特别的验证,只需传递str,不然,您或许会传递任何类型(或实际上可调用的任何类型),该类型将接纳一个字符串并将其转化为有意义的目标。假如转化是不可行的,那么会抛出 TypeError 或许 ValueError 反常。

举例:

东西包包括两个额定的“类型”(或许是是验证器):Range 和 Set。Range 指定一个最小值和最大值,约束一个整数在该范围内(闭区间)。Set 指定一组答应的值,而且期望参数匹配这些值中的一个。示例如下:

留意东西包中还有其他有用的验证器:ExistingFile(保证给定的参数是一个存在的文件),ExistingDirectory(保证给定的参数是一个存在的目录),NonexistentPath(保证给定的参数是一个不存在的途径)。一切这些将参数转化为本地途径。

可重复的选项

许多时分,你需求在同一个指令行中屡次指定某个选项。比方,在 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

一旦当一切指令行参数被处理后 ,main办法会获取程序的操控,而且能够有恣意数量的方位参数,比方,在cp -r /foo /bar中,/foo和/bar是方位参数。程序承受方位参数的数量依靠于main函数的声明:假如main办法有 5 个参数,2 个是有默许值的,那么用户最少需求供给 3 个方位参数而且总数量不能多于 5 个。假如main办法的声明中运用的是可变参数(*args),那么方位参数的个数是没有约束的。

留意 该办法的声明也用于生成协助信息,例如:

Usage: [SWITCHES] src dst [mode='normal']

运用可变参数:

方位验证

你能够运用cli.positional装修器供给的验证器来验证方位参数。只需在装修器中传递与main函数中的相匹配的验证器即可。例如:

假如你的程序只在 Python 3 中运转,你能够运用注解来指定验证器,例如:

子指令

新版别 1.1

跟着 CLI 运用程序的扩展,功用变的越来越多,一个一般的做法是将其逻辑分红多个子运用(或许子指令)。一个典型的比方是版别操控系统,比方git,git 是根指令,在这之下的子指令比方 commit 或许 push 是嵌套的。git 乃至支撑指令别号,这运转用户自己创立一些子指令。Plumbum 写相似这样的程序是很轻松的。

在咱们开端了解代码之前,先着重两件工作:

在 Plumbum 中,每个子指令都是一个完好的 cli.Application 运用,你能够独自履行它,或许从所谓的根指令中分离出来。当运用程序独自履行是,它的父特点是 None,当以子指令运转时,它的父特点指向父运用程序。相同,当父运用运用子指令履行时,它的内嵌指令被设置成内嵌运用。

每个子指令只担任它自己的选项参数(直到下一个子指令)。这答应运用在内嵌运用调用之前来处理它自己的选项和方位参数。例如 git --foo=bar spam push origin --tags:根运用 git 担任选项 --foo 和方位选项 spam ,内嵌运用 push 担任在它之后的参数。从理论上讲,你能够将多个子运用程序嵌套到另一个运用程序中,但在实践中,一般嵌套层级只要一层。

这是一个仿照版别操控系统的比方 geet。咱们有一个根运用 Geet ,它有两个子指令 GeetCommit 和 GeetPush:这两个子指令经过 subcommand 装修器来将其附加到根运用。

留意

因为 GeetCommit 也是一个 cli.Application,因而你能够直接调用 GeetCommit.run (这在运用的上下文是合理的)

你也能够不必装修器而运用 subcommand 办法来附加子指令:Geet.subcommand("push", GeetPush)

以下是运转该运用程序的示例:

装备解析器

运用程序的另一个常见的功用是装备文件解析器,解析后台 INI 装备文件:Config(或许ConfigINI)。运用示例:

假如装备文件不存在,那么将会以当时的

key 和默许的 value 来创立一个装备文件,在调用 .get 办法时会得到默许值,当上下文管理器存在时,文件会被创立。假如装备文件存在,那么该文件将会被读取而且没有任何改动。你也能够运用 语法来强制设置一个值或许当变量不存在时获取到一个 ValueError。假如你想防止上下文管理器,你也能够运用 .read 和 .write。

ini 解析器默许运用 [DEFAULT] 段,就像 Python 的 ConfigParser。假如你想运用一个不同的段,只需求在 key 中经过 . 将段和标题分离隔。比方 conf['section.item'] 会将 item放置在 [section] 下。一切存储在 ConfigINI 中的条目会被转化成 str,str 是常常回来的。

终端实用程序

在 plumbum.cli.terminal 中有多个终端实用程序,用来协助制造终端运用程序。

get_terminal_size(default=(80,25)) 答应跨渠道拜访终端屏幕巨细,回来值是一个元组 (width, height)。还有几个办法能够用来问询用户输入,比方 readline, ask, choose和 prompt 都是可用的。

Progress(iterator) 能够使你快速地从迭代器来创立一个进度条。简略地打包一个 slow 迭代器并迭代就会生成一个不错的根据用户屏幕宽度的文本进度条,一起会显现剩下时间。假如你想给 fast 迭代器创立一个进度条,而且在循环中包括代码,那么请运用 Progress.wrap 或许 Progress.range。例如:

假如在终端中有其他输出,可是依然需求一个进度条,请传递 has_output=True 参数来制止进度条清除去前史输出。

在 plumbum.cli.image 中供给了一个指令行绘图器(Image)。它能够制作一个相似 PIL 的图画:

Image.show_pil(im)

Image 结构函数承受一个可选的 size 参数(假如是 None,那么默许是当时终端巨细)和一个字符份额,该份额来自当时字符的高度和宽度的衡量,默许值是 2.45。假如设置为 None,ratio 将会被疏忽,图画不再被约束成份额缩放。要直接制作一个图画,show 需求一个文件名和一对参数。show_pil 和 show_pil_double 办法直接承受一个 PIL-like 目标。为了从指令行制作图画,该模块能够直接被运转:python -m plumbum.cli.image myimage.png。

需求python教程+PDF电子书的小伙伴

请重视、转发、私信我"学习"就能免费获取教程+电子书。