前言

在我們的系列文章中，我們已經(jīng)深入探討了 setup.py 和 conda-build 這兩種強(qiáng)大的打包工具。您可能已經(jīng)注意到，社區(qū)正在逐步從使用 setup.py 這個(gè)可執(zhí)行的 Python 腳本，轉(zhuǎn)向一個(gè)名為 pyproject.toml 的靜態(tài)配置文件。

這不僅僅是一個(gè)簡(jiǎn)單的文件格式變化，它代表了 Python 打包理念的一次重要演進(jìn)。為什么需要這個(gè)新文件？它又該如何使用呢？

本文將為您全面解析 pyproject.toml，這個(gè)被 PEP 518 和 PEP 621 等提案確立為官方標(biāo)準(zhǔn)的現(xiàn)代化打包工具。

一、 開(kāi)發(fā)者篇：使用pyproject.toml定義你的項(xiàng)目

作為項(xiàng)目的創(chuàng)建者，擁抱 pyproject.toml 能讓你的項(xiàng)目配置更清晰、更標(biāo)準(zhǔn)，并能將以往散落在各種文件（setup.py, setup.cfg, MANIFEST.in 等）中的配置統(tǒng)一起來(lái)。

1. 為什么要使用pyproject.toml？

• 標(biāo)準(zhǔn)化：它是官方指定的、統(tǒng)一的 Python 項(xiàng)目配置文件格式。
• 聲明式，非可執(zhí)行：與 setup.py 不同，toml 文件是靜態(tài)的，只聲明“是什么”，而不是執(zhí)行“做什么”。這使得構(gòu)建過(guò)程更安全、更可預(yù)測(cè)。
• 統(tǒng)一配置入口：它不僅能定義項(xiàng)目元數(shù)據(jù)和依賴，還能統(tǒng)一存放 black, pytest, ruff, mypy 等開(kāi)發(fā)工具的配置，讓項(xiàng)目根目錄更整潔。
• 構(gòu)建系統(tǒng)解耦：它允許你自由選擇構(gòu)建后端（如 setuptools, poetry, pdm, hatch），而不僅僅是綁定 setuptools。

2. 如何創(chuàng)建pyproject.toml？

pyproject.toml 是一個(gè)基于 TOML (Tom’s Obvious, Minimal Language) 語(yǔ)法的文本文件，您需要在項(xiàng)目根目錄手動(dòng)創(chuàng)建它。

項(xiàng)目結(jié)構(gòu)示例：

my_modern_project/
├── my_awesome_tool/
│   ├── __init__.py
│   └── main.py
├── tests/
│   └── test_main.py
└── pyproject.toml   <-- 我們要?jiǎng)?chuàng)建的文件

pyproject.toml 文件詳解：

一個(gè)遵循 PEP 621 標(biāo)準(zhǔn)的現(xiàn)代化 pyproject.toml 核心內(nèi)容如下：

# pyproject.toml

# 1. 構(gòu)建系統(tǒng)聲明 (必需)
# 告訴 pip 等工具，這個(gè)項(xiàng)目需要用什么來(lái)構(gòu)建 (這里是 setuptools)
[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

# 2. 項(xiàng)目核心元數(shù)據(jù) (必需)
# 這部分取代了 setup.py 中的大部分參數(shù)
[project]
name = "my-awesome-tool"
version = "0.1.0"
authors = [
  { name="你的名字", email="你的郵箱@example.com" },
]
description = "一個(gè)功能強(qiáng)大的現(xiàn)代工具"
readme = "README.md" # 指定 README 文件
requires-python = ">=3.9"
license = { text = "MIT" }
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
]

# 3. 依賴項(xiàng) (核心)
# 這取代了 setup.py 中的 install_requires
dependencies = [
    "requests>=2.20",
    "numpy",
    "click",
]

# 4. 命令行工具 (可選)
# 這取代了 setup.py 中的 entry_points
[project.scripts]
awesome_tool = "my_awesome_tool.main:cli"

# 5. 可選依賴 (可選)
# 允許用戶安裝額外功能，例如 pip install "my-awesome-tool[extra]"
[project.optional-dependencies]
extra = ["pandas"]

# 6. 項(xiàng)目鏈接 (可選)
[project.urls]
Homepage = "https://github.com/your_username/my_modern_project"
"Bug Tracker" = "https://github.com/your_username/my_modern_project/issues"

可以看到，它的結(jié)構(gòu)清晰、可讀性強(qiáng)，并且?guī)缀鹾w了 setup.py 的所有核心功能。

3. 開(kāi)發(fā)和安裝

開(kāi)發(fā)流程與 setup.py 完全相同。您依然需要在一個(gè)虛擬環(huán)境中進(jìn)行開(kāi)發(fā)，并使用 pip 以可編輯模式安裝：

# 在激活虛擬環(huán)境后，于項(xiàng)目根目錄運(yùn)行
pip install -e .

pip (較新版本) 會(huì)自動(dòng)識(shí)別 pyproject.toml 文件，并根據(jù)其中的配置來(lái)正確安裝項(xiàng)目及其依賴。

二、 用戶篇：如何使用pyproject.toml定義的項(xiàng)目

作為用戶，你可能根本感覺(jué)不到任何區(qū)別，這正是 pyproject.toml 標(biāo)準(zhǔn)化的美妙之處。

1. 安裝流程

當(dāng)你從 GitHub 下載了一個(gè)包含 pyproject.toml 的項(xiàng)目后，安裝步驟和傳統(tǒng)項(xiàng)目一模一樣。

