摘要

儘管 distutils / setuptools 陪伴我們走過了很長一段路，但它們存在三個嚴重的問題：(a) 它們缺少重要的功能，如可用的建置期依賴宣告、自動配置，甚至連基礎的工程學需求（如符合 DRY 原則的版本號管理）都缺乏；(b) 擴充它們非常困難，因此雖然針對上述問題存在各種解決方案，但它們往往古怪、脆弱且維護成本高昂；(c) 由於 distutils/setuptools 為使用者和如 pip 這類安裝工具提供了標準的套件安裝介面，因此很難使用其他方案來取代它們。

先前的努力（例如 distutils2 或 setuptools 本身）曾試圖解決 (a) 和/或 (b) 問題。本提案旨在解決 (c) 問題。

本 PEP 的目標是讓 distutils-sig 不再擔任 Python 建置系統的守門人。如果您想使用 distutils，很好；如果您想使用其他工具，那麼透過標準化方法應該要能輕鬆達成。目前與 distutils 對接的難度意味著市面上並沒有太多這類系統，但若想了解我們的想法，請參考 flit 或 bento。幸運的是，Wheel 格式目前已解決了許多棘手問題（例如，建置系統不再需要了解所有可能的安裝配置），因此我們實際上只需要建置系統提供一種輸出符合標準的 Wheel 和 sdist 的方式即可。

因此，我們為如 pip 這類的安裝工具提出了一種新的、相對精簡的介面，用於與套件原始碼樹及原始碼發布包互動。

術語與目標

原始碼樹 (source tree) 指的是像 VCS 的 checkout 副本之類的東西。我們需要一個標準介面來從此格式進行安裝，以支援如 pip install some-directory/ 這類用法。

原始碼發布包 (source distribution) 是代表特定版本原始碼的靜態快照，例如 lxml-3.4.4.tar.gz。原始碼發布包有多種用途：它們構成了發布版本的存檔紀錄、為希望讀取和處理大型程式碼庫（可能由多種語言編寫，如程式碼搜尋）的工具提供了簡單明瞭的事實標準，並作為 Debian/Fedora/Conda/... 等下游封裝系統的輸入等等。在 Python 生態系統中，它們還有一個特別重要的角色，因為像 pip 這類的封裝工具能夠使用原始碼發布包來滿足二進位依賴關係。例如，若有一個發布包 foo.whl 宣告了對 bar 的依賴，那麼我們就需要支援當執行 pip install bar 或 pip install foo 時，自動定位 bar 的 sdist、下載、建置並安裝產生的套件。

原始碼發布包簡稱為 sdists。

建置前端 (build frontend) 是一種使用者可能會執行的工具，它接收任意原始碼樹或原始碼發布包並從中建置 Wheel。實際的建置工作由每個原始碼樹的 建置後端 (build backend) 完成。在 pip wheel some-directory/ 這樣的指令中，pip 扮演的就是建置前端的角色。

整合前端 (integration frontend) 是一種使用者可能會執行的工具，它接收一套套件需求（例如 requirements.txt 檔案）並試圖更新工作環境以滿足這些需求。這可能需要定位、建置並安裝 Wheel 和 sdist 的組合。在 pip install lxml==2.4.0 這樣的指令中，pip 扮演的就是整合前端的角色。

原始碼樹

目前存在一種包含 setup.py 的遺留原始碼樹格式。我們不嘗試對其進行進一步規範；其事實上的規範已編碼在 distutils、setuptools、pip 及其他工具的原始碼和文件中。我們將其稱為 setup.py 風格。

在此，我們定義了一種新的原始碼樹風格，基於 PEP 518 中定義的 pyproject.toml 檔案，並在該檔案的 [build-system] 表格中增加一個額外的鍵值 build-backend。以下是一個範例：

[build-system]
# Defined by PEP 518:
requires = ["flit"]
# Defined by this PEP:
build-backend = "flit.api:main"

