摘要

根據 PEP 440，一個套件可以透過名稱與版本，或是直接 URL 參考（參見 PEP 440 直接參考）來識別。安裝後，名稱與版本會被記錄在專案元資料中，但目前沒有方法可以取得該套件最初以直接 URL 參考進行識別時的 URL 詳細資訊。

本提案定義了額外的元資料，由安裝前端（installation front end）新增至已安裝的套件中，記錄其「直接 URL 原始來源」，供檢視已安裝套件資料庫的消費者使用（參見 PEP 376）。

動機

本 PEP 最初的動機是為了讓具備「凍結（freeze）」功能的工具，能夠在更廣泛的情況下重新建立 Python 環境。

具體而言，本 PEP 源於解決 pip issue #609 的需求：即改進 pip freeze 在處理從直接 URL 參考安裝的套件時的行為。本提案遵循了 discuss.python.org 上的討論串，探討實作此功能的最佳途徑。

原理

本 PEP 指定在已安裝套件的 .dist-info 目錄中建立一個新的 direct_url.json 元資料檔案。

所指定的欄位足以重現原始碼壓縮檔及 pip 支援的 VCS URL。這些欄位也足以重現 PEP 440 直接參考，以及 Pipfile 與 Pipfile.lock 條目。最後，它們足以記錄已安裝版本的原始分支、標籤及/或 Git ref，這些資訊對於可編輯安裝而言，由於 VCS 檢出目錄的存在，原本就已經可以取得。

由於目前已存在至少三種編碼此類資訊的方式，本 PEP 使用字典格式，以免對直接 URL 參考最終如何在需求或鎖定檔（lockfile）中編碼做出任何假設。關於此選擇的進一步討論，請參見下方的「替代方案（Alternatives）」章節。

參考 Ruby 的 bundler 手冊以確認其具備類似能力，並據此資訊選定並命名本規範中的欄位。

JSON 格式允許在未來新增額外的欄位。

規範

本 PEP 指定在已安裝套件的 .dist-info 目錄中建立一個 direct_url.json 檔案，以記錄該套件的直接 URL 原始來源。

關於此元資料檔案名稱與語意的官方來源，請參見 記錄已安裝套件的原始直接 URL 文件。

當安裝程式從指定直接 URL 參考（包含 VCS URL）的需求安裝套件時，必須建立此檔案。

當從其他類型的需求（即名稱加版本說明符）安裝套件時，不得建立此檔案。

此 JSON 檔案必須為字典格式，符合 RFC 8259 標準並以 UTF-8 編碼。

若存在此檔案，它必須包含至少兩個欄位。第一個是 url，型態為 string。根據 url 指向的內容，第二個欄位必須是 vcs_info（若 url 為 VCS 參考）、archive_info（若 url 為原始碼壓縮檔或 wheel）或 dir_info（若 url 為本地目錄）其中之一。這些資訊欄位的值為一個（可能為空的）子字典，包含下文定義的可能鍵值。

基於安全考量，url 必須移除任何敏感的驗證資訊。

URL 中的 user:password 部分可以由環境變數組成，需符合以下正規表示式：

\$\{[A-Za-z0-9-_]+\}(:\$\{[A-Za-z0-9-_]+\})?

此外，URL 中的 user:password 部分也可以是眾所皆知、非安全敏感的字串。一個典型的例子是像 ssh://git@gitlab.com 這樣的 URL 中的 git。

當 url 指向 VCS 儲存庫時，必須包含 vcs_info 鍵，並作為包含下列鍵的字典：

