在 PyPI 上上传的 Python 库的分发格式

Question

我完成了将包上传到https://test.pypi.org/的教程，并且成功了。

但是，$python setup.py sdist bdist_wheel 在dist/ 目录中生成一个.whl 文件和一个tar.gz 文件。 twine 允许仅上传 .whl 或 tar.gz 文件或两者。我看到https://pypi.org/ 上的许多存储库都上传了这两种格式。

我想了解什么是最佳做法。一种格式是否优于另一种格式？如果.whl 文件足以分发我的代码，我是否也应该上传tar.gz 文件？或者还有什么我在这里完全想念的。

Answer 1

.tar.gz 是所谓的源代码分发。它包含您的包的源代码和如何构建它的说明，目标系统将在安装它之前执行构建。

.wheel（PEP 427 中的规范详细信息）是一种内置分发格式，这意味着目标系统不再需要构建它。安装轮子通常只是意味着将其内容复制到右侧site-packages。

车轮听起来非常出色，因为它确实如此。 最佳做法是同时上传轮子和源分发，因为任何构建的分发格式仅适用于目标系统的子集。对于package that contains only python code，该子集就是“一切”——尽管人们仍然经常上传源分布，也许是为了在出现新标准的情况下向前兼容^[1]，也许是为了期待system specific extensions这将突然需要源代码分发以支持所有平台，也许可以让用户选择运行具有特定构建参数的自定义构建。

观察不同情况的一个很好的示例包是numpy，它上传了 25 个轮子以覆盖最流行的平台，以及一个源代码分发。如果您从任何受支持的平台安装 numpy，您将获得一个不错的简短安装，只需几秒钟即可复制轮子的内容。如果你在一个不受支持的平台上（比如alpine），一台普通的电脑可能至少需要20分钟从源码编译numpy才能安装，而且你需要安装各种system level dev tools for building C-extensions。有点痛苦，但总比不能全部安装好。

---

^{[1] _{毕竟，在 wheel 之前就有 egg，如果包管理器决定只上传 egg 发行版而不上传，那么采用 wheel 格式会比现在困难得多。来源。}}

Answer 2

最佳做法是同时提供。

为能够使用该发行版的用户提供“内置发行版”(.whl)。这节省了安装时间，因为“构建的发行版”是预先构建的，并且可以在用户机器上放置到位，无需任何编译步骤或不执行 setup.py。一个给定的发行版可能有多个内置发行版——一旦你开始在你的发行版中包含已编译的二进制文件，它们就会成为特定于平台的（例如，参见https://pypi.org/project/tensorflow/#files）

“源分发”（.tar.gz）本质上是任何无法使用您构建的分发的用户的后备。源发行版不是“内置”的，这意味着它们可能需要编译才能安装。至少，它们需要执行构建后端（对于大多数项目，这是调用 setup.py 和 setuptools 作为构建后端）。任何安装程序都应该能够从源代码安装。此外，源代码分发使想要审核您的源代码的用户更容易（尽管这也可以通过内置分发实现）。

对于大多数 Python 项目，将“源代码分发”转换为“构建分发”会产生一个纯 Python 轮子（由 none-any 在类似 projectname-1.2.3-py2.py3-none-any.whl 的文件名中表示）。这与源代码分发没有太大区别，但最好同时上传两者。

Answer 3

您可以上传 whl 文件并使用以下命令进行安装