1. 創(chuàng)建并激活虛擬環(huán)境 (依然是最佳實(shí)踐)。
2. 安裝項(xiàng)目：
   • 作為普通用戶使用：pip install .
   • 作為貢獻(xiàn)者開(kāi)發(fā)：pip install -e .

pip 會(huì)在后臺(tái)自動(dòng)處理所有事情。它會(huì)讀取 pyproject.toml，理解項(xiàng)目的構(gòu)建需求和依賴，然后下載并安裝所有需要的東西。用戶無(wú)需關(guān)心底層是用 setuptools 還是 poetry 構(gòu)建的。

三、 總結(jié)與優(yōu)勢(shì)

pyproject.toml 是 Python 打包的未來(lái)，它的優(yōu)勢(shì)非常明顯：

四、 那如果項(xiàng)目文件里既有setup.py又有pyproject.toml呢?

pyproject.toml 是現(xiàn)代 Python 打包流程的唯一入口，它的優(yōu)先級(jí)更高。

當(dāng)一個(gè)構(gòu)建工具（例如 pip）開(kāi)始工作時(shí)，它會(huì)首先尋找 pyproject.toml。這個(gè)文件決定了接下來(lái)該做什么，以及由誰(shuí)（哪個(gè)構(gòu)建后端）來(lái)做。

下面我們來(lái)詳細(xì)分解一下具體的讀取和處理邏輯。

讀取流程：三步走

1. 入口 (pyproject.toml 的 [build-system] 部分)

   • pip 首先打開(kāi) pyproject.toml，并且只讀取 [build-system] 這個(gè)表格。
   • 這個(gè)表格告訴 pip：“嘿，要構(gòu)建這個(gè)項(xiàng)目，你需要使用 setuptools（或者 poetry, pdm 等）這個(gè)工具。”
   • pip 會(huì)確保這個(gè)構(gòu)建工具被安裝，然后把控制權(quán)完全交給它。

2. 構(gòu)建后端接管 (例如 setuptools)

   • 現(xiàn)在，setuptools (作為構(gòu)建后端) 開(kāi)始工作。它的任務(wù)是收集項(xiàng)目的所有元數(shù)據(jù)（包名、版本、依賴等）。
   • setuptools 會(huì)再次查看 pyproject.toml 文件，尋找一個(gè)名為 [project] 的表格。

3. 元數(shù)據(jù)讀取的優(yōu)先級(jí)

   • 這就是決定性的步驟，會(huì)根據(jù)文件內(nèi)容分為以下幾種情況：

兩種主要場(chǎng)景

場(chǎng)景一：現(xiàn)代項(xiàng)目 (最佳實(shí)踐)

• 文件狀態(tài):
  • pyproject.toml：包含了完整的 [project] 表格，里面定義了 name, version, dependencies 等所有核心信息。
  • setup.py：要么不存在，要么是一個(gè)非常簡(jiǎn)單的“墊片”文件，內(nèi)容可能只有：

    # setup.py (shim)
    from setuptools import setup
    setup()
    

• 讀取方式:
  • setuptools 會(huì)優(yōu)先讀取 pyproject.toml 中的 [project] 表格作為所有元數(shù)據(jù)的“唯一真實(shí)來(lái)源”。
  • 它會(huì)忽略 setup.py 文件中的任何元數(shù)據(jù)（如果有的話）。
  • 那個(gè)簡(jiǎn)單的 setup.py 文件僅僅是為了兼容一些非常老舊的、不認(rèn)識(shí) pyproject.toml 的工具。

結(jié)論：在這種模式下，pyproject.toml 完勝。

場(chǎng)景二：過(guò)渡期項(xiàng)目 (非常普遍)

• 文件狀態(tài):
  • pyproject.toml：只包含了 [build-system] 表格，可能還有一些工具配置（如 [tool.pytest]），但沒(méi)有 [project] 表格。
  • setup.py：包含一個(gè)完整的 setup() 函數(shù)，里面定義了 name, version, install_requires 等所有信息。
• 讀取方式:
  • pip 仍然從 pyproject.toml 開(kāi)始，得知需要使用 setuptools。
  • setuptools 接管后，在 pyproject.toml 中找不到 [project] 表格。
  • 于是，setuptools 會(huì)回退 (fallback) 到它的傳統(tǒng)模式：去執(zhí)行 setup.py 文件，并從 setup() 函數(shù)的參數(shù)中提取所有的項(xiàng)目元數(shù)據(jù)。

結(jié)論：在這種模式下，pyproject.toml 扮演“指路人”的角色，而 setup.py 仍然是“信息提供者”。

總結(jié)與建議

如果 pyproject.toml 文件中包含了完整的 [project] 表格（定義了項(xiàng)目名稱、版本、依賴等），同時(shí)又存在一個(gè)完備的 setup.py 文件，那么現(xiàn)代化的構(gòu)建工具（如新版 pip 和 setuptools）會(huì)：默認(rèn)優(yōu)先使用 pyproject.toml 文件中的信息。

pyproject.toml 是官方指定的“新版藍(lán)圖”，而 setup.py 是“舊版藍(lán)圖”。當(dāng)兩種藍(lán)圖都在時(shí)，構(gòu)建系統(tǒng)會(huì)默認(rèn)遵循更新、更標(biāo)準(zhǔn)的那一份。舊的 setup.py 文件中的配置在很大程度上會(huì)被忽略，以避免沖突和混淆。

到此這篇關(guān)于Python打包之pyproject.toml全方位使用的文章就介紹到這了,更多相關(guān)Python打包pyproject.toml內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評(píng)論