如何将 Python 脚本转换为命令行应用程序

利用 Python 中的 scaffold 和 click， 可以将一个简单的实用工具升级为一个成熟的命令行界面工具。

在我们的职业生涯中， 一定写过、使用过以及看到过很多松散的脚本， 也经常会希望在这些脚本中能够体会到更像命令行工具的感受。 然而，将质量水平从一次性脚本提升到适当的工具到底有多难呢？ 事实证明， 这在 Python 中其实并不难。

Scaffold

在本文中，将从 Python 的片段开始， 将其放到 scaffold 模块中， 并通过 click 以接受命令行参数来进行扩展。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

#!/usr/bin/python

from glob import glob
from os.path import join, basename
from shutil import move
from datetime import datetime
from os import link, unlink

LATEST = 'latest.txt'
ARCHIVE = '/Users/mark/archive'
INCOMING = '/Users/mark/incoming'
TPATTERN = '%Y-%m-%d'

def transmogrify_filename(fname):
    bname = basename(fname)
    ts = datetime.now().strftime(TPATTERN)
    return '-'.join([ts, bname])

def set_current_latest(file):
    latest = join(ARCHIVE, LATEST)
    try:
        unlink(latest)
    except:
        pass
    link(file, latest)

def rotate_file(source):
    target = join(ARCHIVE, transmogrify_filename(source))
    move(source, target)
    set_current_latest(target)

def rotoscope():
    file_no = 0
    folder = join(INCOMING, '*.txt')
    print(f'Looking in {INCOMING}')
    for file in glob(folder):
        rotate_file(file)
        print(f'Rotated: {file}')
        file_no = file_no + 1
    print(f'Total files rotated: {file_no}')

if __name__ == '__main__':
    print('This is rotoscope 0.4.1. Bleep, bloop.')
    rotoscope()

本文中的所有非内联代码示例都引用了代码的特定版本， 可在 https://codeberg.org/ofosos/rotoscope 找到特定版本的代码。 该 repo 中的每一次提交都描述了本操作指南文章中的一些有意义步骤。

此代码段可执行以下操作：

• 检查传入文件中指定的路径中是否有任何文本文件；
• 如果存在，它将创建一个具有当前时间戳的新文件名，移动并存档；
• 删除当前存档/最新存档，txt 链接并创建一个指向刚刚添加新文件。

利用 pyscaffold 创建应用程序

首先，需要安装 scaffold、click 和 tox Python 模块。

$ python3 -m pip install scaffold click tox

安装 scaffold 后， 切换到示例 rotoscope 项目所在的目录， 并执行以下命令：

$ putup rotoscope -p rotoscope \
--force --no-skeleton -n rotoscope \
-d 'Move some files around.' -l GLWT \
-u http://codeberg.org/ofosos/rotoscope \
--save-config --pre-commit --markdown

Pyscaffold 覆盖了 README.md， 可在 Git 中进行恢复：

$ git checkout README.md

Pyscaffold 在文档层次结构中设置了一个完整的示例项目， 除此外， Pyscaffold 还可以在项目中提供持续集成（CI）模板，具体如下：

• 打包：项目现在已启用 PyPi，因此可将其下载到 repo 并安装；
• 文档：目前有一个完整的文档文件夹层次结构，基于 Sphinx 并包括 readthedocs.org 构建器；
• 测试：可与 tox 测试运行器一起使用， tests 文件夹包含运行基于 pytest 测试所需的所有样板文件；
• 依赖关系管理：打包和测试基础设施都需要一种管理依赖关系的方法， setup.cfg 文件解决了此问题，并包含依赖项；
• 预提交 hook：包括 Python 源格式化程序 “black” 和 “flake8” Python 样式检查器。

创建 Git 标记（例如，v0.2）， 该工具将其识别为可安装版本。 在提交更改之前， 先浏览自动生成的 setup.cfg， 并根据用例对其进行编辑。 对于此示例，可以修改 LICENSE 和项目描述。 如果要将这些更改添加到 Git 的暂存区域， 需要禁用预提交 hook 来提交， 否则会遇到错误。

$ PRE_COMMIT_ALLOW_NO_CONFIG=1 git commit

