前言

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

主要用途

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

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

• 項目元數據：

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

• 依賴管理：

  • 該文件可以管理項目的依賴關系，包括運行時依賴、開發(fā)時依賴等，類似于 requirements.txt，但更加結構化和靈活。

• 配置構建工具的行為：

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

文件結構

一個典型的 pyproject.toml 文件由幾個部分組成，每個部分對應不同的功能和配置信息。以下是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"

這個 pyproject.toml 文件配置了項目的構建系統(tǒng)以及使用 ruff 進行代碼檢查和格式化的相關設置。以下是各部分的詳細解釋：

1. [build-system]

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

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

2. [tool.ruff]

• target-version: 指定了代碼的目標 Python 版本，這里是 Python 3.8 (py38)。ruff 將根據這個版本進行相應的檢查和優(yōu)化。

• line-length: 指定了代碼行的最大長度，超過這個長度會被視為格式錯誤。這里設置為 119 個字符。

• indent-width: 指定代碼縮進的寬度，這里設置為 4 個空格。

3. [tool.ruff.lint]

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

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

4. [tool.ruff.lint.isort]

• lines-after-imports: 指定在導入語句之后應保留的空行數，這里設置為 2 行。

• known-first-party: 列出了項目中的第一方模塊，即 llamafactory，用于在導入排序時識別項目內部的模塊。

• known-third-party: 列出了已知的第三方庫，這些庫將在導入排序時與其他模塊區(qū)分開來。

5. [tool.ruff.format]

• quote-style: 指定字符串使用的引號樣式，這里設置為 double，即雙引號。

• indent-style: 指定縮進風格，這里使用 space（空格）而非 tab。

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

• skip-magic-trailing-comma: 設置為 false，意味著即使添加魔術尾逗號（magic trailing comma），也不會跳過格式化。

• line-ending: 設置為 auto，表示根據操作系統(tǒng)的默認設置自動選擇行結尾符。

小結

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

工作流程

在執(zhí)行 pip install . 時，pyproject.toml 文件會在構建和安裝 Python 項目的過程中被引用。具體流程如下：

1. 識別 pyproject.toml 文件

• 當你在項目的根目錄執(zhí)行 pip install . 命令時，pip 會首先檢查該目錄下是否存在 pyproject.toml 文件。
• 如果存在這個文件，pip 會將其視為該項目的構建配置文件，并按照其中的內容來指導接下來的構建過程。

2. 解析 build-system 部分

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

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

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

4. 安裝項目

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

5. 其他工具配置

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

簡化的執(zhí)行流程

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

總結

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

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

最新評論