摘要

本文件描述了對建構後端與前端通訊的擴充（由 PEP 517 引入），以透過引入虛擬輪的方式，允許專案以可編輯模式安裝。

動機

在開發期間，許多 Python 使用者偏好安裝他們的函式庫，以便對底層原始碼和資源的變更，能夠在後續的直譯器呼叫中自動反映，而無需額外的安裝步驟。此模式通常稱為「開發模式」或「可編輯安裝」。目前，沒有標準化的方法可以實現這一點，因為 PEP 517 由於實際觀察行為的複雜性而明確將其排除在外。

目前，使用者若要獲得此行為，會執行以下其中一種方式：

• 僅針對 Python 程式碼，透過將相關原始碼目錄加入 sys.path（可透過命令列介面，經由 PYTHONPATH 環境變數配置）。請注意在此情況下，使用者必須自行安裝專案依賴項，並且不會產生進入點或專案中繼資料。
• setuptools 提供了 setup.py develop 機制：它會安裝一個 pth 檔案，該檔案會在直譯器啟動時將專案根目錄注入 sys.path，產生專案中繼資料，並也安裝專案依賴項。pip 透過 pip install -e 命令列介面公開呼叫此機制。
• flit 提供了 flit install –symlink 命令，它會將專案檔案符號連結到直譯器的 purelib 資料夾中，產生專案中繼資料，並也安裝依賴項。請注意，這也支援資源檔案。

這些範例顯示，可編輯安裝可以透過多種方式實現，目前並沒有標準方法。此外，目前尚不清楚實現和定義何謂可編輯安裝是誰的責任：

1. 允許建構後端定義並具現化它，
2. 允許建構前端定義並具現化它，
3. 從所有可能選項中明確定義並標準化一種方法。

本 PEP 的作者認為在此沒有一體適用的解決方案，每種實現可編輯效果的方法都有其優點和缺點。因此，本 PEP 拒絕選項三，因為社群不太可能同意單一解決方案。此外，前端或建構後端應該擁有此責任的問題仍然存在。PEP 660 建議由建構後端來負責，而目前的 PEP 主要建議由前端負責，但如果後端希望如此，仍然允許其掌握控制權。

原理

PEP 517 推遲了「可編輯安裝」，因為這會進一步延遲其採用，並且對於如何實現可編輯安裝沒有達成共識。由於 setuptools 和 pip 專案的普及，現狀得以維持，後端可以透過提供一個 setup.py develop 實作來實現可編輯模式，使用者可以透過 pip install -e 觸發該實作。透過在建構後端和前端之間定義一個可編輯介面，我們可以消除 setup.py 檔案及其目前的通訊方法。

術語與目標

本 PEP 旨在明確劃分前端和後端的角色，並賦予每個開發者最大的能力，為其使用者提供有價值的特性。在此提案中，後端的角色是為可編輯安裝準備專案，然後向前端提供足夠的資訊，以便前端可以具現化並實施可編輯安裝。

後端提供給前端的資訊是一個遵循 PEP 427 中現有規範的 wheel。關於壓縮檔本身的 wheel 中繼資料（{distribution}-{version}.dist-info/WHEEL）也必須包含鍵 Editable，其值為 true。

然而，它必須提供一個 editable.json 檔案（在 wheel 的根目錄中），而不是在 wheel 內提供專案檔案，該檔案定義了要由前端公開的檔案。此檔案的內容被定義為一個映射，將絕對原始碼樹路徑映射到方案映射中相對目標直譯器目標路徑。

滿足前兩段說明的 wheel 是一個虛擬輪。前端的角色是接收虛擬輪並以可編輯模式安裝專案。它實現此目的的方式完全取決於前端，並被視為實作細節。

可編輯安裝模式表示正在安裝的專案原始碼在本地目錄中可用。一旦專案以可編輯模式安裝，對本地原始碼樹中專案程式碼的某些變更將會生效，而無需新的安裝步驟。至少，對安裝時存在的非產生檔案文本的變更，應在後續匯入套件時反映出來。

某些類型的變更，例如新增或修改進入點或新的依賴項，需要新的安裝步驟才能生效。這些變更通常在建構後端配置檔案中進行（例如 pyproject.toml）。此要求與一般使用者預期一致，即此類修改僅在重新安裝後才會生效。

儘管使用者預期可編輯安裝與標準安裝的行為相同，這可能並非總是可行，並可能與其他使用者預期相衝突。取決於前端如何實作可編輯模式，可能會出現一些差異，例如額外檔案的存在（與典型安裝相比），無論是在原始碼樹中還是直譯器的安裝路徑中。