build-backend 是一個字串，用來命名將執行建置任務的 Python 物件（詳細資訊請參閱下文）。其格式遵循與 setuptools 入口點相同的 module:object 語法。例如，若字串如上例所示為 "flit.api:main"，則此物件將透過執行類似以下的程式碼來尋找：

import flit.api
backend = flit.api.main

也可以省略 :object 部分，例如：

build-backend = "flit.api"

這等同於：

import flit.api
backend = flit.api

形式上，該字串應滿足此文法：

identifier = (letter | '_') (letter | '_' | digit)*
module_path = identifier ('.' identifier)*
object_path = identifier ('.' identifier)*
entry_point = module_path (':' object_path)?

我們匯入 module_path，然後查找 module_path.object_path（若 object_path 缺失，則僅查找 module_path）。

在匯入模組路徑時，我們不會在包含原始碼樹的目錄中尋找，除非該目錄本來就在 sys.path 中（例如因為它是在 PYTHONPATH 中指定的）。儘管 Python 在某些情況下會自動將工作目錄添加到 sys.path 中，但用於解析後端的程式碼不應受到此影響。

若不存在 pyproject.toml 檔案，或者缺失 build-backend 鍵值，則該原始碼樹不使用本規範，工具應回退到執行 setup.py 的遺留行為（直接執行，或是隱式呼叫 setuptools.build_meta:__legacy__ 後端）。

當 build-backend 鍵值存在時，它具有優先權，且原始碼樹會遵循該後端的格式和約定（因此，除非後端需要，否則不需要 setup.py）。專案可能仍希望包含一個 setup.py 以保持對未使用此規範的工具的相容性。

本 PEP 也定義了一個用於 pyproject.toml 的 backend-path 鍵值，請參閱下方的「樹內建置後端」章節。此鍵值的使用方式如下：

[build-system]
# Defined by PEP 518:
requires = ["flit"]
# Defined by this PEP:
build-backend = "local_backend"
backend-path = ["backend"]

建置後端介面

建置後端物件預期擁有提供以下部分或全部掛鉤的屬性。通用的 config_settings 引數將在個別掛鉤後說明。

def build_wheel(wheel_directory, config_settings=None, metadata_directory=None):
    ...

def build_sdist(sdist_directory, config_settings=None):
    ...

def get_requires_for_build_wheel(config_settings=None):
    ...

def get_requires_for_build_wheel(config_settings):
    return ["wheel >= 0.25", "setuptools"]

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

def get_requires_for_build_sdist(config_settings=None):
    ...

config_settings

pip install                                           \
  --package-config CC=gcc                             \
  --global-option="--some-global-option"              \
  --build-option="--build-option1"                    \
  --build-option="--build-option2"

{
 "CC": "gcc",
 "--global-option": ["--some-global-option"],
 "--build-option": ["--build-option1", "--build-option2"],
}

原始碼發布包

我們繼續使用舊有的 sdist 格式，並增加一些新的限制。這種格式大多未定義，但基本上歸結為：一個名為 {NAME}-{VERSION}.{EXT} 的檔案，解壓縮後成為一個稱為 {NAME}-{VERSION}/ 的可建置原始碼樹。傳統上，這些始終包含 setup.py 風格的原始碼樹；我們現在也允許它們包含 pyproject.toml 風格的原始碼樹。

整合前端要求名為 {NAME}-{VERSION}.{EXT} 的 sdist 必須能產生名為 {NAME}-{VERSION}-{COMPAT-INFO}.whl 的 Wheel。

由 PEP 517 後端建置的 sdist 的新限制如下：

• 它們將是 gzipped tar 封存檔，副檔名為 .tar.gz。目前不允許使用 Zip 封存檔或其他 tarball 壓縮格式。
• Tar 封存檔必須以現代 POSIX.1-2001 pax tar 格式建立，該格式使用 UTF-8 處理檔案名稱。
• sdist 中包含的原始碼樹預期應包含 pyproject.toml 檔案。

