本文旨在解決 ruff linter 自動(dòng)將 python 導(dǎo)入語(yǔ)句（特別是內(nèi)置類(lèi)型如 `pathlib.path`）移至 `if type_checking:` 塊，從而導(dǎo)致 pydantic 模型出現(xiàn) `forwardref` 配置錯(cuò)誤的問(wèn)題。通過(guò)詳細(xì)分析 ruff 的 `tch` 規(guī)則，并提供修改 `pyproject.toml` 配置文件的具體步驟，本教程將指導(dǎo)開(kāi)發(fā)者如何禁用或優(yōu)化此行為，確保類(lèi)型提示在運(yùn)行時(shí)正確解析，維護(hù)代碼的穩(wěn)定性和可預(yù)測(cè)性。

1. 引言：Ruff 導(dǎo)入重排引發(fā)的 Pydantic 問(wèn)題

Ruff 是一個(gè)高性能的 Python 代碼檢查器和格式化工具，它集成了多種 linting 規(guī)則，包括對(duì)導(dǎo)入語(yǔ)句的優(yōu)化。其中，flake8-type-checking 規(guī)則集（在 Ruff 中對(duì)應(yīng) TCH 前綴的規(guī)則）旨在將僅用于類(lèi)型檢查的導(dǎo)入語(yǔ)句移動(dòng)到 if TYPE_CHECKING: 代碼塊中。這種優(yōu)化在理論上可以減少運(yùn)行時(shí)不必要的導(dǎo)入開(kāi)銷(xiāo)，提高程序啟動(dòng)速度。

然而，對(duì)于某些依賴運(yùn)行時(shí)類(lèi)型信息的庫(kù)，如 Pydantic，這種自動(dòng)重排可能會(huì)導(dǎo)致意想不到的問(wèn)題?？紤]以下 Pydantic BaseModel 定義，其中使用了 pathlib.Path 作為類(lèi)型提示：

# 原始代碼
from pathlib import Path
from pydantic import BaseModel


class Model(BaseModel):
    log_file: Path

當(dāng) Ruff 啟用 TCH 規(guī)則并運(yùn)行時(shí)，它可能會(huì)將 from pathlib import Path 視為僅用于類(lèi)型檢查的導(dǎo)入，并將其移動(dòng)到 if TYPE_CHECKING: 塊中，導(dǎo)致代碼變?yōu)椋?/p>

# 經(jīng)過(guò) Ruff 重排后的代碼
from typing import TYPE_CHECKING
from pydantic import BaseModel

if TYPE_CHECKING:
    from pathlib import Path


class Model(BaseModel):
    log_file: Path

此時(shí)，如果嘗試實(shí)例化 Model 或進(jìn)行 Pydantic 模型的驗(yàn)證，就會(huì)遇到 pydantic.errors.ConfigError 錯(cuò)誤，提示 field "log_file" not yet prepared so type is still a ForwardRef, you might need to call Model.update_forward_refs()。這是因?yàn)樵谶\(yùn)行時(shí)，if TYPE_CHECKING: 塊內(nèi)的代碼不會(huì)被執(zhí)行，導(dǎo)致 Path 類(lèi)型在 Pydantic 模型定義時(shí)無(wú)法被正確解析，Pydantic 將其視為一個(gè)未解析的 ForwardRef。雖然 Pydantic 提供了 update_forward_refs() 方法來(lái)手動(dòng)解析這些引用，但在許多場(chǎng)景下，我們更希望避免這種手動(dòng)干預(yù)，并保持類(lèi)型提示的直接可用性。

立即學(xué)習(xí)“Python免費(fèi)學(xué)習(xí)筆記（深入）”；

2. 理解 Ruff 的 TCH 規(guī)則

Ruff 的 TCH 規(guī)則集源自 flake8-type-checking，旨在優(yōu)化 Python 項(xiàng)目中的類(lèi)型檢查導(dǎo)入。該規(guī)則集包含以下主要規(guī)則：

• TCH001: 將應(yīng)用程序內(nèi)部導(dǎo)入移入類(lèi)型檢查塊。
• TCH002: 將第三方庫(kù)導(dǎo)入移入類(lèi)型檢查塊。
• TCH003: 將內(nèi)置庫(kù)導(dǎo)入移入類(lèi)型檢查塊。

在上述 Pydantic 示例中，pathlib 是 Python 的標(biāo)準(zhǔn)庫(kù)模塊，因此 TCH003 規(guī)則很可能是導(dǎo)致 from pathlib import Path 被移動(dòng)的罪魁禍?zhǔn)?。Ruff 的默認(rèn)行為并非總是開(kāi)啟所有 TCH 規(guī)則，通常是當(dāng)用戶在 pyproject.toml 或其他配置中明確 select 了 TCH 或更寬泛的規(guī)則集時(shí)才會(huì)觸發(fā)。

3. 解決方案：禁用或優(yōu)化 TCH 規(guī)則

解決此問(wèn)題的最直接方法是在 Ruff 的配置中禁用或限制 TCH 規(guī)則。這通常通過(guò)修改項(xiàng)目的 pyproject.toml 文件來(lái)完成。

