记录已安装项目#

此文档指定了记录有关已安装在环境中的 Python 项目 信息的通用格式。通用元数据格式允许工具查询、管理或卸载项目，无论其安装方式如何。

几乎所有信息都是可选的。这允许 Python 生态系统之外的工具（例如 Linux 软件包管理器）尽可能地与 Python 工具集成。例如，即使安装程序无法轻松地以特定于 Python 工具的格式提供已安装文件列表，它仍应记录已安装项目的名称和版本。

.dist-info 目录#

从发行版安装的每个项目都必须除了文件之外，还安装一个“.dist-info”目录，该目录位于可导入模块和软件包旁边（通常是 site-packages 目录）。

此目录的名称为 {name}-{version}.dist-info，其中 name 和 version 字段对应于 核心元数据规范。这两个字段都必须是规范化的（请参阅 名称规范规范 和 版本规范规范），并将破折号 (-) 字符替换为下划线 (_) 字符，因此 .dist-info 目录在其词干中始终只有一个破折号 (-) 字符，分隔 name 和 version 字段。

从历史上看，工具无法替换 name 字段中的点字符或规范大小写，或者无法在 version 字段中执行规范化。使用 .dist-info 目录的工具应该期望这些字段未规范化，并将它们视为等效于其规范化对应项。编写 .dist-info 目录的新工具必须使用上面描述的规则规范化 name 和 version 字段，并且鼓励现有工具开始规范化这些字段。

注意

.dist-info 目录的名称被格式化为明确地将发行版表示为文件系统路径。向用户显示发行版名称的工具应避免使用规范化名称，而应显示指定的名称（在解析为已安装软件包之前需要时），或读取核心元数据中的相应字段，因为那里列出的值未转义且准确地反映了发行版。库应为此类工具提供 API 以供使用，以便工具在显示发行版信息时可以访问未规范化的名称。

此 .dist-info 目录可能包含以下文件，具体说明如下

METADATA 文件是必需的。根据安装工具的判断，所有其他文件都可以省略。可能存在其他安装程序特定的文件。

注意

二进制发行版格式 规范描述了可能出现在 Wheel 的 .dist-info 目录中的其他文件。此类文件可以复制到已安装项目的 .dist-info 目录中。

此规范的先前版本还指定了 REQUESTED 文件。此文件现在被认为是特定于工具的扩展，但将来可能会再次标准化。有关其原始含义，请参阅 PEP 376。

METADATA 文件#

METADATA 文件包含 核心元数据规范 规范（版本 1.1 或更高版本）中所述的元数据。

METADATA 文件是必需的。如果无法创建它，或者如果缺少必需的核心元数据，则安装程序必须报告错误并无法安装项目。

RECORD 文件#

RECORD 文件保存已安装文件列表。它是一个 CSV 文件，每个已安装文件包含一条记录（行）。

CSV 方言必须可以使用 Python 的 csv 模块的默认 reader 读取

  • 字段分隔符：,（逗号），

  • 引用字符："（直引号），

  • 行终止符：\r\n 或 \n。

每条记录由三个元素组成：文件的路径、内容的哈希及其大小。

路径可以是绝对路径，也可以相对于包含 .dist-info 目录的目录（通常是 site-packages 目录）。在 Windows 中，目录可以用正斜杠或反斜杠（/ 或 \）分隔。

哈希要么是空字符串，要么是 hashlib.algorithms_guaranteed 中哈希算法的名称，后跟等号 = 和文件内容的摘要，使用 urlsafe-base64-nopad 编码（base64.urlsafe_b64encode(digest)，并删除尾随 =）。

大小要么是空字符串，要么是文件大小（以字节为单位），表示为 10 进制整数。

对于任何文件，哈希和大小字段都可以为空。通常，.pyc 文件和 RECORD 文件本身的条目具有空的哈希和大小。对于其他文件，不建议省略信息，因为它会阻止验证已安装项目的完整性。

如果 RECORD 文件存在，它必须列出项目的所有已安装文件，但 .pyc 文件除外，这些文件对应于 RECORD 中列出的 .py 文件，这些文件是可选的。值得注意的是，.dist-info 目录的内容（包括 RECORD 文件本身）必须列出。不应列出目录。

要完全卸载包，工具需要删除 RECORD 中列出的所有文件，所有 .pyc 文件（所有优化级别）对应于已删除的 .py 文件，以及卸载后清空的任何目录。

以下是可能的 RECORD 文件示例片段

