如何自动识别可通过TYPE_CHECKING优化的仅类型提示导入？

核心检查工具 #

• Mypy 原生检查
  直接运行 mypy --warn-unused-imports，Mypy会精准标记出仅在类型注解上下文使用的导入。这些就是适合用if TYPE_CHECKING:包裹的对象。确保你的Mypy配置中warn_unused_imports设为True（默认在严格模式下启用）。

• Pyright 类型检查
  运行pyright后，输出中会出现类似"Import is only used in type annotations"的提示，这类导入即为候选目标。Pyright的类型分析对复杂场景的识别准确率很高。

自动迁移工具 #

• Ruff 自动修复
  Ruff的UP035规则专门处理这类场景：

  1. 安装Ruff后，执行 ruff check --fix --select UP035
  2. 它会自动识别仅用于类型提示的导入，将其包裹到if TYPE_CHECKING:代码块中，还会自动导入from typing import TYPE_CHECKING（如果模块中没有的话）

• Autoflake + Mypy 配合清理
  先用autoflake --remove-all-unused-imports --ignore-init-module-imports清理完全未被使用的导入，再用Mypy标记出类型专用导入，手动或结合脚本完成迁移。

注意事项 #

• 避免误迁移同时用于运行时和类型提示的导入（比如from typing import Union既做注解又在运行时逻辑中使用），工具会自动排除这类情况，但建议处理后重新跑一遍类型检查和单元测试。
• 对__init__.py中的导入要谨慎，防止破坏模块的导出结构。
• 处理大型库时，建议分模块逐步操作，避免一次性修改过多代码导致难以排查问题。

内容的提问来源于stack exchange，提问作者JonFitt