Python軟件包要在選定的構(gòu)建（Build）系統(tǒng)上運行時，應(yīng)該如何指定其依賴關(guān)系

摘要

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

基本原理

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

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

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

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

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

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

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

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

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

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

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

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

項目的源代碼簽出

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

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

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

規(guī)范

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

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

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

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

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

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

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

一些未接受的想法

語義版本號

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

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

一個嵌套更深的命名空間

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

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

其他文件格式

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

JSON

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

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

YAML

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

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

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

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

一個YAML示例文件:

Configparser

一個基于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，但這確實意味著此PEP必須編碼，所有項目希望使用configparser的backport才能使用此PEP指定的元數(shù)據(jù)。 這是過度限制性的，如果有人不知道預(yù)期特定版本的configparser會導(dǎo)致混淆。

一個示例INI文件是：

Python語法

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

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

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

其他文件名稱

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

pysettings.toml

最合理的選擇。

pypa.toml

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

pybuild.toml

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

pip.toml

工具特定。

meta.toml

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

setup.toml

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

pymeta.toml

對新手不太明顯。

pypackage.toml＆pypackaging.toml

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

pydevelop.toml

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

pysource.toml

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

pytools.toml

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

dstufft.toml

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