安装 wheel ‘distribution-1.0-py32-none-any.whl’

Wheel 安装名义上包括两个阶段

• 解包。
  1. 解析 distribution-1.0.dist-info/WHEEL。
  2. 检查安装程序是否与 Wheel-Version 兼容。如果次要版本更高则警告，如果主要版本更高则中止。
  3. 如果 Root-Is-Purelib == 'true'，则将存档解包到 purelib (site-packages)。
  4. 否则将存档解包到 platlib (site-packages)。
• 传播。
  1. 解包的存档包括 distribution-1.0.dist-info/ 和（如果有数据）distribution-1.0.data/。
  2. 将 distribution-1.0.data/ 的每个子树移动到其目标路径。 distribution-1.0.data/ 的每个子目录都是目标目录字典的键，例如 distribution-1.0.data/(purelib|platlib|headers|scripts|data)。
  3. 更新以 #!python 开头的脚本以指向正确的解释器。（注意：Python 脚本通常由包元数据处理，而不按字面包含在 wheel 中。）
  4. 使用已安装的路径更新 distribution-1.0.dist.info/RECORD。
  5. 如果为空，则删除 distribution-1.0.data 目录。
  6. 将所有已安装的 .py 编译为 .pyc。（即使 RECORD 中未提及 .pyc，卸载程序也应该足够智能地删除 .pyc。）

实际上，安装程序通常会将文件直接从存档解压到其目标位置，而无需写入临时 distribution-1.0.data/ 目录。

文件格式

re.sub("[^\w\d.]+", "_", distribution, re.UNICODE)

distribution-1.0.dist-info/

distribution-1.0.data/

{
    'bindir': '$eprefix/bin',
    'sbindir': '$eprefix/sbin',
    'libexecdir': '$eprefix/libexec',
    'sysconfdir': '$prefix/etc',
    'sharedstatedir': '$prefix/com',
    'localstatedir': '$prefix/var',
    'libdir': '$eprefix/lib',
    'static_libdir': r'$prefix/lib',
    'includedir': '$prefix/include',
    'datarootdir': '$prefix/share',
    'datadir': '$datarootdir',
    'mandir': '$datarootdir/man',
    'infodir': '$datarootdir/info',
    'localedir': '$datarootdir/locale',
    'docdir': '$datarootdir/doc/$dist_name',
    'htmldir': '$docdir',
    'dvidir': '$docdir',
    'psdir': '$docdir',
    'pdfdir': '$docdir',
    'pkgdatadir': '$datadir/$dist_name'
}

Install-Paths-To: wheel/_paths.py
Install-Paths-To: wheel/_paths.json

data='../wheel-0.26.0.dev1.data/data'
headers='../wheel-0.26.0.dev1.data/headers'
platlib='../wheel-0.26.0.dev1.data/platlib'
purelib='../wheel-0.26.0.dev1.data/purelib'
scripts='../wheel-0.26.0.dev1.data/scripts'
# ...

{ "data": "../wheel-0.26.0.dev1.data/data", ... }

签名的 wheel 文件

Wheel 文件包含一个扩展的 RECORD，它支持数字签名。PEP 376 的 RECORD 经过修改，将安全哈希 digestname=urlsafe_b64encode_nopad(digest)（不带尾随 = 字符的 urlsafe base64 编码）作为第二列，而不是 md5sum。所有可能的条目都经过哈希处理，包括任何生成的文件（如 .pyc 文件），但不包括 RECORD，因为 RECORD 不能包含自身的哈希。例如

file.py,sha256=AVTFPZpEKzuHr7OvQZmhaU3LvwKz06AJw8mT\_pNh2yI,3144
distribution-1.0.dist-info/RECORD,,

签名文件 RECORD.jws 和 RECORD.p7s 在 RECORD 中根本没有提及，因为它们只能在 RECORD 生成之后添加。存档中的所有其他文件都必须在 RECORD 中有正确的哈希，否则安装将失败。

如果使用 JSON Web 签名，一个或多个 JSON Web 签名 JSON 序列化 (JWS-JS) 签名存储在 RECORD 旁边的文件 RECORD.jws 中。JWS 通过将 RECORD 的 SHA-256 哈希作为签名的 JSON 有效负载来签署 RECORD

{ "hash": "sha256=ADD-r2urObZHcxBW3Cr-vDCu5RJwT4CaRTHiFmbcIYY" }

（哈希值与 RECORD 中使用的格式相同。）

如果使用 RECORD.p7s，它必须包含 RECORD 的分离式 S/MIME 格式签名。

wheel 安装程序不需要理解数字签名，但必须根据提取的文件内容验证 RECORD 中的哈希。当安装程序对照 RECORD 检查文件哈希时，单独的签名检查器只需要确认 RECORD 与签名匹配即可。

参见

