打包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

译者：张新英