前言

pyproject.toml 是一個(gè)配置文件，用于定義 Python 項(xiàng)目的構(gòu)建系統(tǒng)和相關(guān)的元數(shù)據(jù)。它是 Python 社區(qū)為了解決項(xiàng)目構(gòu)建和依賴管理問(wèn)題而引入的一種標(biāo)準(zhǔn)化方式，最初由 PEP 518 提出。pyproject.toml 文件被廣泛使用，尤其是在構(gòu)建工具（如 Poetry 和 Flit）中，用來(lái)替代傳統(tǒng)的 setup.cfg 文件。

主要用途

• 定義構(gòu)建系統(tǒng)：

  • pyproject.toml 文件中可以指定構(gòu)建工具及其版本，如 setuptools 或 poetry，以及這些工具所需的依賴項(xiàng)。這使得項(xiàng)目的構(gòu)建環(huán)境更加可控和可重復(fù)。

• 項(xiàng)目元數(shù)據(jù)：

  • 包括項(xiàng)目的名稱、版本、描述、作者、許可證等信息，可以在 pyproject.toml 文件中定義。這些信息可以被構(gòu)建工具或包管理工具讀取和使用。

• 依賴管理：

  • 該文件可以管理項(xiàng)目的依賴關(guān)系，包括運(yùn)行時(shí)依賴、開(kāi)發(fā)時(shí)依賴等，類似于 requirements.txt，但更加結(jié)構(gòu)化和靈活。

• 配置構(gòu)建工具的行為：

  • 對(duì)于不同的構(gòu)建工具，如 setuptools、poetry、black、isort 等，可以在 pyproject.toml 中配置其行為。

文件結(jié)構(gòu)

一個(gè)典型的 pyproject.toml 文件由幾個(gè)部分組成，每個(gè)部分對(duì)應(yīng)不同的功能和配置信息。以下是LlamaFactory示例：

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[tool.ruff]
target-version = "py38"
line-length = 119
indent-width = 4

[tool.ruff.lint]
ignore = ["C408", "C901", "E501", "E731", "E741", "W605"]
select = ["C", "E", "F", "I", "W"]

[tool.ruff.lint.isort]
lines-after-imports = 2
known-first-party = ["llamafactory"]
known-third-party = [
    "accelerate",
    "datasets",
    "gradio",
    "numpy",
    "peft",
    "torch",
    "transformers",
    "trl"
]

[tool.ruff.format]
quote-style = "double"
indent-style = "space"
docstring-code-format = true
skip-magic-trailing-comma = false
line-ending = "auto"

這個(gè) pyproject.toml 文件配置了項(xiàng)目的構(gòu)建系統(tǒng)以及使用 ruff 進(jìn)行代碼檢查和格式化的相關(guān)設(shè)置。以下是各部分的詳細(xì)解釋：

1. [build-system]

• requires: 指定了項(xiàng)目的構(gòu)建系統(tǒng)依賴項(xiàng)。這里要求使用 setuptools 版本 61.0 或更高版本。這意味著在構(gòu)建這個(gè)項(xiàng)目時(shí)，Python 環(huán)境中必須安裝 setuptools，且版本不低于 61.0。

• build-backend: 指定了用于構(gòu)建項(xiàng)目的后端工具，這里使用的是 setuptools.build_meta。這意味著 setuptools 將作為構(gòu)建過(guò)程的核心工具。

2. [tool.ruff]

• target-version: 指定了代碼的目標(biāo) Python 版本，這里是 Python 3.8 (py38)。ruff 將根據(jù)這個(gè)版本進(jìn)行相應(yīng)的檢查和優(yōu)化。

• line-length: 指定了代碼行的最大長(zhǎng)度，超過(guò)這個(gè)長(zhǎng)度會(huì)被視為格式錯(cuò)誤。這里設(shè)置為 119 個(gè)字符。

• indent-width: 指定代碼縮進(jìn)的寬度，這里設(shè)置為 4 個(gè)空格。

3. [tool.ruff.lint]

• ignore: 指定了一些要忽略的規(guī)則或錯(cuò)誤代碼。列出的錯(cuò)誤代碼將不會(huì)在代碼檢查時(shí)觸發(fā)。

• select: 指定了要檢查的錯(cuò)誤或警告類別。只有屬于這些類別的檢查才會(huì)被啟用。

4. [tool.ruff.lint.isort]

• lines-after-imports: 指定在導(dǎo)入語(yǔ)句之后應(yīng)保留的空行數(shù)，這里設(shè)置為 2 行。

• known-first-party: 列出了項(xiàng)目中的第一方模塊，即 llamafactory，用于在導(dǎo)入排序時(shí)識(shí)別項(xiàng)目?jī)?nèi)部的模塊。

• known-third-party: 列出了已知的第三方庫(kù)，這些庫(kù)將在導(dǎo)入排序時(shí)與其他模塊區(qū)分開(kāi)來(lái)。

5. [tool.ruff.format]

• quote-style: 指定字符串使用的引號(hào)樣式，這里設(shè)置為 double，即雙引號(hào)。