如能有一个入口点可以进入此脚本， 用户就可以从命令行调用， 而现在只能通过查找 .py 文件并手动执行来运行。 幸运的是，Python 的打包基础设施有一个很好的 "canned" 方式， 可以使配置更改变得很容易， 同时可将以下内容添加到 options.entry_points 中的 setup.cfg 部分 ：

console_scripts =
    roto = rotoscope.rotoscope:rotoscope

此更改创建了名为 roto 的 shell 命令， 能够使用该命令调用 rotoscope 脚本。 使用 pip 安装 rotoscope 后， 执行roto 命令。 从 Pyscaffold 中免费获得所有的打包、测试和文档设置。

命令行工具

现在，有一些值硬编码到脚本中， 作为命令参数会更方便。 例如，INCOMING 常数作为命令行参数会更好。

首先，导入 Click 库。 利用 Click 提供的命令对 rotoscope() 方法进行注释， 并添加 Click 传递给 rotoscope 函数的参数。 Click 提供了一组验证器， 因此在参数中添加一个路径验证器。 Click 还可以方便地使用函数的 here 字符串作为命令行文档的一部分。 因此最终会得到以下方法签名：

@click.command()
@click.argument('incoming', type=click.Path(exists=True))
def rotoscope(incoming):
    """
    Rotoscope 0.4 - Bleep, blooop.
    Simple sample that move files.
    """

主要部分调用 rotoscope()， 现在是一个 Click 命令, 因此不需要传递任何参数， 选项也可以由 环境变量 自动填充。 例如，将 ARCHIVE 常量更改为选项：

@click.option('archive', '--archive', default='/Users/mark/archive', envvar='ROTO_ARCHIVE', type=click.Path())

相同的路径验证程序再次应用。 这一次， 允许 Click 填充环境变量， 如果环境没有提供任何内容， 则默认为旧常量的值， 同时具有彩色控制台输出、提示和子命令的功能， 允许构建复杂的 CLI 工具， 浏览 Click 文档会发现其更强大的功能。 并能添加一些测试。

测试

Click 提供了一些关于使用 CLI runner 运行程序端到端测试 的建议， 可以利用它来实现一个完整的测试（在 示例项目 中，测试位于 tests 文件夹中）， 测试位于测试类的方法中。 大多数都非常接近其他 Python 项目中使用的约定， 但也有一些细节， 因为 rotoscope 使用 click。 在该 test 方法中， 创建了 CliRunner。 测试使用此命令在隔离文件系统中运行命令, 测试创建传入和归档目录以及一个虚拟传入/测试, incoming/test.txt 文件调用 CliRunner， 就如调用命令行应用程序一样。 运行完成后， 测试将检查隔离的文件系统， 并验证 incoming 文件是否为空， 以及 archive 包含两个文件（最新链接和归档文件）。

from os import listdir, mkdir
from click.testing import CliRunner
from rotoscope.rotoscope import rotoscope

class TestRotoscope:
    def test_roto_good(self, tmp_path):
        runner = CliRunner()

        with runner.isolated_filesystem(temp_dir=tmp_path) as td:
            mkdir("incoming")
            mkdir("archive")
            with open("incoming/test.txt", "w") as f:
                f.write("hello")

            result = runner.invoke(rotoscope, ["incoming", "--archive", "archive"])
            assert result.exit_code == 0

            print(td)
            incoming_f = listdir("incoming")
            archive_f = listdir("archive")
            assert len(incoming_f) == 0
            assert len(archive_f) == 2

要在控制台上执行这些测试， 请在项目的根目录中运行 tox。

在实现测试的过程中， 在代码中发现了一个 bug。 当进行 Click 转换时， rotoscope 只是断开了最新文件的链接， 无论它是否存在。 测试从一个新的文件系统（而不是主文件夹）开始， 不过很快以失败告终。 我们可以通过在一个完全隔离和自动化的测试环境中运行来防止这种错误， 这将避免很多 “在我的机器上运行没有问题” 的情况。

Scaffolding 和模块

这样就完成了对可以使用 Scaffold 和进行高级操作的介绍 click。 有很多可能性可以升级一个随意的 Python 脚本， 甚至可以将简单实用程序变为成熟的 CLI 工具。

以上完成了对可以使用 Scaffold 和 click 执行的高级操作的介绍。 有很多可能性可以升级一个随意的Python脚本， 甚至让你的简单实用程序成为成熟的CLI工具。