/usr/bin/black,sha256=iFlOnL32lIa-RKk-MDihcbJ37wxmRbE4xk6eVYVTTeU,220
../../../bin/blackd,sha256=lCadt4mcU-B67O1gkQVh7-vsKgLpx6ny1le34Jz6UVo,221
__pycache__/black.cpython-38.pyc,,
__pycache__/blackd.cpython-38.pyc,,
black-19.10b0.dist-info/INSTALLER,sha256=zuuue4knoyJ-UwPPXg8fezS7VCrXJQrAP7zeNuwvFQg,4
black-19.10b0.dist-info/LICENSE,sha256=nAQo8MO0d5hQz1vZbhGqqK_HLUqG1KNiI9erouWNbgA,1080
black-19.10b0.dist-info/METADATA,sha256=UN40nGoVVTSpvLrTBwNsXgZdZIwoKFSrrDDHP6B7-A0,58841
black-19.10b0.dist-info/RECORD,,
black.py,sha256=45IF72OgNfF8WpeNHnxV2QGfbCLubV5Xjl55cI65kYs,140161
blackd.py,sha256=JCxaK4hLkMRwVfZMj8FRpRRYC0172-juKqbN22bISLE,6672
blib2to3/__init__.py,sha256=9_8wL9Scv8_Cs8HJyJHGvx1vwXErsuvlsAqNZLcJQR0,8
blib2to3/__pycache__/__init__.cpython-38.pyc,,
blib2to3/__pycache__/pygram.cpython-38.pyc,sha256=zpXgX4FHDuoeIQKO_v0sRsB-RzQFsuoKoBYvraAdoJw,1512
blib2to3/__pycache__/pytree.cpython-38.pyc,sha256=LYLplXtG578ZjaFeoVuoX8rmxHn-BMAamCOsJMU1b9I,24910
blib2to3/pygram.py,sha256=mXpQPqHcamFwch0RkyJsb92Wd0kUP3TW7d-u9dWhCGY,2085
blib2to3/pytree.py,sha256=RWj3IL4U-Ljhkn4laN0C3p7IRdfvT3aIRjTV-x9hK1c,28530

如果 RECORD 文件丢失，依赖于 .dist-info 的工具不得尝试卸载或升级包。（此限制不适用于依赖于其他信息源的工具，例如 Linux 发行版中的系统包管理器。）

注意

强烈建议已安装的包不要修改自身（例如，在 site-packages 中的其命名空间下存储缓存文件）。site-packages 中的更改应留给 pip 等专门的安装程序工具。如果仍然以这种方式修改包，则必须更新 RECORD，否则卸载包将使未列出的文件保留在原处（可能导致僵尸命名空间包）。

INSTALLER 文件#

如果存在，INSTALLER 是一个单行文本文件，用于命名用于安装项目的工具。如果可以从命令行执行安装程序，INSTALLER 应包含命令名称。否则，它应包含可打印的 ASCII 字符串。

该文件可以用零个或多个 ASCII 空白字符终止。

以下是两个可能的 INSTALLER 文件的示例

pip

MegaCorp Cloud Install-O-Matic

此值仅应用于信息目的。例如，如果要求工具卸载项目但未找到 RECORD 文件，则它可能会建议 INSTALLER 中命名的工具可能能够执行卸载。

entry_points.txt 文件#

安装程序可能会创建此文件，以指示包包含哪些组件，供其他代码（包括控制台脚本和安装程序已使其可执行的其他应用程序）发现和使用。

其详细规范位于 入口点规范。

direct_url.json 文件#

安装程序在从指定直接 URL 引用（包括 VCS URL）的要求中安装发行版时，必须创建此文件。

从其他类型的要求（即名称加版本说明符）安装发行版时，不得创建此文件。

其详细规范位于 记录已安装发行版的直接 URL 来源。

有意防止对已安装包进行更改#

在某些情况下（例如，除了 Python 生态系统依赖项之外，还需要管理外部依赖项时），将包安装到 Python 环境中的工具希望确保其他工具不会用于卸载或以其他方式修改已安装的包，因为这样做可能会导致与更广泛环境的兼容性问题。

为实现此目的，受影响的工具应采取以下步骤

  • 重命名或删除 RECORD 文件，以防止通过其他工具进行更改（例如，追加后缀以创建非标准的 RECORD.tool 文件，如果工具本身需要这些信息，或者如果通过其他方式跟踪和管理包内容，则完全省略该文件）

  • 编写 INSTALLER 文件，指明应使用哪个工具来管理包（这允许 RECORD 识别工具在被要求修改受影响的包时提供更好的错误通知）

Python 运行时提供程序还可以通过修改默认 Python 包安装方案，使用平台提供的包之外的位置（同时还确保这两个位置都出现在默认 Python 导入路径中），来防止意外修改平台提供的包。

在某些情况下，可能希望甚至通过 Python 特定工具阻止安装其他包。对于这些情况，请参阅 外部管理的环境

历史记录#

  • 2009 年 6 月：此规范的原始版本已通过 PEP 376 批准。当时，它被称为已安装 Python 发行版的数据库。

  • 2020 年 3 月：direct_url.json 文件的规范已通过 PEP 610 批准。它仅在此页面上提及；有关完整定义，请参阅 记录已安装发行版的直接 URL 来源。

  • 2020 年 9 月：通过 PEP 627 批准了各种修正案和澄清。