• indent-style: 指定縮進(jìn)風(fēng)格，這里使用 space（空格）而非 tab。

• docstring-code-format: 設(shè)置為 true，表示在文檔字符串（docstring）中也會(huì)應(yīng)用代碼格式化規(guī)則。

• skip-magic-trailing-comma: 設(shè)置為 false，意味著即使添加魔術(shù)尾逗號(hào)（magic trailing comma），也不會(huì)跳過(guò)格式化。

• line-ending: 設(shè)置為 auto，表示根據(jù)操作系統(tǒng)的默認(rèn)設(shè)置自動(dòng)選擇行結(jié)尾符。

小結(jié)

這個(gè) pyproject.toml 文件主要配置了項(xiàng)目的構(gòu)建系統(tǒng)，并詳細(xì)定義了 ruff 工具用于代碼風(fēng)格檢查和格式化的規(guī)則。這些設(shè)置幫助確保代碼的一致性和質(zhì)量，減少錯(cuò)誤，并遵循團(tuán)隊(duì)的編碼規(guī)范。

工作流程

在執(zhí)行 pip install . 時(shí)，pyproject.toml 文件會(huì)在構(gòu)建和安裝 Python 項(xiàng)目的過(guò)程中被引用。具體流程如下：

1. 識(shí)別 pyproject.toml 文件

• 當(dāng)你在項(xiàng)目的根目錄執(zhí)行 pip install . 命令時(shí)，pip 會(huì)首先檢查該目錄下是否存在 pyproject.toml 文件。
• 如果存在這個(gè)文件，pip 會(huì)將其視為該項(xiàng)目的構(gòu)建配置文件，并按照其中的內(nèi)容來(lái)指導(dǎo)接下來(lái)的構(gòu)建過(guò)程。

2. 解析 build-system 部分

• pip 首先讀取 pyproject.toml 文件中的 [build-system] 部分。這一部分定義了構(gòu)建項(xiàng)目所需的依賴項(xiàng)以及構(gòu)建后端（即構(gòu)建工具）。
  • requires: 列出了構(gòu)建這個(gè)項(xiàng)目所需的 Python 包。在執(zhí)行 pip install . 時(shí)，pip 會(huì)確保這些包已經(jīng)安裝。如果這些包沒(méi)有安裝，pip 會(huì)首先安裝這些依賴。
  • build-backend: 指定構(gòu)建項(xiàng)目所使用的后端工具，比如 setuptools.build_meta 或 poetry.core.masonry.api。pip 會(huì)調(diào)用這個(gè)工具來(lái)構(gòu)建項(xiàng)目。

3. 構(gòu)建源分發(fā)包（SDist）和/或輪子包（Wheel）

• 一旦 pip 安裝了構(gòu)建所需的依賴并加載了構(gòu)建后端，構(gòu)建后端會(huì)被調(diào)用來(lái)生成源分發(fā)包（SDist）和/或輪子包（Wheel）。
  • 如果使用 setuptools.build_meta，它會(huì)讀取項(xiàng)目的 setup.py 或 setup.cfg 文件來(lái)指導(dǎo)包的構(gòu)建。
  • 這些構(gòu)建輸出會(huì)保存在臨時(shí)目錄中，用于接下來(lái)的安裝步驟。

4. 安裝項(xiàng)目

• pip 使用生成的包（SDist 或 Wheel）安裝項(xiàng)目到目標(biāo)環(huán)境中（通常是當(dāng)前 Python 環(huán)境）。
• 如果項(xiàng)目依賴其他包，pip 會(huì)從 pyproject.toml 或 setup.py 中的 install_requires 列表中識(shí)別并安裝這些依賴。

5. 其他工具配置

• pyproject.toml 中的其他部分，如 [tool.ruff]，可能會(huì)被相應(yīng)的工具在構(gòu)建或開(kāi)發(fā)過(guò)程中引用。雖然這些部分不會(huì)直接影響 pip install . 的過(guò)程，但它們?cè)陂_(kāi)發(fā)環(huán)境中依然重要。

簡(jiǎn)化的執(zhí)行流程

• pip 檢查并加載 pyproject.toml 文件。
• 解析 build-system，安裝構(gòu)建所需的依賴。
• 使用指定的構(gòu)建后端構(gòu)建項(xiàng)目（生成 SDist 和/或 Wheel）。
• 安裝生成的包及其依賴。

總結(jié)

pyproject.toml 文件在 pip install . 的過(guò)程中會(huì)被 pip 引用，以確定如何構(gòu)建和安裝項(xiàng)目。pip 主要使用其中的 [build-system] 部分來(lái)加載構(gòu)建工具和依賴，然后調(diào)用這些工具生成項(xiàng)目的分發(fā)包，并最終將其安裝到當(dāng)前環(huán)境中。

到此這篇關(guān)于python庫(kù)構(gòu)建之pyproject.toml配置文件詳解的文章就介紹到這了,更多相關(guān)python庫(kù)構(gòu)建pyproject.toml內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評(píng)論