Ruff 实战指南：全自动升级 typing 类型注解至 PEP 585 标准-Python教程-PHP中文网

Ruff 实战指南：全自动升级 typing 类型注解至 PEP 585 标准

本文详解如何使用 ruff 一键将 from typing import dict, list, optional 等旧式类型导入自动升级为 dict[str], list[int], int | none 等 pep 585/604 原生语法，并支持安全修复、版本适配与编辑器集成。

本文详解如何使用 ruff 一键将 from typing import dict, list, optional 等旧式类型导入自动升级为 dict[str], list[int], int | none 等 pep 585/604 原生语法，并支持安全修复、版本适配与编辑器集成。

Ruff 不仅是超快的 linter 和 formatter，更是 Python 类型现代化的“智能引擎”。自 Python 3.9 起，PEP 585 允许直接使用内置容器类型（如 list, dict, set）作为泛型，取代 typing.List, typing.Dict；PEP 604 则引入 | 作为联合类型操作符（替代 Union[T, U]）。这些变更大幅提升代码可读性与标准兼容性，而 Ruff 内置规则集可全自动完成迁移。

✅ 核心能力：UP 规则族精准处理类型升级

Ruff 提供专用于语法现代化的 UP（Upgrade）规则族，其中关键规则包括：

UP006: 将 typing.Dict[K, V] → dict[K, V]，typing.List[T] → list[T]，typing.Set[T] → set[T] 等
UP007: 将 typing.Optional[T] → T | None（需 Python ≥ 3.10）
UP013: 将 typing.Union[A, B] → A | B
UP032: 将 typing.Text → str（已废弃的别名）
UP040: 将 typing.AnyStr → 删除（推荐显式使用 str 或 bytes）

这些规则全部支持 --fix 自动修复，且严格遵循目标 Python 版本约束——例如 UP007 在 target-version = "py39" 下不会启用，避免降级兼容性问题。

?️ 三步完成项目级类型升级

第一步：配置 pyproject.toml（推荐标准格式）

在项目根目录创建或编辑 pyproject.toml，添加以下内容：

[tool.ruff]
target-version = "py310"  # 必须匹配项目实际运行版本（支持 py37–py314）
line-length = 88

[tool.ruff.lint]
select = ["UP006", "UP007", "UP013", "UP032", "UP040", "F401"]  # 启用类型升级 + 清理未使用导入
ignore = ["E501"]  # 可选：忽略行长警告（因泛型可能变长）

[tool.ruff.format]
quote-style = "double"
docstring-code-format = true  # 若文档字符串中含类型示例，建议开启

? 提示：F401（未使用导入）会自动移除 from typing import Dict, List 等已不再需要的导入语句，实现“零残留”清理。

Coda
Coda是一款AI办公效率工具，在线协作平台Coda推出的AI写作和文档助手，类似于Notion AI。

下载

第二步：执行自动修复

在终端运行：

# 预览变更（不修改文件）
ruff check --fix --diff .

# 执行修复（推荐先备份或提交当前分支）
ruff check --fix .

# 仅处理特定文件
ruff check --fix src/utils.py

Ruff 将智能识别上下文：
✅ 保留 typing 中仍需的类型（如 typing.TypeVar, typing.Protocol）
✅ 避免误改字符串字面量或注释中的 Dict
✅ 正确处理嵌套泛型（如 Dict[str, List[int]] → dict[str, list[int]]）
✅ 自动调整 Union 多重嵌套为链式 |（Union[A, Union[B, C]] → A | B | C）

第三步：VS Code 深度集成（保存即升级）

在工作区 settings.json 中添加：

{
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.fixAll.ruff": "explicit",
      "source.organizeImports.ruff": "explicit"
    }
  }
}

✅ 保存 .py 文件时，Ruff 将自动：

升级类型注解（UP 规则）
排序并清理导入（F401, I001）
格式化代码（缩进、换行、引号等）

⚠️ 注意事项：

确保 ruff CLI 已全局可用（pip install ruff），VS Code 终端能执行 ruff --version；

若使用 pyupgrade 作为补充工具（如需更激进的语法升级，如 f-string 转换），可与 Ruff 并行运行，但建议以 Ruff 为主——因其 UP 规则更稳定、版本感知更强；

对于大型项目，首次全量修复前建议启用 --diff 预览，并结合 Git 分步提交，便于人工复核关键类型逻辑。