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

本文档指定在已安装分发版的 *.dist-info 目录中创建一个 direct_url.json 文件，以记录该分发版的直接 URL 来源。*.dist-info 目录的通用结构和用法在记录已安装项目中描述。

规范

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

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

此 JSON 文件必须是 UTF-8 编码、RFC 8259 兼容的直接 URL 数据结构的序列化。

注意

当请求的 URL 具有 file:// 方案并指向一个恰好包含 VCS 检出的本地目录时，安装程序不得尝试推断任何 VCS 信息，因此不得在 direct_url.json 中输出任何与 VCS 相关的信息（例如 vcs_info）。

注意

作为一般规则，安装程序在生成 direct_url.json 时应尽可能保留请求 URL 中提供的信息。例如，应保留 user:password 环境变量，并且 requested_revision 应尽可能真实地反映请求 URL 中提供的修订。但是，此信息会通过更精确的数据（例如 commit_id）进行丰富。

pip 命令示例及其对 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/

历史

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