千面視頻動(dòng)捕

千面視頻動(dòng)捕是一個(gè)AI視頻動(dòng)捕解決方案，專(zhuān)注于將視頻中的人體關(guān)節(jié)二維信息轉(zhuǎn)化為三維模型動(dòng)作。

27

查看詳情

假設(shè)您的 pyproject.toml 文件中 Ruff 配置的 select 部分如下：

# pyproject.toml 原始配置片段
[tool.ruff]
line-length = 120
ignore = ["F405", "B008"]
select = ["E", "F", "B", "C4", "DTZ", "PTH", "TCH", "I001"] # 注意這里的 "TCH"
exclude = ["docs/conf.py", "Deployment/make_deployment_bundle.py"]

要阻止 Ruff 將導(dǎo)入移入 if TYPE_CHECKING: 塊，您需要從 select 列表中移除 "TCH"。修改后的配置應(yīng)如下所示：

# pyproject.toml 修改后的配置片段
[tool.ruff]
line-length = 120
ignore = ["F405", "B008"]
select = ["E", "F", "B", "C4", "DTZ", "PTH", "I001"] # 移除了 "TCH"
exclude = ["docs/conf.py", "Deployment/make_deployment_bundle.py"]

移除 "TCH" 后，Ruff 將不再應(yīng)用 flake8-type-checking 相關(guān)的規(guī)則，從而停止自動(dòng)將導(dǎo)入語(yǔ)句重排到 if TYPE_CHECKING: 塊中。這樣，pathlib.Path 等類(lèi)型在 Pydantic 模型定義時(shí)將始終可用，避免 ForwardRef 錯(cuò)誤。

4. 注意事項(xiàng)與最佳實(shí)踐

• 權(quán)衡利弊: 禁用 TCH 規(guī)則會(huì)失去 Ruff 在類(lèi)型檢查導(dǎo)入優(yōu)化方面帶來(lái)的潛在性能優(yōu)勢(shì)。在大多數(shù)應(yīng)用中，這種性能差異微乎其微。但對(duì)于極端注重啟動(dòng)性能且導(dǎo)入開(kāi)銷(xiāo)巨大的項(xiàng)目，可能需要仔細(xì)權(quán)衡。
• Pydantic 與運(yùn)行時(shí)類(lèi)型: Pydantic 模型的特性決定了它在運(yùn)行時(shí)需要訪問(wèn)類(lèi)型信息來(lái)執(zhí)行驗(yàn)證和序列化。因此，對(duì)于 Pydantic 模型中使用的類(lèi)型提示，通常不建議將其置于 if TYPE_CHECKING: 塊內(nèi)。
• 特定文件的忽略: 如果您只想在特定文件或目錄中禁用 TCH 規(guī)則，可以使用 [tool.ruff.per-file-ignores] 配置項(xiàng)，提供更細(xì)粒度的控制。例如：

  [tool.ruff.per-file-ignores]
  "models/*.py" = ["TCH"] # 僅在 models 目錄下的所有 .py 文件中忽略 TCH 規(guī)則

  登錄后復(fù)制

  這允許您在項(xiàng)目的大部分代碼中保留 TCH 規(guī)則的優(yōu)點(diǎn)，同時(shí)避免在關(guān)鍵區(qū)域（如 Pydantic 模型定義）中引發(fā)問(wèn)題。

• Ruff 版本: 隨著 Ruff 的不斷發(fā)展，其規(guī)則代碼和行為可能會(huì)有所調(diào)整。請(qǐng)確保查閱您所使用 Ruff 版本的官方文檔，以獲取最新的規(guī)則列表和配置指南。
• Pre-commit Hook: 如果您通過(guò) pre-commit 鉤子運(yùn)行 Ruff，請(qǐng)確保在修改 pyproject.toml 后，重新運(yùn)行 pre-commit install 或 pre-commit run --all-files 以驗(yàn)證更改是否生效。

5. 總結(jié)

Ruff 作為一款強(qiáng)大的 Python 代碼檢查工具，其導(dǎo)入優(yōu)化功能在某些情況下可能會(huì)與 Pydantic 等庫(kù)的運(yùn)行時(shí)類(lèi)型需求發(fā)生沖突。當(dāng)遇到 Ruff 自動(dòng)將導(dǎo)入移入 if TYPE_CHECKING: 塊導(dǎo)致 ForwardRef 錯(cuò)誤時(shí)，最有效的解決方案是審查并調(diào)整 pyproject.toml 文件中的 Ruff 配置，特別是從 select 列表中移除 TCH 規(guī)則。理解工具的行為并根據(jù)項(xiàng)目實(shí)際需求進(jìn)行合理配置，是維護(hù)代碼質(zhì)量和項(xiàng)目穩(wěn)定性的關(guān)鍵。

以上就是Python 項(xiàng)目中避免 Ruff 自動(dòng)將導(dǎo)入移至類(lèi)型檢查塊的指南的詳細(xì)內(nèi)容，更多請(qǐng)關(guān)注php中文網(wǎng)其它相關(guān)文章！