记录已安装的项目¶

Recording installed projects

中文

本文档指定了记录 Python 项目在环境中安装信息的通用格式。一种通用的元数据格式允许工具查询、管理或卸载项目，无论它们是如何安装的。

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

英文

This document specifies a common format of recording information about Python projects installed in an environment. A common metadata format allows tools to query, manage or uninstall projects, regardless of how they were installed.

Almost all information is optional. This allows tools outside the Python ecosystem, such as Linux package managers, to integrate with Python tooling as much as possible. For example, even if an installer cannot easily provide a list of installed files in a format specific to Python tooling, it should still record the name and version of the installed project.

.dist-info 目录¶

The .dist-info directory

中文

从分发中安装的每个项目必须除了文件外，还安装一个名为 ".dist-info" 的目录，该目录位于可导入的模块和包旁边（通常是 site-packages 目录）。

该目录命名为 {name}-{version}.dist-info，其中 name 和 version 字段对应于核心元数据规范。这两个字段必须标准化（请参见 name normalization specification 和 version normalization specification），并将破折号（-）字符替换为下划线（_）字符，因此 .dist-info 目录的名称总是包含且仅包含一个破折号（-），用于分隔 name 和 version 字段。

历史上，工具未能替换点字符或标准化 name 字段中的大小写，或者未对 version 字段进行标准化。消费 .dist-info 目录的工具应预期这些字段未标准化，并将它们视为与其标准化形式等效。新的工具在写入 .dist-info 目录时，必须使用上述规则标准化 name 和 version 字段，并鼓励现有工具开始标准化这些字段。

备注

.dist-info 目录的名称格式旨在明确表示一个分发作为文件系统路径。向用户展示分发名称的工具应避免使用标准化后的名称，而应呈现指定的名称（在解析到已安装包之前需要时），或者读取核心元数据中的相关字段，因为那里列出的值是未转义的，准确反映了该分发。库应为这些工具提供 API，以便工具在显示分发信息时能够访问未标准化的名称。

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

METADATA: 包含项目元数据
RECORD: 记录已安装文件的列表。
INSTALLER: 记录用于安装项目的工具的名称。
entry_points.txt: 详见入口点规范
direct_url.json: 详见记录已安装发行版的直接 URL 来源

METADATA 文件是强制性的。其他所有文件可以根据安装工具的判断决定是否省略。可能会有其他特定于安装工具的文件。

备注

二进制分发格式规范描述了可能出现在 Wheel 的 .dist-info 目录中的附加文件。这些文件可以被复制到已安装项目的 .dist-info 目录中。

该规范的早期版本还指定了一个 REQUESTED 文件。这个文件现在被视为工具特定的扩展，但未来可能会重新标准化。有关其原始含义，请参见 PEP 376。

英文

Each project installed from a distribution must, in addition to files, install a ".dist-info" directory located alongside importable modules and packages (commonly, the site-packages directory).

This directory is named as {name}-{version}.dist-info, with name and version fields corresponding to 核心元数据规范. Both fields must be normalized (see the name normalization specification and the version normalization specification), and replace dash (-) characters with underscore (_) characters, so the .dist-info directory always has exactly one dash (-) character in its stem, separating the name and version fields.

Historically, tools have failed to replace dot characters or normalize case in the name field, or not perform normalization in the version field. Tools consuming .dist-info directories should expect those fields to be unnormalized, and treat them as equivalent to their normalized counterparts. New tools that write .dist-info directories MUST normalize both name and version fields using the rules described above, and existing tools are encouraged to start normalizing those fields.

备注

The .dist-info directory's name is formatted to unambiguously represent a distribution as a filesystem path. Tools presenting a distribution name to a user should avoid using the normalized name, and instead present the specified name (when needed prior to resolution to an installed package), or read the respective fields in Core Metadata, since values listed there are unescaped and accurately reflect the distribution. Libraries should provide API for such tools to consume, so tools can have access to the unnormalized name when displaying distribution information.

This .dist-info directory may contain the following files, described in detail below:

