打包python库

我认为应该重新定义打包的最优方法,现在有许多好的工具,要么不用,要么用得不多。最好重新评估最优方法。

这里假设包将在多个Python版本上进行测试,其中包含不同的依赖版本、设置等的组合。

打包时我喜欢遵循的几个原则:

如果有工具可以帮助你进行测试,使用它。如果你可以使用py.test或者nose,不要浪费时间来构建自定义的测试程序。它们带有大型生态系统插件,可以改进你的测试。

在可能的情况下,尽早预防问题。这主要是严格的测试和详尽的测试。防止常见错误的设计。

收集所有覆盖数据。记录。识别回归。

测试所有可能的配置。

结构

这是相当重要的,一切都围绕着这个。我喜欢这种结构:

src目录是一种较好的方法,因为:

你不得不编写和用户一样的导入语句。当前目录隐式包含在sys.path中;但是当从site-packegs安装和导入时不是这样。用户永远不会有与你相同的当前工作目录。

这种限制在测试和打包中都有有益的:

您将被迫测试已安装的代码(因为你也需要在virtualenv中安装一遍才能使用)。这将确保部署的代码工作正常(打包正确)——否则你的测试将失败。这让你不会发布那种完全不能用的软件包。

您将被迫安装发布。如果你曾经在PyPI上上传一个带有缺失模块或错误依赖项的发行版,那是因为你没有测试安装。只是能够成功地建造sdist,不保证它会真的安装成功。

它阻止你轻松导入setup.py脚本中的代码。这是一种不好的做法,因为如果导入主包或模块触发对依赖项的额外导入(可能不可用),它总是会放大。最好不要让它成为可能。

简单的打包代码和清单。它使清单写起来非常简单(如:你打包有一个有模板或静态文件的Django应用程序)。同样,对于拥有多个包的大型库来说,多个包之间也不会混淆。明确被打包代码和打包代码的分离。

不建立src目录而编写MANIFEST.in颇为不易。如果你的manifest写得不正确,测试将失败。而使用src目录就会容易很多:只需在MANIFEST.in中添加graft src。

发布坏掉的的包给PyPI是不好玩的。

