摘要

本PEP詳細(xì)說明了Python軟件包要在選定的構(gòu)建（Build）系統(tǒng)上運(yùn)行時(shí)，應(yīng)該如何指定其依賴關(guān)系。本規(guī)范引入了一個(gè)新的配置文件，用于指定軟件包的構(gòu)建依賴關(guān)系（假定今后的配置會(huì)使用相同的配置文件作為參考）。

基本原理

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

distutils是Python標(biāo)準(zhǔn)庫的一部分，所以，使用一個(gè)可執(zhí)行文件來指定distutils下的構(gòu)建條件是沒有問題的。將構(gòu)建工具作為Python的一部分意味著，項(xiàng)目維護(hù)人員如果要構(gòu)建一個(gè)項(xiàng)目的發(fā)行版，無需擔(dān)心setup.py有哪些外部依賴項(xiàng)。唯一的依賴項(xiàng)只是Python，因此沒有必要指定任何依賴信息。

但是當(dāng)一個(gè)項(xiàng)目選擇使用setuptools時(shí)，像setup.py這樣的可執(zhí)行文件的使用就成了一個(gè)問題。你無法在不知道setup.py文件依賴關(guān)系的條件下執(zhí)行它。可是，目前還沒有標(biāo)準(zhǔn)的方法，在不執(zhí)行存儲(chǔ)著依賴信息的setup.py文件的情況下，自動(dòng)地了解它具體有哪些依賴項(xiàng)。這就形成了一個(gè)悖論：你不運(yùn)行這個(gè)文件，你就無法知道它的內(nèi)容；你不知道這個(gè)文件的內(nèi)容，就無法運(yùn)行它。

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

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

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

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

setup_requires中列出的項(xiàng)目只要執(zhí)行setup.py就會(huì)被安裝，但執(zhí)行setup.py的常見方式是通過另一個(gè)工具，比如已經(jīng)負(fù)責(zé)管理依賴關(guān)系的pip。 這意味著像pip install spam這樣的命令可能最終導(dǎo)致pip和setuptools下載和安裝軟件包，最終，用戶需要配置這兩個(gè)工具（并且不受控制地調(diào)用setuptools）來更改它安裝的存儲(chǔ)庫等設(shè)置。 這也意味著用戶需要了解這兩種工具的發(fā)現(xiàn)規(guī)則，因?yàn)槊總€(gè)工具可能支持不同的軟件包格式或以不同方式確定最新版本。

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

所有這一切使得pip [4]假定在執(zhí)行setup.py文件時(shí)setuptools是存在的。但問題在于，如果另一個(gè)項(xiàng)目像setuptools那樣開始在社區(qū)中獲得關(guān)注，這個(gè)項(xiàng)目就沒有可擴(kuò)展性。如此一來，會(huì)阻止其他項(xiàng)目獲得應(yīng)有的關(guān)注。因?yàn)楫?dāng)pip無法推斷出項(xiàng)目需要的是除setuptools以外的某個(gè)東西時(shí)，使用setuptools便會(huì)產(chǎn)生沖突。

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

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

項(xiàng)目的源代碼簽出

構(gòu)建系統(tǒng)的安裝

構(gòu)建系統(tǒng)的運(yùn)行

本PEP涵蓋了第2步。 預(yù)計(jì)未來的PEP將包括第3步，包括如何使構(gòu)建系統(tǒng)動(dòng)態(tài)指定構(gòu)建系統(tǒng)執(zhí)行其工作所需的更多依賴性。 但是，本PEP的目的是為構(gòu)建系統(tǒng)指定要開始運(yùn)行所需的最低要求。

規(guī)范

構(gòu)建系統(tǒng)的依賴關(guān)系將存儲(chǔ)在一個(gè)名為pyproject.toml的文件中，該文件以TOML格式編寫[6]。選擇這種格式是因?yàn)樗晒┤藖硎褂茫ú幌馢SON [7]），它足夠靈活（不像configparser [9]）起源于某個(gè)標(biāo)準(zhǔn)（也不像configparser [9]），不過于復(fù)雜（不像YAML [8]）。 TOML格式已被Rust社區(qū)用作其包管理器的一部分[14]，據(jù)私人電郵所述，他們對選擇TOML感到非常滿意。關(guān)于為什么不選擇各種替代品的更詳細(xì)的討論可以閱讀以下其他文件格式的部分。