前端應努力將可編輯安裝與標準安裝之間的行為差異降至最低，並記錄已知的差異。

供參考，非可編輯安裝的運作方式如下：

1. 開發者正在使用一個工具（我們在此稱之為前端，例如 pip）來驅動專案開發。當使用者想要觸發專案的套件建構和安裝時，他們將與前端通訊。
2. 前端使用一個建構前端（例如 build）來觸發 wheel 的建構。建構前端使用 PEP 517 與建構後端（例如 setuptools）通訊 — 其中建構後端安裝在一個 PEP 518 環境中。一旦呼叫，後端會返回一個 wheel。
3. 前端接收 wheel 並將其提供給一個安裝器（例如 installer），將 wheel 安裝到目標 Python 直譯器中。

機制

本 PEP 增加了兩個可選的掛鉤到 PEP 517 後端介面。其中一個掛鉤用於指定可編輯安裝的建構依賴項。另一個掛鉤則透過建構前端返回前端創建可編輯安裝所需的必要資訊。

def get_requires_for_build_editable(config_settings=None):
    ...

def prepare_metadata_for_build_editable(metadata_directory, config_settings=None):
    ...

def build_editable(self, wheel_directory, config_settings=None,
                    metadata_directory=None):
    ...

{
  "$schema": "http://json-schema.org/draft-07/schema",
  "$id": "http://pypa.io/editables.json",
  "type": "object",
  "title": "Virtual wheel editable schema.",
  "required": ["version", "scheme"],
  "properties": {
    "version": {
      "$id": "#/properties/version",
      "type": "integer",
      "minimum": 1,
      "maximum": 1,
      "title": "The version of the schema."
    },
    "scheme": {
      "$id": "#/properties/scheme",
      "type": "object",
      "title": "Files to expose.",
      "required": ["purelib", "platlib", "data", "headers", "scripts"],
      "properties": {
        "purelib": { "$ref": "#/$defs/mapping" },
        "platlib": { "$ref": "#/$defs/mapping" },
        "data": { "$ref": "#/$defs/mapping" },
        "headers": { "$ref": "#/$defs/mapping" },
        "scripts": { "$ref": "#/$defs/mapping" }
      },
      "additionalProperties": true
    }
  },
  "additionalProperties": true,
  "$defs": {
    "mapping": {
      "type": "object",
      "description": "A mapping of source to target paths. The source is absolute path, the destination is relative path.",
      "additionalProperties": true
    }
  }
}

{
   "version": 1,
   "scheme": {
      "purelib": {"/src/tree/a.py": "tree/a.py"},
      "platlib": {},
      "data": {"/src/tree/py.typed": "tree/py.typed"},
      "headers": {},
      "scripts": {}
   }
}

{
  {"version": 1, "scheme": {"purelib": {"<project dir>": "<project dir>"}}}
}

{
   "version": 1,
   "scheme": {
      "purelib": {
        "<project dir>/.editable/_register_importer.pth": "<project dir>/_register_importer.pth".
        "<project dir>/.editable/_editable_importer.py": "<project dir>/_editable_importer.py"
      }
    }
  }
}

遭否決的想法

本 PEP 與 PEP 660 競爭並拒絕了該提案，因為我們認為實現可編輯安裝的機制應該在前​​端而不是建構後端。此外，這種方法允許生態系統使用替代方法來實現可編輯安裝效果（例如，在 sys.path 上插入路徑或符號連結，而不是僅僅暗示該 PEP 描述的後端鬆散 wheel 模式）。

值得注意的是，PEP 660 不允許使用符號連結來公開程式碼和資料檔案，除非同時擴充 wheel 檔案標準以支援符號連結。目前尚不清楚如何擴充 wheel 格式以支援不指向 wheel 本身內部檔案，而是僅指向本地磁碟上可用檔案的符號連結。值得注意的是，後端本身（或後端生成的程式碼）不得生成這些符號連結（例如，在直譯器啟動時），因為這會與前端記錄需要解除安裝哪些檔案的方式衝突。

最後，PEP 660 僅支援 purelib 和 platlib 檔案。它特意避免支援 wheel 格式支援的其他類型資訊：include、data 和 scripts。透過這種方式，前端可以透過符號連結機制盡力支援這些（儘管此功能並非普遍可用 — 在 Windows 上需要啟用）。我們認為為這些檔案類型添加盡力支援是有益的，而不是完全排除支援它們的可能性。

版權

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