摘要

本PEP詳細說明了Python軟件包要在選定的構建（Build）系統上運行時，應該如何指定其依賴關系。本規范引入了一個新的配置文件，用于指定軟件包的構建依賴關系（假定今后的配置會使用相同的配置文件作為參考）。

基本原理

當Python首次開發用于構建項目、軟件分發的工具時，distutils [1]是選定的解決方案。隨著時間的推移，setuptools [2]越來越流行，它在distutils的基礎上增加了一些功能。兩者都應用了setup.py文件這樣一個概念。項目維護人員通過執行這個文件來構建其軟件的發行版（使得用戶也能夠安裝上述發行版）。

distutils是Python標準庫的一部分，所以，使用一個可執行文件來指定distutils下的構建條件是沒有問題的。將構建工具作為Python的一部分意味著，項目維護人員如果要構建一個項目的發行版，無需擔心setup.py有哪些外部依賴項。唯一的依賴項只是Python，因此沒有必要指定任何依賴信息。

但是當一個項目選擇使用setuptools時，像setup.py這樣的可執行文件的使用就成了一個問題。你無法在不知道setup.py文件依賴關系的條件下執行它。可是，目前還沒有標準的方法，在不執行存儲著依賴信息的setup.py文件的情況下，自動地了解它具體有哪些依賴項。這就形成了一個悖論：你不運行這個文件，你就無法知道它的內容；你不知道這個文件的內容，就無法運行它。

setuptools嘗試用它的setup() 函數的setup_requires參數來解決這個問題[3]。 此解決方案有許多問題，例如：

除了setuptools本身，沒有工具可以在不執行setup.py的情況下訪問這些信息，但是如果不安裝這些項目，setup.py將無法執行。

盡管setuptools本身會安裝setup.py中列出的一切，但在執行setup() 函數期間，它們將不會被安裝，這意味著實際使用此處添加的任何東西的唯一方法是通過越來越復雜的機制來延遲導入和使用，直到后來執行setup() 函數為止。

該方案不包括setuptools本身，也不能包括setuptools的替代品，這意味著像numpy.distutils這樣的項目很大程度上無法利用它，項目不能利用較新的setuptools功能，直到用戶自然地將setuptools的版本升級到較新的版本。

setup_requires中列出的項目只要執行setup.py就會被安裝，但執行setup.py的常見方式是通過另一個工具，比如已經負責管理依賴關系的pip。 這意味著像pip install spam這樣的命令可能最終導致pip和setuptools下載和安裝軟件包，最終，用戶需要配置這兩個工具（并且不受控制地調用setuptools）來更改它安裝的存儲庫等設置。 這也意味著用戶需要了解這兩種工具的發現規則，因為每個工具可能支持不同的軟件包格式或以不同方式確定最新版本。

這導致了setup_requires很少被人使用的情況，在這種情況下，項目傾向于只是在多個setup.py文件之間復制和粘貼代碼片段，或者完全跳過，僅僅只在某個地方記錄好--希望用戶在嘗試建立或安裝他們的項目之前，已經手動安裝好這些內容。

所有這一切使得pip [4]假定在執行setup.py文件時setuptools是存在的。但問題在于，如果另一個項目像setuptools那樣開始在社區中獲得關注，這個項目就沒有可擴展性。如此一來，會阻止其他項目獲得應有的關注。因為當pip無法推斷出項目需要的是除setuptools以外的某個東西時，使用setuptools便會產生沖突。

本PEP試圖在特定文件中、以一種聲明式的方式顯式列出項目構建系統的最小依賴關系，從而解決當前的狀況。此舉允許項目列出它必須具有何種構建依賴關系。例如，源代碼簽出到wheel，同時不落入setup.py所形成的悖論中。即，工具無法推斷項目需要自行構建的東西。實施本PEP將允許項目預先指定他們依賴的構建系統，以便像pip這樣的工具可以確保所有依賴條件已經安裝，以便運行構建系統來進行構建。