在配置文件中將會(huì)有一個(gè)[build-system]表來存儲(chǔ)與構(gòu)建相關(guān)的數(shù)據(jù)。最初，表中只有一個(gè)關(guān)鍵字是有效的和必需的：requires。該鍵將包含一個(gè)字符串列表的值，代表執(zhí)行構(gòu)建系統(tǒng)所需的PEP 508依賴條件（意味著執(zhí)行setup.py文件需要哪些依賴條件）。

以下的JSON架構(gòu)[15]將與數(shù)據(jù)格式匹配，表示了某個(gè)特定類型的結(jié)果數(shù)據(jù)。這些數(shù)據(jù)來自于僅供演示用的TOML文件：

對于絕大多數(shù)依賴setuptools的Python項(xiàng)目，pyproject.toml文件會(huì)是這個(gè)樣子：

目前社區(qū)中setuptools和wheel的使用非常廣泛，所以當(dāng)pyproject.toml文件不存在時(shí)，構(gòu)建工具將使用上面的示例配置文件作為它們的默認(rèn)語義。

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

我們需要一些機(jī)制來在工具中分配tool.*命名空間中的名稱，以確保不同的項(xiàng)目不會(huì)嘗試使用相同的子表產(chǎn)生沖突。 我們的規(guī)則是:當(dāng)且僅當(dāng)一個(gè)項(xiàng)目擁有Cheeseshop / PyPI中的$NAME條目時(shí)，它才可以使用子表tool.$NAME。

一些未接受的想法

語義版本號

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

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

一個(gè)嵌套更深的命名空間

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

其他表名[build-system]表的另一個(gè)名字是[build]。替代名稱較短，但并未表達(dá)信息存儲(chǔ)在表中的意圖。 經(jīng)過distutils-sig郵件列表上發(fā)起的投票，當(dāng)前的名稱勝出。

其他文件格式

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

JSON

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

提議的數(shù)據(jù)的示例JSON文件將是：

YAML

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

一個(gè)是規(guī)范太多：如果打印在letter尺寸的紙上，則為86頁。這就使得有人可能會(huì)使用YAML的功能與一個(gè)解析器一起工作，而不是另一個(gè)解析器。有人建議在一個(gè)子集上進(jìn)行標(biāo)準(zhǔn)化，但這基本上意味著要?jiǎng)?chuàng)建一個(gè)特定于該文件的新標(biāo)準(zhǔn)，這個(gè)標(biāo)準(zhǔn)是不容易長期處理的。

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

最后，最流行的YAML的Python實(shí)現(xiàn)是PyYAML [10]，它是一個(gè)包含幾千行代碼的大型項(xiàng)目，也是一個(gè)可選的C擴(kuò)展模塊。雖然本身并不一定是個(gè)問題，但對于像pip這樣的項(xiàng)目來說，這更像是一個(gè)問題，因?yàn)樗麄兒芸赡苄枰獙yYAML作為依賴項(xiàng)供應(yīng)商，以便完全獨(dú)立（否則，最終會(huì)導(dǎo)致您安裝需要安裝工具的工具才能正常工作）。 PyYAML的一個(gè)概念驗(yàn)證已經(jīng)完成，看看供應(yīng)一個(gè)簡單版本的庫是多么地簡單，這一切表明了一種可能性。

一個(gè)YAML示例文件:

Configparser

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

一個(gè)示例INI文件是：

Python語法

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

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

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

其他文件名稱

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

pysettings.toml

最合理的選擇。

pypa.toml

雖然參考PyPA [11]是有道理的，但這是一個(gè)有點(diǎn)用處的術(shù)語。沒有特定領(lǐng)域的知識，最好讓文件名有意義。

pybuild.toml

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

pip.toml

工具特定。

meta.toml

太通用;項(xiàng)目可能希望擁有自己的元數(shù)據(jù)文件。

setup.toml

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

pymeta.toml

對新手不太明顯。

pypackage.toml＆pypackaging.toml

概念混淆，考慮什么才是一個(gè)“包”？（項(xiàng)目和包的區(qū)別）

pydevelop.toml

該文件可能包含非特定于開發(fā)的細(xì)節(jié)。

pysource.toml

與源代碼沒有直接關(guān)系。

pytools.toml

由于該文件（當(dāng)前）針對項(xiàng)目管理，因此具有誤導(dǎo)性。

dstufft.toml

個(gè)體相關(guān)性太大