演進說明

這裡的一個目標是盡可能簡單地將舊式 sdist 轉換為新式 sdist。（例如，這是支援動態建置需求的一個動機。）理想情況是存在一個單一的靜態 pyproject.toml，可以放入任何「0 版本」的 VCS checkout 中，將其轉換為新的樣式。這可能不是 100% 可能，但我們可以接近目標，保持對進度的追蹤很重要……因此有了這一節。

一個大概的計劃是：建立一個建置系統套件（setuptools_pypackage 或其他），知道如何對話我們想出的掛鉤語言，並將其轉換為對 setup.py 的呼叫。這可能需要對 setuptools 進行某種掛鉤或 Monkeypatch，以便在需要時提供提取 setup_requires= 引數的方法，並提供一個產生新式格式的 sdist 指令的新版本。這一切似乎是可行且足以應付大部分套件的（儘管顯然我們會在最終確定之前對這樣的系統進行原型設計）。（或者，這些變更可以直接對 setuptools 本身進行，而不是進入單獨的套件。）

但仍然存在兩個障礙，意味著我們可能無法自動將套件升級到新格式：

1. 目前存在一些套件，它們堅持在執行 setup.py 之前必須在環境中安裝特定套件。這意味著如果我們決定在隔離的虛擬環境類環境中執行建置指令稿，那麼專案將需要檢查它們是否執行此操作；如果是，那麼在升級到新系統時，它們將不得不開始明確宣告這些依賴（透過 setup_requires= 或 pyproject.toml 中的靜態宣告）。
2. 目前存在一些套件，它們不宣告一致的 metadata（例如 egg_info 和 bdist_wheel 可能會獲得不同的 install_requires=）。在升級到新系統時，專案將不得不評估這是否適用於它們，如果適用，它們將需要停止這樣做。

已拒絕的選項

• 我們討論了讓 Wheel 和 sdist 掛鉤建置解壓縮後的目錄，包含與其各自封存檔相同的內容。在某些情況下，這可以避免打包和解壓縮封存檔的需要，但這似乎是過早優化。對工具而言，使用封存檔作為標準交換格式是有利的（特別是對於 Wheel，其封存格式已經標準化）。對封存檔建立的嚴格控制對於可重現的建置很重要。而且，目前尚不清楚需要解壓縮發布包的任務是否會比需要封存檔的任務更常見。
• 我們考慮了一個額外的掛鉤，在呼叫 build_wheel 之前將檔案複製到建置目錄。查看現有的建置系統，我們發現將建置目錄傳入 build_wheel 對許多工具來說比預先將檔案複製到建置目錄更有意義。
• 將 build_wheel 傳入建置目錄的想法後來也被認為是不必要的複雜化。建置工具可以在建置時使用臨時目錄或快取目錄來儲存中間檔案。如果有需要，未來可以增加一個由前端控制的快取目錄。
• 關於 build_sdist 如何因預期的原因發出失敗訊號，各種選項進行了廣泛討論，包括拋出 NotImplementedError 以及回傳 NotImplemented 或 None。請不要在沒有極其充分的理由下試圖重新開啟此討論，因為我們已經對此感到厭倦了。
• 允許從原始碼樹中的檔案匯入後端，會與 Python 的匯入方式更一致。然而，不允許這樣做可以防止模組名稱衝突引起的混淆錯誤。本 PEP 的初始版本沒有提供允許後端從原始碼樹內的檔案匯入的方法，但在下一個修訂版中增加了 backend-path 鍵值，允許專案在需要時選擇加入此行為。

PEP 517 變更摘要

在本 PEP 的初始參考實作於 pip 19.0 發布後，對此 PEP 進行了以下變更：

• 明確禁止建置需求中的迴圈。
• 透過在 [build-system] 表格中引入 backend-path 鍵值，增加了對樹內後端和後端自託管的支援。
• 澄清了對於未明確指定 build-backend 的原始碼樹，setuptools.build_meta:__legacy__ PEP 517 後端是直接呼叫 setup.py 的一個可接受替代方案。

