pyproject.toml 文件是做什么用的？

Question

背景

我正准備嘗試從 GitHub 下載的 Python package ，發現它沒有setup.py ，所以我無法安裝它

pip install -e <folder>

相反，package 有一個pyproject.toml文件，該文件似乎與setup.py通常具有非常相似的條目。

我發現了什么

谷歌搜索引導我進入PEP-518 ，它在基本原理部分對setup.py提出了一些批評。 但是，它並沒有明確說明應該避免使用setup.py ，或者pyproject.toml將完全取代setup.py 。

問題

pyproject.toml是用來替換setup.py的東西嗎？ 或者 package 是否應該同時帶有pyproject.toml和setup.py ？
如何在可編輯的 state 中安裝帶有pyproject.toml的項目？

Answer 1

是的， pyproject.toml是PEP 518的指定文件格式，其中包含 Python 項目的構建系統要求。

這解決了構建工具依賴雞和雞蛋的問題，即pip可以讀取pyproject.toml以及可能需要什么版本的setuptools或wheel one。

如果您需要setup.py進行可編輯安裝，您可以在setup.py中使用 shim：

#!/usr/bin/env python

import setuptools

if __name__ == "__main__":
    setuptools.setup()

Answer 2

pyproject.toml是替換setup.py的新統一 Python 項目設置文件。 可編輯的安裝仍然需要一個setup.py ： import setuptools; setuptools.setup() import setuptools; setuptools.setup()

要使用pyproject.toml ，請運行python -m pip install.

然后，如果項目使用poetry而不是pip ，您可以像這樣安裝依賴項（到%USERPROFILE%\AppData\Local\pypoetry\Cache\virtualenvs ）：

poetry install

然后運行pytest 之類的依賴項：

poetry run pytest tests/

並預提交（使用.pre-commit-config.yaml ）：

poetry run pre-commit install
poetry run pre-commit run --all-files

Answer 3

目前在 Python 社區中流行多種打包工具，雖然setuptools似乎仍然很流行，但它不再是事實上的標准。 這種情況給最終用戶和開發人員帶來了許多麻煩：

1. 對於基於setuptools的軟件包，如果未安裝setuptools ，則從發行版的源代碼/構建安裝可能會失敗；
2. 不能使用pip從源代碼安裝基於其他打包工具的包。 必須先安裝打包工具，然后使用工具特定的命令安裝/構建分發 package；
3. 如果 package 作者決定更改打包工具，則還必須更改工作流程以使用不同的工具特定命令。

pyproject.toml是PEP 517和PEP 518為解決這些問題而引入的新配置文件：

...想想為項目生成構建工件所需的（粗略）步驟：

1. 項目的源代碼簽出。
2. 安裝構建系統。
3. 執行構建系統。

此 PEP [518] 涵蓋步驟 #2。 PEP 517涵蓋了第 3 步……

任何工具也可以使用自己的部分（表）擴展此文件以接受特定於工具的選項，但這取決於他們而不是必需的。

---

對於基於setuptools的包pyproject.toml並不是嚴格意義上的替換setup.py ，而是為了確保它在仍然需要時正確執行。 對於其他打包工具——是的，它是：

如果存在build-backend鍵，則優先，源代碼樹遵循指定后端的格式和約定（因此不需要setup.py ，除非后端需要它）。 項目可能仍希望包含setup.py以與不使用此規范的工具兼容。

---

“可編輯安裝”是setuptools的功能，因此PEP 517不支持它：

Install Options:
  -e, --editable <path/url>   Install a project in editable mode (i.e. setuptools "develop mode")

要以可編輯模式安裝基於setuptools的 package，它需要一個setup.py文件，其中至少包含最少的內容：

from setuptools import setup

setup()

Answer 4

僅回答這部分，因為 rest 已被其他人很好地解釋：

如何在可編輯的 state 中安裝帶有 pyproject.toml 的項目？

解決方法（工作）

1. 克隆項目並運行poetry install以首先創建它的正常安裝。

2. 使用poetry env info -p獲取詩歌創建的虛擬環境的路徑。 它可能類似於<absolute path of your cloned project/.venv 。 然后檢查其中的site-packages目錄的路徑是什么。 它取決於您的 Python 版本，類似於<absolute path of your cloned project/.venv/lib/python3.9/site-packages 。

3. 在這個site-packages中創建一個.pth文件。 它應該包含一行文本，其中包含 package 的完整路徑，以便在可編輯模式下安裝：

echo "<absolute path of your cloned project>" > "<absolute path of your cloned project/.venv/lib/python3.9/site-packages/package_name.pth"

正確修復（自 2021 年 8 月起未實施）

2021 年 6 月，描述基於pyproject.toml的構建的可編輯安裝的PEP-660已被接受。

在這個 PR中，它對poetry的實現正在進行中。

所以我們需要等待它完成，合並並發布新的poetry版本。

來源

除了上面鏈接的那些，我的主要來源是“pip install -e.等價物？” - github.com/python-poetry/poetry 中的問題 #34 。

Answer 5

pyproject.toml 可以聲明 python package 中的文件以及將在PyPi中顯示的所有元數據。

像flit這樣的工具可以將 pyproject.toml 文件處理成 package，可以上傳到 PyPi 或與 pip 一起安裝。

其他工具將 pyproject.toml 用於其他目的。 例如， pytest存儲有關在何處查找和如何運行測試的信息，以及 pytest 關於在運行測試之前修改 pythonpath (sys.path) 的說明。 許多 IDE 可以使用它來幫助開發人員方便地運行測試。