為了提供更多的上下文和推動本PEP，可以把所需的（大體）步驟看成是生成一個手工項目的過程：

項目的源代碼簽出

構建系統的安裝

構建系統的運行

本PEP涵蓋了第2步。 預計未來的PEP將包括第3步，包括如何使構建系統動態指定構建系統執行其工作所需的更多依賴性。 但是，本PEP的目的是為構建系統指定要開始運行所需的最低要求。

規范

構建系統的依賴關系將存儲在一個名為pyproject.toml的文件中，該文件以TOML格式編寫[6]。選擇這種格式是因為它可供人來使用（不像JSON [7]），它足夠靈活（不像configparser [9]）起源于某個標準（也不像configparser [9]），不過于復雜（不像YAML [8]）。 TOML格式已被Rust社區用作其包管理器的一部分[14]，據私人電郵所述，他們對選擇TOML感到非常滿意。關于為什么不選擇各種替代品的更詳細的討論可以閱讀以下其他文件格式的部分。

在配置文件中將會有一個[build-system]表來存儲與構建相關的數據。最初，表中只有一個關鍵字是有效的和必需的：requires。該鍵將包含一個字符串列表的值，代表執行構建系統所需的PEP 508依賴條件（意味著執行setup.py文件需要哪些依賴條件）。

以下的JSON架構[15]將與數據格式匹配，表示了某個特定類型的結果數據。這些數據來自于僅供演示用的TOML文件：

對于絕大多數依賴setuptools的Python項目，pyproject.toml文件會是這個樣子：

目前社區中setuptools和wheel的使用非常廣泛，所以當pyproject.toml文件不存在時，構建工具將使用上面的示例配置文件作為它們的默認語義。

除了[tool]表格，所有其他頂級密鑰和表格被保留下來，供其他的PEP將來使用。在[tool]表格中，只要使用了[tool]中的子表，工具就允許用戶指定其配置數據，例如，名為flit的工具會將其配置存儲在[tool.flit]中。

我們需要一些機制來在工具中分配tool.*命名空間中的名稱，以確保不同的項目不會嘗試使用相同的子表產生沖突。 我們的規則是:當且僅當一個項目擁有Cheeseshop / PyPI中的$NAME條目時，它才可以使用子表tool.$NAME。

一些未接受的想法

語義版本號

為了將來驗證配置文件的結構，最初提出了語義版本號。 默認值是1，背后的想法是：如果發生了針對之前定義的密鑰或表格的語義變化，而這些變化不向后兼容，則語義版本將增加一個新的數字。

但最終卻認定這是一個不成熟的優化。 我們的預期是，在配置文件中對語義上預先定義的內容的更改將是相當保守的。 在發生向后不兼容的變化的情況下，可以使用不同的名稱作為新的語義，以避免破壞舊的工具。

一個嵌套更深的命名空間

這個PEP的早期草案有一個頂級[Package]表。 想法是為語義版本方案限定范圍（請參閱語義版本關鍵字來了解這個想法被拒絕的原因）。 由于不再需要范圍的限定，因此擁有頂級表的重要性變得多余。

其他表名[build-system]表的另一個名字是[build]。替代名稱較短，但并未表達信息存儲在表中的意圖。 經過distutils-sig郵件列表上發起的投票，當前的名稱勝出。

其他文件格式

提出了其他幾種文件格式供考慮，都因各種原因而被拒絕。 關鍵要求是該格式可以由人進行編輯，且可以通過項目落地。 這徹底排除了某些格式，如對人類不友好的XML，而且從未認真討論過。

JSON

JSON格式[7]起初納入考慮，但很快被拒絕。 盡管作為基于字符串的人類可讀的數據交換格式非常好，但語法本身并不適合人類做簡單的編輯（例如，語法比所需的更冗長而不允許有注釋）。

提議的數據的示例JSON文件將是：

YAML

