檔案格式

構建系統依賴項將儲存在名為 pyproject.toml 的檔案中，該檔案採用 TOML 格式編寫 [6]。

選擇此格式是因為它易於人類閱讀（不像 JSON [7]），它足夠靈活（不像 configparser [9]），源自於標準（也不像 configparser [9]），並且不至於過於複雜（不像 YAML [8]）。TOML 格式已被 Rust 社群作為其 Cargo 套件管理器的一部分使用 [14]，且在私人電子郵件中表示他們對選擇 TOML 非常滿意。關於為何未選擇其他替代方案的更詳盡討論，可以在其他檔案格式章節中閱讀。儘管如此，作者確實意識到配置檔案格式的選擇最終是主觀的，必須做出選擇，而作者在此情況下更偏好 TOML。

我們在下方列出了工具預期要辨識/遵守的表格。本 PEP 未指定的表格保留給未來其他 PEP 使用。

build-system 表格

[build-system] 表格用於儲存與構建相關的資料。最初，該表格中只有一個鍵有效且為強制性：requires。此鍵的值必須是一個字串列表，代表執行構建系統所需的 PEP 508 依賴項（目前這意味著執行 setup.py 檔案所需的依賴項）。

對於絕大多數依賴 setuptools 的 Python 專案，pyproject.toml 檔案將是：

[build-system]
# Minimum requirements for the build system to execute.
requires = ["setuptools"]  # PEP 508 specifications.

由於目前 setuptools 在社群中的使用非常廣泛，預期當 pyproject.toml 檔案不存在時，構建工具將使用上述範例配置檔案作為其預設語義。

工具不應要求必須存在 [build-system] 表格。pyproject.toml 檔案可用於儲存與構建無關的配置細節，因此合法地缺少 [build-system] 表格。如果檔案存在但缺少 [build-system] 表格，則應使用上述指定的預設值。如果指定了該表格但缺少必要的欄位，則工具應將其視為錯誤。

tool 表格

[tool] 表格是任何與你的 Python 專案相關的工具（不僅僅是構建工具）可以讓使用者指定配置資料的地方，前提是他們在 [tool] 中使用子表格，例如 flit 工具會將其配置儲存在 [tool.flit] 中。

我們需要某種機制來分配 tool.* 命名空間內的名稱，以確保不同的專案不會嘗試使用相同的子表格而發生衝突。我們的規則是，專案僅在擁有 Cheeseshop/PyPI 中 $NAME 的條目時，才能使用子表格 tool.$NAME。

JSON Schema

為了僅用於說明目的而提供來自 TOML 檔案所得資料的型別特定表示，以下 JSON Schema [15] 將符合該資料格式：

{
    "$schema": "http://json-schema.org/schema#",

    "type": "object",
    "additionalProperties": false,

    "properties": {
        "build-system": {
            "type": "object",
            "additionalProperties": false,

            "properties": {
                "requires": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                }
            },
            "required": ["requires"]
        },

        "tool": {
            "type": "object"
        }
    }
}

語義版本鍵

為了對配置檔案的結構進行未來驗證，最初提議了一個 semantics-version 鍵。預設為 1，其想法是如果之前定義的鍵或表格發生了任何不向後相容的語義變更，則 semantics-version 將增加一個新數字。

然而最終決定這是一個過早的優化。預期配置檔案中語義預定義內容的變更將會相當保守。而在發生不向後相容變更的情況下，可以使用不同的名稱來表示新的語義，以避免破壞舊的工具。

更深層的巢狀命名空間

本 PEP 的早期草稿有一個頂層的 [package] 表格。其想法是為語義版本控制方案強加一些範圍限制（參見語義版本鍵以了解為什麼該想法被拒絕）。隨著範圍限制需求的消除，擁有頂層表格的意義變得多餘。

其他表格名稱

另一個為 [build-system] 表格提議的名稱是 [build]。替代名稱更短，但不能傳達出該表格中儲存資訊意圖的足夠多資訊。在 distutils-sig 郵寄清單上投票後，目前的名稱勝出。

其他檔案格式

還有其他幾種檔案格式被提出討論，但都因各種原因被拒絕。關鍵需求是該格式應可由人類編輯，並具有一個可輕易被專案整合的實作。這直接排除了某些如 XML 這樣對人類不友善且從未被嚴肅討論的格式。

{
    "build": {
        "requires": [
            "setuptools",
            "wheel>=0.27"
        ]
    }
}

build:
    requires:
        - setuptools
        - wheel>=0.27

[build]
requires =
    setuptools
    wheel>=0.27

# The build configuration
{"build": {"requires": ["setuptools",
                        "wheel>=0.27", # note the trailing comma
                        # "numpy>=1.10" # a commented out data line
                        ]
# and here is an arbitrary comment.
           }
 }

堅持使用 setup.cfg

setuptools 用作通用格式的 setup.cfg 存在兩個問題。一是它們是 .ini 檔案，正如上述 configparser 討論中所提到的那樣存在問題。另一個是該檔案的結構從未被嚴格定義，因此不知道未來使用哪種格式是安全的，而不會潛在地混淆 setuptools 的安裝。

其他檔案名稱

還有其他幾種檔案名稱被考慮並拒絕（儘管這在很大程度上是一個瑣碎的爭論話題，所以決定主要歸結為品味）。

pysettings.toml

最合理的替代方案。

pypa.toml

雖然引用 PyPA [11] 是合理的，但這是一個有些小眾的術語。最好讓檔案名稱在沒有特定領域知識的情況下也能說得通。

pybuild.toml

從本 PEP 的限制角度來看，此檔名是有意義的，但如果任何非構建元資料被新增到檔案中，那麼這個名稱就不再有意義了。

pip.toml

太工具特定了。

meta.toml

太通用；專案可能希望擁有自己的元資料檔案。

setup.toml

雖然由於 setup.py 的存在而保持了傳統，但它不一定符合該檔案未來可能包含的內容（例如，知道專案名稱是否天生就是其設定的一部分？）。

pymeta.toml

對於程式設計和/或 Python 的新手來說不直觀。

pypackage.toml & pypackaging.toml

關於什麼是「套件」的名稱混淆（專案與命名空間）。

pydevelop.toml

該檔案可能包含與開發無關的細節。

pysource.toml

與原始碼沒有直接關係。

pytools.toml

誤導，因為該檔案（目前）旨在用於專案管理。

dstufft.toml

太個人化了。 ;)