附錄 A：與 PEP 516 的比較

PEP 516 是一項競爭性的建置系統介面規範提案，該提案已被拒絕，轉而支援本 PEP。主要差異在於我們的建置後端是透過基於 Python 掛鉤的介面定義，而不是基於命令列的介面。

本附錄記錄了相較於 PEP 516 支援本 PEP 的論點。

我們不期望透過指定 Python 掛鉤而非命令列介面能單獨降低呼叫後端的複雜性，因為建置前端無論如何都會希望在子處理程序中執行掛鉤——這對於隔離建置前端本身與後端程式碼，並更好地控制建置後端的執行環境非常重要。因此，在兩個提案下，都需要在 pip 中編寫一些程式碼來產生子處理程序並與某種命令列/IPC 介面通訊，並且子處理程序中需要編寫一些程式碼來了解如何解析這些命令列參數並呼叫實際的建置後端實作。因此，此圖表適用於所有提案：

+-----------+          +---------------+           +----------------+
| frontend  | -spawn-> | child cmdline | -Python-> |    backend     |
|   (pip)   |          |   interface   |           | implementation |
+-----------+          +---------------+           +----------------+

這兩種方法之間的關鍵差異在於這些介面邊界如何映射到專案結構上。

.-= This PEP =-.

+-----------+          +---------------+    |      +----------------+
| frontend  | -spawn-> | child cmdline | -Python-> |    backend     |
|   (pip)   |          |   interface   |    |      | implementation |
+-----------+          +---------------+    |      +----------------+
                                            |
|______________________________________|    |
   Owned by pip, updated in lockstep        |
                                            |
                                            |
                                 PEP-defined interface boundary
                               Changes here require distutils-sig


.-= Alternative =-.

+-----------+    |     +---------------+           +----------------+
| frontend  | -spawn-> | child cmdline | -Python-> |    backend     |
|   (pip)   |    |     |   interface   |           | implementation |
+-----------+    |     +---------------+           +----------------+
                 |
                 |     |____________________________________________|
                 |      Owned by build backend, updated in lockstep
                 |
    PEP-defined interface boundary
  Changes here require distutils-sig

透過將 PEP 定義的介面邊界移入 Python 程式碼，我們獲得了三個關鍵優勢。

第一，由於建置前端數量可能很少（pip，還有……也許還有幾個？），而自訂建置後端的長尾效應將會很大（因為它們由每個套件分別選擇以匹配其特定的建置需求），因此實際的圖表可能看起來更像：

.-= This PEP =-.

+-----------+          +---------------+           +----------------+
| frontend  | -spawn-> | child cmdline | -Python+> |    backend     |
|   (pip)   |          |   interface   |        |  | implementation |
+-----------+          +---------------+        |  +----------------+
                                                |
                                                |  +----------------+
                                                +> |    backend     |
                                                |  | implementation |
                                                |  +----------------+
                                                :
                                                :

.-= Alternative =-.

+-----------+          +---------------+           +----------------+
| frontend  | -spawn+> | child cmdline | -Python-> |    backend     |
|   (pip)   |       |  |   interface   |           | implementation |
+-----------+       |  +---------------+           +----------------+
                    |
                    |  +---------------+           +----------------+
                    +> | child cmdline | -Python-> |    backend     |
                    |  |   interface   |           | implementation |
                    |  +---------------+           +----------------+
                    :
                    :

也就是說，本 PEP 導致整個生態系統中的程式碼總量更少。特別是，它降低了建立新建置系統的准入門檻。例如，這是一個完整、可運作的建置後端：

# mypackage_custom_build_backend.py
import os.path
import pathlib
import shutil
import tarfile

SDIST_NAME = "mypackage-0.1"
SDIST_FILENAME = SDIST_NAME + ".tar.gz"
WHEEL_FILENAME = "mypackage-0.1-py2.py3-none-any.whl"