• RFC 7515
• https://datatracker.ietf.org/doc/html/draft-jones-jose-jws-json-serialization.html
• RFC 7517
• https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key.html

与 .egg 的比较

1. Wheel 是一种安装格式；egg 是可导入的。Wheel 存档不需要包含 .pyc，并且与特定 Python 版本或实现的相关性较小。Wheel 可以安装使用以前版本的 Python 构建的（纯 Python）包，因此您不必总是等待打包程序跟上。
2. Wheel 使用 .dist-info 目录；egg 使用 .egg-info。Wheel 与 Python 打包的新世界及其带来的新概念兼容。
3. Wheel 为当今多实现的世界提供了更丰富的文件命名约定。单个 wheel 存档可以指示其与多个 Python 语言版本和实现、ABI 和系统架构的兼容性。历史上，ABI 是 CPython 版本特有的，wheel 已为稳定的 ABI 做好准备。
4. Wheel 是无损的。第一个 wheel 实现 bdist_wheel 总是生成 egg-info，然后将其转换为 .whl。也可以转换现有的 egg 和 bdist_wininst 发行版。
5. Wheel 是有版本的。每个 wheel 文件都包含 wheel 规范的版本和打包它的实现。希望下一次迁移可以直接到 Wheel 2.0。
6. Wheel 是对另一个 Python 的引用。

Wheel 定义了一个 .data 目录。我应该把所有数据都放在那里吗？

此规范不就您应如何组织代码发表意见。.data 目录只是一个用于存放通常不安装在 site-packages 或 PYTHONPATH 中的任何文件的地方。换句话说，您可以继续使用 pkgutil.get_data(package, resource)，即使*那些*文件通常不会分发在 *wheel 的* .data 目录中。

为什么 wheel 包含附加签名？

附加签名比分离签名更方便，因为它们随存档一起传输。由于只对单个文件进行签名，因此可以重新压缩存档而不会使签名失效，或者可以在不下载整个存档的情况下验证单个文件。

为什么 wheel 允许 JWS 签名？

JWS 所属的 JOSE 规范旨在易于实现，这也是 wheel 的主要设计目标之一。JWS 产生了一个有用、简洁的纯 Python 实现。

为什么 wheel 也允许 S/MIME 签名？

S/MIME 签名允许需要或希望使用现有公钥基础设施与 wheel 配合使用的用户使用。

签名包只是安全包更新系统中的一个基本构建块。Wheel 只提供构建块。

“purelib” 和 “platlib” 有什么区别？

Wheel 保留了“purelib”与“platlib”的区别，这在某些平台上很重要。例如，Fedora 将纯 Python 包安装到“/usr/lib/pythonX.Y/site-packages”，将平台相关包安装到“/usr/lib64/pythonX.Y/site-packages”。

一个“Root-Is-Purelib: false”且所有文件都在 {name}-{version}.data/purelib 中的 wheel，等同于一个“Root-Is-Purelib: true”且这些文件在根目录中的 wheel，并且在“purelib”和“platlib”类别中都包含文件是合法的。

实际上，一个 wheel 应该只有一个“purelib”或“platlib”，这取决于它是否是纯 Python，并且这些文件应该在根目录下，并为“Root-is-purelib”设置适当的值。

是否可以直接从 wheel 文件导入 Python 代码？

技术上，由于支持通过简单提取进行安装并使用与 zipimport 兼容的存档格式，一部分 wheel 文件*确实*支持直接放置在 sys.path 上。然而，虽然这种行为是格式设计的自然结果，但通常不鼓励实际依赖它。

首先，wheel *主要*设计为一种分发格式，因此跳过安装步骤也意味着故意避免依赖假定完全安装的功能（例如，能够使用 pip 和 virtualenv 等标准工具来捕获和管理依赖项，以便进行审计和安全更新，或通过在适当位置发布头文件来与 C 扩展的标准构建机制完全集成）。

其次，虽然有些 Python 软件支持直接从 zip 存档运行，但代码通常仍假设已完全安装。当尝试从 zip 存档运行软件而打破这种假设时，故障通常可能晦涩难懂且难以诊断（尤其是在第三方库中发生时）。造成此问题的两个最常见原因是从 zip 存档导入 C 扩展*不*受 CPython 支持（因为任何平台上的动态加载机制都不直接支持这样做），以及从 zip 存档运行时 __file__ 属性不再引用普通的filesystem 路径，而是引用包含 zip 存档在文件系统上的位置和存档内部模块的相对路径的组合路径。即使软件在内部正确使用抽象资源 API，与外部组件交互仍可能需要实际的磁盘文件。

就像元类、猴子补丁和元路径导入器一样，如果您不确定是否需要利用此功能，那么您几乎肯定不需要它。如果您*确实*决定无论如何都要使用它，请注意，许多项目会要求在将其接受为真正错误之前，必须使用完全安装的包重现故障。