没有src目录,你会得到乱七八糟的可编辑安装(“setup.py develop"或者"pip install -e")。没有分离(没有src目录)将迫使setuptools将项目的根放在sys.path上——其中包含所有无用的东西(例如:setup.py和其它测试或配置脚本将无意中变得可导入)。

还有更好的工具。你不需要处理安装包就可以运行测试了。只使用tox——它将自动为你安装包,零摩擦,零摩擦。

用户错误的可能更少。

更少的工具将代码与非代码混合的可能。

有的人说,扁平胜于嵌套,但这种思想并不适用于数据。毕竟,文件系统就是数据,而数据重要的是内聚性以及结构良好。

你将注意到,我没有在安装的包中包含测试。因为:

模块发现工具将使你的测试模块失败。测试模块中经常发生奇怪的事情。内置help进行模块发现。例如:

测试通常需要额外的依赖项才能运行,因此它们本身并没用——你不能直接运行它们。

测试关注的是开发,而不是使用。

非常不可能的是库的用户而不是库的开发人员运行测试。例如:在测试应用程序时,不需要运行Django的测试——Django已经测试过。

替代品

src目录中结构更少,几个例子:

这两种结构之所以流行,是因为几年前打包存在许多问题,所以安装包只是为了测试它是不可行的。人们仍然推荐它们,即使它是基于旧的和过时的设定。

大多数项目都错误地使用了它们,因为除了Twisted"s trial之外,所有测试运行程序都有不正确的当前工作目录的默认值——如果不测试已安装的代码,那么你将测试错误的代码。trial通过将工作目录更改为临时目录来做正确的事情,但是大多数项目不使用trial。

安装脚本

遗憾的是,目前的打包工具存在很多缺陷。setup.by脚本应该尽可能简单:

这有什么特别之处:

没有exec或者import技巧。

包括src:packages或者root-level模块中的所有内容。

显式编码。

运行测试

再次,似乎人们喜欢运行python setup.py test来运行包测试。我认为这不值得做——setup.py test是一个复制CPAN测试系统的失败的实验。Python没有通用的测试结果协议,所以没有通用的测试命令。至少现在没有——我们需要一些人来建立使这一切有价值的规范和服务,并支持他们。我认为,一般来说,认识到失败的地方,并在必要时回到起点很重要——绝对没有任何服务或工具以带来附加值的方式使用setup.py test命令。这里肯定出了问题。

我相信现在对PyPI来说做任何事情都已经太晚了,Travis已经是一个稳固、可靠、极其灵活和免费的替代品。它与Github集成得非常好——将为每个Pull Request自动运行构建。

测试本地tox是运行所有可能的测试配置的一种非常好的方法(每个配置将是一个tox环境)。我喜欢用这些额外的环境把测试组织成矩阵:

check——检查包元数据(例如:如果你的长文本中的重构文本是有效的)

clean——净覆盖率

report——为所有积累的数据做覆盖报告

docs——构建sphinx文档

我也喜欢有或没有覆盖测量的环境,并一直运行它们。竟态条件通常对性能敏感,如果使用覆盖率测量运行所有内容,则不太可能捕获它们。

测试矩阵

根据依赖性,你通常会得到大量的Python版本、依赖版本和不同设置的组合。

通常人们只是硬编码tox.ini或仅是.travis.yml中的一切。它们最终得到不完整的本地测试或Travis中连续运行的测试配置。我试过了,不喜欢。我试过复制tox.ini和.travis.yml中的环境。还是不喜欢它。

由于没有现成的可用选项来生成配置,因此我实现了一个使用模板来生成tox.ini和.travis.ym的生成器脚本。最好的方式是DRY,你可以轻松地跳过特定配置上的运行测试(例如:在Python 3上跳过Django 1.4),并且改变的工作就更少了。

基本要素(完整的代码):

setup.cfg

生成器脚本使用配置文件(setup.cfg为方便起见):

ci/bootstrap.py

这是生成器脚本。每当您想要重新配置配置时,就运行此操作。

ci/templates/.travis.yml

这里面有很多吸引人的东西:非常有用libSegFault.so trick。

它基本上只运行tox。

ci/templates/tox.ini

ci/templates/appveyor.ini

对于Windows友好的项目:

如果你有足够的耐心阅读,你会注意到的:

Travis配置为矩阵中的每个项目使用tox。这使得Travis中的测试与本地测试一致。

tox的环境顺序是clean,check,2.6-1.3,2.6-1.4,……,report。

具有覆盖率测量的环境无需安装即可运行代码(usedevelop = true),以便覆盖率可以在最后组合所有测量。

没有覆盖的环境将持续存在并安装到virtualenv中(tox的默认行为),以便尽早发现打包问题。

report环境将最终的所有运行合并为单个报告。

拥有tox.ini中完整的环境清单是一个巨大的优势:

你在本地并行运行所有的东西(如果你的测试不需要严格的隔离)和detox。如果你想使用drone.io而不是Travis,你仍然可以并行运行所有的东西。

你可以为本地的一切(将所有环境的覆盖测量合并为单个环境)测量累积的覆盖率。

测试覆盖率

Coveralls——一种跟踪覆盖时间和多个构建的好方法。它会自动添加关于Gitbub Pull Request覆盖率变化的注释。

TL;DR

将代码放入src。

使用tox和detox。

有无覆盖测量测试。

为tox.ini和.travis.ini使用生成器脚本。

在Travis中用tox运行测试以保持与本地测试的一致性。

太复杂?只需使用Python包模板。

不够说服力?阅读Hynek的文章关于scr结构。

英文原文:https://qiniumedia.freelycode.com/vcdn/1/%E4%BC%98%E8%B4%A8%E6%96%87%E7%AB%A0%E9%95%BF%E5%9B%BE2/package_a_python_lib.pdf

译者:张新英

  • 发表于:
  • 原文链接https://kuaibao.qq.com/s/20181218A07F2200?refer=cp_1026
  • 腾讯「云+社区」是腾讯内容开放平台帐号(企鹅号)传播渠道之一,根据《腾讯内容开放平台服务协议》转载发布内容。
  • 如有侵权,请联系 yunjia_community@tencent.com 删除。

扫码关注云+社区

领取腾讯云代金券