记录已安装发行版的直接 URL 来源

Recording the Direct URL Origin of installed distributions

本文档指定了一个位于已安装发行版的 *.dist-info 目录中的 direct_url.json 文件，用于记录发行版的直接 URL 来源。*.dist-info 目录的一般结构和使用方式在 记录已安装的项目 中描述。

This document specifies a direct_url.json file in the *.dist-info directory of an installed distribution, to record the Direct URL Origin of the distribution. The general structure and usage of *.dist-info directories is described in 记录已安装的项目.

规范

Specification

当从指定直接 URL 引用（包括 VCS URL）的要求安装发行版时，安装工具 必须 在 *.dist-info 目录中创建 direct_url.json 文件。

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

此 JSON 文件 必须 是一个 UTF-8 编码的、符合 RFC 8259 的序列化版本，表示 直接 URL 数据结构。

备注

当请求的 URL 使用 file:// 协议并指向一个恰好包含 VCS 检出内容的本地目录时，安装工具 不得 尝试推断任何 VCS 信息，因此 不得 在 direct_url.json 文件中输出任何与 VCS 相关的信息（如 vcs_info）。

备注

一般来说，安装工具应尽可能保留请求的 URL 中提供的信息，生成 direct_url.json 时。例如，环境变量中的用户名:密码应被保留，而 requested_revision 应尽可能忠实地反映请求 URL 中提供的修订版本。然而，这些信息应通过更精确的数据进行 补充，如 commit_id。

The direct_url.json file MUST be created in the *.dist-info directory 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).

This JSON file MUST be a UTF-8 encoded, RFC 8259 compliant, serialization of the 直接 URL 数据结构.

备注

When the requested URL has the file:// scheme and points to a local directory that happens to contain a VCS checkout, installers MUST NOT attempt to infer any VCS information and therefore MUST NOT output any VCS related information (such as vcs_info) in direct_url.json.

备注

As a general rule, installers should as much as possible preserve the information that was provided in the requested URL when generating direct_url.json. For example user:password environment variables should be preserved and requested_revision should reflect the revision that was provided in the requested URL as faithfully as possible. This information is however enriched with more precise data, such as commit_id.

示例 pip 命令及其对 direct_url.json 的影响

Example pip commands and their effect on direct_url.json

生成 direct_url.json 的命令：

  • pip install https://example.com/app-1.0.tgz

  • pip install https://example.com/app-1.0.whl

  • pip install "app @ git+https://example.com/repo/app.git#subdirectory=setup"

  • pip install ./app

  • pip install file:///home/user/app

  • pip install --editable "app @ git+https://example.com/repo/app.git#subdirectory=setup" （在这种情况下，url 将是 git 仓库克隆到的本地目录，dir_info 将包含 "editable": true，且不会设置 vcs_info）

  • pip install -e ./app

不生成 ``direct_url.json`` 的命令：

  • pip install app

  • pip install app --no-index --find-links https://example.com/

Commands that generate a direct_url.json:

  • pip install https://example.com/app-1.0.tgz

  • pip install https://example.com/app-1.0.whl

  • pip install "app @ git+https://example.com/repo/app.git#subdirectory=setup"

  • pip install ./app

  • pip install file:///home/user/app

  • pip install --editable "app @ git+https://example.com/repo/app.git#subdirectory=setup" (in which case, url will be the local directory where the git repository has been cloned to, and dir_info will be present with "editable": true and no vcs_info will be set)

  • pip install -e ./app

Commands that do not generate a direct_url.json

  • pip install app

  • pip install app --no-index --find-links https://example.com/

历史记录

History

  • 2020 年 3 月：该规范已通过 PEP 610 批准。

  • March 2020: This specification was approved through PEP 610.