#################
# sdist creation
#################

def _exclude_hidden_and_special_files(archive_entry):
    """Tarfile filter to exclude hidden and special files from the archive"""
    if archive_entry.isfile() or archive_entry.isdir():
        if not os.path.basename(archive_entry.name).startswith("."):
            return archive_entry

def _make_sdist(sdist_dir):
    """Make an sdist and return both the Python object and its filename"""
    sdist_path = pathlib.Path(sdist_dir) / SDIST_FILENAME
    sdist = tarfile.open(sdist_path, "w:gz", format=tarfile.PAX_FORMAT)
    # Tar up the whole directory, minus hidden and special files
    sdist.add(os.getcwd(), arcname=SDIST_NAME,
              filter=_exclude_hidden_and_special_files)
    return sdist, SDIST_FILENAME

def build_sdist(sdist_dir, config_settings):
    """PEP 517 sdist creation hook"""
    sdist, sdist_filename = _make_sdist(sdist_dir)
    return sdist_filename

#################
# wheel creation
#################

def get_requires_for_build_wheel(config_settings):
    """PEP 517 wheel building dependency definition hook"""
    # As a simple static requirement, this could also just be
    # listed in the project's build system dependencies instead
    return ["wheel"]

def build_wheel(wheel_directory,
                metadata_directory=None, config_settings=None):
    """PEP 517 wheel creation hook"""
    from wheel.archive import archive_wheelfile
    path = os.path.join(wheel_directory, WHEEL_FILENAME)
    archive_wheelfile(path, "src/")
    return WHEEL_FILENAME

當然，這是一個糟糕的建置後端：它要求使用者手動設定 src/mypackage-0.1.dist-info/ 中的 Wheel metadata；當版本號變更時，必須在多個地方手動更新……但它確實有效，且可以增量增加更多功能。許多經驗表明，大型成功的專案往往起源於快速破解（例如，Linux ——「只是一個愛好，不會很大很專業」；IPython/Jupyter —— 研究生的 $PYTHONSTARTUP 檔案），因此如果我們的目標是鼓勵開發優秀建置工具的活躍生態系統，那麼最大限度地降低准入門檻就非常重要。

第二，因為 Python 提供了更簡單且更豐富的結構來描述介面，我們消除了規範中不必要的複雜性——而規範是複雜性最糟糕的存放地，因為變更規範需要各個相關方之間痛苦的共識建立。在命令列介面方法中，我們必須想出 ad hoc 的方法將多種不同類型的輸入對映到單一線性命令列（例如我們如何避免使用者指定的配置引數與 PEP 定義的引數之間的衝突？我們如何指定可選引數？在使用 Python 介面時，這些問題有簡單、明顯的答案）。在產生和管理子處理程序時，有許多細節必須正確處理，微妙的跨平台差異，以及一些最明顯的方法——例如，使用 stdout 回傳 build_requires 操作的資料——可能會產生意想不到的陷阱（例如，當計算建置需求需要產生一些子處理程序，而這些子處理程序偶爾會將錯誤訊息列印到 stdout 時會發生什麼？顯然，謹慎的建置後端作者可以避免此問題，但定義 Python 介面的最明顯方式完全消除了這種可能性，因為掛鉤的回傳值界限清晰）。

總體而言，需要將建置後端隔離到它們自己的處理程序中意味著我們無法完全消除 IPC 複雜性——但透過將 IPC 通道的兩側置於單一專案的控制之下，使得修復 IPC 介面中的錯誤比如果修復錯誤需要生態系統中多個方面的協調一致與變更要便宜得多。

第三，且最重要的是，Python 掛鉤方法為我們在未來演進此規範提供了更強大的選擇。