METADATA: contains project metadata
RECORD: records the list of installed files.
INSTALLER: records the name of the tool used to install the project.
entry_points.txt: see 入口点规范 for details
direct_url.json: see 记录已安装发行版的直接 URL 来源 for details

The METADATA file is mandatory. All other files may be omitted at the installing tool's discretion. Additional installer-specific files may be present.

备注

The 二进制分发格式 specification describes additional files that may appear in the .dist-info directory of a Wheel. Such files may be copied to the .dist-info directory of an installed project.

The previous versions of this specification also specified a REQUESTED file. This file is now considered a tool-specific extension, but may be standardized again in the future. See PEP 376 for its original meaning.

METADATA 文件¶

The METADATA file

中文

METADATA 文件包含如核心元数据规范规范中所描述的元数据，版本为 1.1 或更高版本。

METADATA 文件是强制性的。如果无法创建该文件，或者所需的核心元数据不可用，安装程序必须报告错误并停止安装项目。

英文

The METADATA file contains metadata as described in the 核心元数据规范 specification, version 1.1 or greater.

The METADATA file is mandatory. If it cannot be created, or if required core metadata is not available, installers must report an error and fail to install the project.

RECORD 文件¶

The RECORD file

中文

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

CSV 方言必须可以通过 Python 的 csv 模块的默认 reader 读取：

字段分隔符：, （逗号），
引号字符：" （直引号），
行终止符：\r\n 或 \n。

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

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

哈希值 要么是空字符串，要么是来自 hashlib.algorithms_guaranteed 的哈希算法名称，后跟等号字符 = 和文件内容的摘要，摘要使用 urlsafe-base64-nopad 编码（即使用 base64.urlsafe_b64encode(digest)，去掉尾部的 =）。

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

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

如果 RECORD 文件存在，它必须列出项目的所有已安装文件，但不包括与 .py 文件对应的 .pyc 文件，这些文件是可选的。特别地，.dist-info 目录的内容（包括 RECORD 文件本身）必须列出。目录不应列出。

为了完全卸载一个包，工具需要删除 RECORD 中列出的所有文件，删除与已移除的 .py 文件对应的所有 .pyc 文件（包括所有优化级别），以及卸载过程中被清空的任何目录。

以下是一个可能的 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，否则卸载包时将留下未列出的文件（可能导致僵尸命名空间包）。

英文

The RECORD file holds the list of installed files. It is a CSV file containing one record (line) per installed file.

The CSV dialect must be readable with the default reader of Python's csv module:

field delimiter: , (comma),
quoting char: " (straight double quote),
line terminator: either \r\n or \n.

Each record is composed of three elements: the file's path, the hash of the contents, and its size.

The path may be either absolute, or relative to the directory containing the .dist-info directory (commonly, the site-packages directory). On Windows, directories may be separated either by forward- or backslashes (/ or \).

The hash is either an empty string or the name of a hash algorithm from hashlib.algorithms_guaranteed, followed by the equals character = and the digest of the file's contents, encoded with the urlsafe-base64-nopad encoding (base64.urlsafe_b64encode(digest) with trailing = removed).

The size is either the empty string, or file's size in bytes, as a base 10 integer.

For any file, either or both of the hash and size fields may be left empty. Commonly, entries for .pyc files and the RECORD file itself have empty hash and size. For other files, leaving the information out is discouraged, as it prevents verifying the integrity of the installed project.

If the RECORD file is present, it must list all installed files of the project, except .pyc files corresponding to .py files listed in RECORD, which are optional. Notably, the contents of the .dist-info directory (including the RECORD file itself) must be listed. Directories should not be listed.

To completely uninstall a package, a tool needs to remove all files listed in RECORD, all .pyc files (of all optimization levels) corresponding to removed .py files, and any directories emptied by the uninstallation.

Here is an example snippet of a possible RECORD file:

/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

If the RECORD file is missing, tools that rely on .dist-info must not attempt to uninstall or upgrade the package. (This restriction does not apply to tools that rely on other sources of information, such as system package managers in Linux distros.)

备注