• 必須包含一個 vcs 鍵（型態為 string），包含 VCS 的名稱（例如 git, hg, bzr, svn 之一）。其他 VCS 應透過撰寫 PEP 來修正本規範以進行註冊。url 的值必須與對應的 VCS 相容，以便安裝程式可以直接將其傳遞給 VCS 的檢出/下載指令，無需進行轉換。
• 可以包含一個 requested_revision 鍵（型態為 string），標註要安裝的分支/標籤/ref/提交雜湊碼/修訂版本等（格式需與該 VCS 相容）。
• 必須包含一個 commit_id 鍵（型態為 string），包含已安裝的確切提交/修訂版本編號。若該 VCS 支援基於提交雜湊碼的修訂版本識別符，則必須使用該雜湊碼作為 commit_id，以引用已安裝原始碼的不可變版本。
• 若安裝程式能發現關於所請求修訂版本的額外資訊，則可以新增 resolved_revision 及/或 resolved_revision_type 欄位。若所請求的 URL 中未提供修訂版本，resolved_revision 可包含已安裝的預設分支，而 resolved_revision_type 將為 branch。若安裝程式判定 requested_revision 為標籤，則可新增值為 tag 的 resolved_revision_type。

當 url 指向原始碼壓縮檔或 wheel 時，必須包含 archive_info 鍵，作為包含下列鍵的字典：

• 應包含一個 hash 鍵（型態為 string），值為 <雜湊演算法>=<預期雜湊值>。建議僅使用標準函式庫 hashlib 模組最新版本中所無條件提供的雜湊演算法作為原始碼壓縮檔的雜湊值。撰寫本文時，此清單包含 'md5'、'sha1'、'sha224'、'sha256'、'sha384' 及 'sha512'。

當 url 指向本地目錄時，必須包含 dir_info 鍵，作為包含下列鍵的字典：

• editable（型態為 boolean）：若套件以可編輯模式安裝則為 true，否則為 false。若不存在，預設為 false。

當 url 指向本地目錄時，必須使用 file 協定並符合 RFC 8089。特別是，路徑部分必須是絕對路徑。將相對路徑轉為絕對路徑時，應保留符號連結（symbolic links）。

可以存在頂層的 subdirectory 欄位，包含相對於 VCS 儲存庫、原始碼壓縮檔或本地目錄根目錄的路徑，以指定 pyproject.toml 或 setup.py 的位置。

範例

{
    "url": "https://github.com/pypa/pip/archive/1.3.1.zip",
    "archive_info": {
        "hash": "sha256=2dc6b5a470a1bde68946f263f1af1515a2574a150a30d6ce02c6ff742fcc0db8"
    }
}

{
    "url": "https://github.com/pypa/pip.git",
    "vcs_info": {
        "vcs": "git",
        "requested_revision": "1.3.1",
        "resolved_revision_type": "tag",
        "commit_id": "7921be1537eac1e97bc40179a57f0349c2aee67d"
    }
}

{
    "url": "file:///home/user/project",
    "dir_info": {}
}

{
    "url": "file:///home/user/project",
    "dir_info": {
        "editable": true
    }
}

使用案例

「凍結」環境

如 pip freeze 等從已安裝 Python 套件資料庫產生需求的工具，若 direct_url.json 存在，則應利用該檔案，並賦予其高於版本元資料的優先權，以產生更高保真度的輸出。在存在 vcs 直接 URL 參考的情況下，應優先使用 commit_id 欄位，以對最初安裝的版本提供最高可能的保真度。若需求格式支援，也鼓勵工具輸出 tag 值（若存在），因其具有不可變的語意。工具可根據使用者的需求選擇其他方法。

請注意，本 PEP 的初始版本並未試圖讓包含可編輯安裝或從本地目錄安裝的環境變得可重現，但確實試圖讓它們變得容易識別。透過此規範的 url 和 dir_info 欄位定位本地專案目錄，工具可以實作任何符合其使用場景的策略。

回溯相容性

由於本 PEP 在 .dist-info 目錄中指定了一個新檔案，因此不會對向後相容性產生影響。

替代方案

致謝

許多人協助讓本 PEP 成為現實。Paul F. Moore 提供了摘要的精髓。Alyssa Coghlan 建議了 direct_url 這個名稱。

版權

本文件已進入公有領域或遵循 CC0-1.0-Universal 授權，以較寬鬆者為準。