YAML格式[8]被設計為JSON的超集[7]，同時更易于手工操作。 YAML有三個主要問題。

一個是規范太多：如果打印在letter尺寸的紙上，則為86頁。這就使得有人可能會使用YAML的功能與一個解析器一起工作，而不是另一個解析器。有人建議在一個子集上進行標準化，但這基本上意味著要創建一個特定于該文件的新標準，這個標準是不容易長期處理的。

二是YAML默認本身并不安全。該規范允許在處理配置數據時最好避免代碼的任意執行。當然可以避免這種行為 - 例如，PyYAML提供了一個safe_load操作 - 但是如果任何工具不小心使用load，那么它們會自行開啟任意代碼執行。雖然這個PEP專注于構建固有涉及代碼執行的項目，但其他配置數據（如項目名稱和版本號）最終可能會在相同的文件中隨意執行任意代碼。

最后，最流行的YAML的Python實現是PyYAML [10]，它是一個包含幾千行代碼的大型項目，也是一個可選的C擴展模塊。雖然本身并不一定是個問題，但對于像pip這樣的項目來說，這更像是一個問題，因為他們很可能需要將PyYAML作為依賴項供應商，以便完全獨立（否則，最終會導致您安裝需要安裝工具的工具才能正常工作）。 PyYAML的一個概念驗證已經完成，看看供應一個簡單版本的庫是多么地簡單，這一切表明了一種可能性。

一個YAML示例文件:

Configparser

一個基于configparser INI風格配置文件考[9]。 不幸的是，沒有關于configparser接受什么的規范，導致版本之間的支持不一致。 例如，Python 2.7中的ConfigParser接受的內容與Python 3中的configparser接受的內容不同。 雖然可以標準化Python 3接受的內容，并簡單地供應configparser模塊的backport，但這確實意味著此PEP必須編碼，所有項目希望使用configparser的backport才能使用此PEP指定的元數據。 這是過度限制性的，如果有人不知道預期特定版本的configparser會導致混淆。

一個示例INI文件是：

Python語法

有人提議使用Python語法作為配置格式。 該文件將在頂層包含一個字典，數據全部在該字典中，并且由鍵定義部分。 所有的Python程序員都會習慣這種格式，而且不需要第三方依賴來讀取配置數據，如果用ast.literal_eval（）進行解析，它可能是安全的[13]。 Python語法可以與JSON相同，同時支持尾隨逗號和注釋。 另外，Python的更豐富的數據模型可能對未來的某些配置需求非常有用（例如非字符串字典密鑰，浮點數與整數值）。

不過，python語法是Python特有的格式，我們預計這些數據可能需要通過不是用Python編寫的打包工具等來讀取。

提議的Python語法文件示例如下：

其他文件名稱

其他幾個文件名在考慮后并未接受（這是一個非常相似的話題，最終決定主要是根據喜好）。

pysettings.toml

最合理的選擇。

pypa.toml

雖然參考PyPA [11]是有道理的，但這是一個有點用處的術語。沒有特定領域的知識，最好讓文件名有意義。

pybuild.toml

從這個PEP的限制性角度來看，這個文件名是有意義的，但是如果有任何非構建元數據被添加到文件中，那么名稱就不再有意義了。

pip.toml

工具特定。

meta.toml

太通用;項目可能希望擁有自己的元數據文件。

setup.toml

在保持setup.py的傳統感謝的同時，它不一定與未來文件可能包含的內容相匹配（例如，.e.g知道項目名稱是否是其設置的一部分？）。

pymeta.toml

對新手不太明顯。

pypackage.toml＆pypackaging.toml

概念混淆，考慮什么才是一個“包”？（項目和包的區別）

pydevelop.toml

該文件可能包含非特定于開發的細節。

pysource.toml

與源代碼沒有直接關系。

pytools.toml

由于該文件（當前）針對項目管理，因此具有誤導性。

dstufft.toml

個體相關性太大