It is strongly discouraged for an installed package to modify itself (e.g., store cache files under its namespace in site-packages). Changes inside site-packages should be left to specialized installer tools such as pip. If a package is nevertheless modified in this way, then the RECORD must be updated, otherwise uninstalling the package will leave unlisted files in place (possibly resulting in a zombie namespace package).

INSTALLER 文件¶

The INSTALLER file

中文

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

该文件可以以零个或多个 ASCII 空白字符结尾。

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

pip

MegaCorp Cloud Install-O-Matic

此值仅应用于参考目的。例如，如果一个工具被要求卸载一个项目，但找不到 RECORD 文件，它可以提示 INSTALLER 中列出的工具可能能够进行卸载。

英文

If present, INSTALLER is a single-line text file naming the tool used to install the project. If the installer is executable from the command line, INSTALLER should contain the command name. Otherwise, it should contain a printable ASCII string.

The file can be terminated by zero or more ASCII whitespace characters.

Here are examples of two possible INSTALLER files:

pip

MegaCorp Cloud Install-O-Matic

This value should be used for informational purposes only. For example, if a tool is asked to uninstall a project but finds no RECORD file, it may suggest that the tool named in INSTALLER may be able to do the uninstallation.

entry_points.txt 文件¶

The entry_points.txt file

中文

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

其详细规范请参见入口点规范。

英文

This file MAY be created by installers to indicate when packages contain components intended for discovery and use by other code, including console scripts and other applications that the installer has made available for execution.

Its detailed specification is at 入口点规范.

direct_url.json 文件¶

The direct_url.json file

中文

当从指定直接 URL 引用（包括 VCS URL）的需求安装分发包时，安装程序必须创建此文件。

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

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

英文

This file MUST be created by installers when installing a distribution from a requirement specifying a direct URL reference (including a VCS URL).

This file MUST NOT be created when installing a distribution from an other type of requirement (i.e. name plus version specifier).

Its detailed specification is at 记录已安装发行版的直接 URL 来源.

有意阻止对已安装软件包的更改¶

Intentionally preventing changes to installed packages

中文

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

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

重命名或删除 RECORD 文件，以防止通过其他工具进行更改（例如，如果工具本身需要这些信息，可以通过附加后缀创建一个非标准的 RECORD.tool 文件，或者如果包内容通过其他方式进行跟踪和管理，则完全省略此文件）
写入 INSTALLER 文件，指明应该用于管理包的工具名称（这允许 RECORD 相关工具在要求修改受影响的包时提供更好的错误提示）

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

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

英文

In some cases (such as when needing to manage external dependencies in addition to Python ecosystem dependencies), it is desirable for a tool that installs packages into a Python environment to ensure that other tools are not used to uninstall or otherwise modify that installed package, as doing so may cause compatibility problems with the wider environment.

To achieve this, affected tools should take the following steps:

Rename or remove the RECORD file to prevent changes via other tools (e.g. appending a suffix to create a non-standard RECORD.tool file if the tool itself needs the information, or omitting the file entirely if the package contents are tracked and managed via other means)
Write an INSTALLER file indicating the name of the tool that should be used to manage the package (this allows RECORD-aware tools to provide better error notices when asked to modify affected packages)

Python runtime providers may also prevent inadvertent modification of platform provided packages by modifying the default Python package installation scheme to use a location other than that used by platform provided packages (while also ensuring both locations appear on the default Python import path).

In some circumstances, it may be desirable to block even installation of additional packages via Python-specific tools. For these cases refer to 外部管理环境

历史记录¶

History

中文

2009年6月：该规范的原始版本通过 PEP 376 获得批准。当时，它被称为 已安装 Python 分发包数据库。
2020年3月：direct_url.json 文件的规范通过 PEP 610 获得批准。它仅在此页面中提及；请参见记录已安装发行版的直接 URL 来源获取完整定义。
2020年9月：通过 PEP 627 批准了各种修订和澄清。

英文

June 2009: The original version of this specification was approved through PEP 376. At the time, it was known as the Database of Installed Python Distributions.
March 2020: The specification of the direct_url.json file was approved through PEP 610. It is only mentioned on this page; see 记录已安装发行版的直接 URL 来源 for the full definition.
September 2020: Various amendments and clarifications were approved through PEP 627.