具體來說，想像明年我們增加了一個新的 build_sdist_from_vcs 掛鉤，它提供了當前 build_sdist 掛鉤的替代方案，其中前端負責將版本控制追蹤 metadata 傳遞給後端（包括指出何時追蹤所有磁碟上的檔案），而不是個別後端必須自己查詢該資訊。為了管理過渡，我們會希望建置前端能在可用時透明地使用 build_sdist_from_vcs，否則回退到 build_sdist；並且我們希望建置後端能夠定義這兩種方法，以保持與舊版和新版建置前端的相容性。

此外，我們的機制還應滿足另外兩個目標：(a) 如果新版本的例如 pip 和 flit 都更新以支援新介面，那麼這應該足以讓它被使用；特別是，不應該要求每個使用 flit 的專案都更新其個人的 pyproject.toml 檔案。(b) 我們不希望為了進行這種協商而產生額外的處理程序，因為處理程序產生在某些平台（Windows）上部署大型多套件堆疊時很容易成為瓶頸。

在本文描述的介面中，所有這些目標都很容易實現。因為 pip 控制在子處理程序中執行的程式碼，它可以很容易地編寫如下內容：

command, backend, args = parse_command_line_args(...)
if command == "build_sdist":
   if hasattr(backend, "build_sdist_from_vcs"):
       backend.build_sdist_from_vcs(...)
   elif hasattr(backend, "build_sdist"):
       backend.build_sdist(...)
   else:
       # error handling

在將公共介面邊界放在子處理程序呼叫的替代方案中，這是不可能的——要麼我們需要產生一個額外的處理程序來查詢支援哪些介面（如 PEP 516 的早期草案所包含的，本文的替代方案），要麼我們完全放棄自動協商（如該 PEP 的當前版本），這意味著介面的任何變更都將要求 N 個個別專案在任何變更生效前更新其 pyproject.toml 檔案，並且任何變更必然僅限於新版本。

這的一個具體後果是，在本 PEP 中，我們能夠使 prepare_metadata_for_build_wheel 指令成為可選的。在我們的設計中，這可以由建置前端輕易處理，它們可以在處理程序執行器中放置如下程式碼：

def dump_wheel_metadata(backend, working_dir):
    """Dumps wheel metadata to working directory.

       Returns absolute path to resulting metadata directory
    """
    if hasattr(backend, "prepare_metadata_for_build_wheel"):
        subdir = backend.prepare_metadata_for_build_wheel(working_dir)
    else:
        wheel_fname = backend.build_wheel(working_dir)
        already_built = os.path.join(working_dir, "ALREADY_BUILT_WHEEL")
        with open(already_built, "w") as f:
            f.write(wheel_fname)
        subdir = unzip_metadata(os.path.join(working_dir, wheel_fname))
    return os.path.join(working_dir, subdir)

def ensure_wheel_is_built(backend, output_dir, working_dir, metadata_dir):
    """Ensures built wheel is available in output directory

       Returns absolute path to resulting wheel file
    """
    already_built = os.path.join(working_dir, "ALREADY_BUILT_WHEEL")
    if os.path.exists(already_built):
        with open(already_built, "r") as f:
            wheel_fname = f.read().strip()
        working_path = os.path.join(working_dir, wheel_fname)
        final_path = os.path.join(output_dir, wheel_fname)
        os.rename(working_path, final_path)
        os.remove(already_built)
    else:
        wheel_fname = backend.build_wheel(output_dir, metadata_dir=metadata_dir)
    return os.path.join(output_dir, wheel_fname)

從而向前端的其餘部分公開一個完全統一的介面，沒有額外的子處理程序呼叫，沒有重複的建置等。但顯然，這是您只想作為私有的、專案內介面一部分編寫的程式碼類型（例如，給定的範例要求工作目錄在兩次呼叫之間共享，但不能與任何其他 Wheel 建置共享，並且 metadata 輔助函式的回傳值將傳遞回 Wheel 建置函式）。

（當然，使 metadata 指令成為可選的是降低開發新後端准入門檻的一種方式，如上所述。）

版權

此文件已歸入公有領域 (public domain)。