从Mypy迁移到Pyrefly的完整指南

前言

Pyrefly是一个新兴的Python静态类型检查工具，由Facebook团队开发。它旨在提供比Mypy更快的类型检查速度和更友好的用户体验。本文将详细介绍如何将现有项目从Mypy迁移到Pyrefly，包括配置迁移、命令差异和错误处理等方面的内容。

Pyrefly基础使用

Pyrefly的使用方式与Mypy非常相似，基本命令格式如下：

pyrefly check 文件1.py 文件2.py

在项目根目录下运行以下命令可以检查整个项目：

cd 项目目录
pyrefly check

Pyrefly设计时就考虑了合理的默认配置，许多项目可能不需要额外配置就能直接使用。但对于已有Mypy配置的项目，我们提供了便捷的迁移工具。

配置迁移

自动迁移工具

Pyrefly提供了自动迁移配置的工具：

pyrefly init 项目路径

这个命令会：

1. 查找项目中的mypy.ini或pyproject.toml(包含tool.mypy部分)
2. 将其转换为pyrefly.toml或pyproject.toml中的[tool.pyrefly]部分
3. 尽可能保留原有配置选项

虽然迁移工具会尽力保持配置的等效性，但由于两个工具的实现差异，建议检查生成的配置文件是否有需要调整的地方。

关键配置选项转换

以下配置选项可以让Pyrefly的行为更接近Mypy：

# 忽略推断的返回类型，未指定时使用Any
untyped_def_behavior = "check-and-infer-return-any"

# 支持基于`mypy: ignore`和`mypy: ignore-errors`注释的忽略
permissive-ignores = true

配置迁移细节

1. 文件包含规则：

   • Mypy的files、modules和packages会被合并为Pyrefly的project_includes
   • 对于files和packages行为完全一致
   • Mypy不会递归检查modules，但Pyrefly会

2. 排除规则：

   • Mypy的exclude正则表达式会被转换为Pyrefly的project_excludes文件路径glob模式
   • 例如some/file.py|exclude_dir/会转换为["**/some/file.py", "**/exclude_dir/"]

3. 导入处理：

   • ignore_missing_imports会被转换为replace_imports_with_any
   • follow_imports = "skip"的处理方式保持不变
   • follow_untyped_imports选项在Pyrefly中对应全局的use_untyped_imports

错误处理与抑制

错误代码映射

Pyrefly将Mypy的错误代码映射到自己的错误类型系统。虽然并非所有错误代码都有完全对应的错误类型，但Pyrefly会尽量保持与Mypy相同的错误抑制行为。

常见映射关系：

Mypy错误代码	Pyrefly错误类型
attr-defined	missing-attribute
union-attr	missing-attribute

错误抑制方法

Pyrefly提供了多种错误抑制方式：

1. 行级抑制：

   # pyrefly: ignore
   x: str = 1
   

   或针对特定错误类型：

   # pyrefly: ignore[bad-assignment]
   x: str = 1
   

2. 全局抑制： 在配置文件中禁用特定错误类型：

   [errors]
   import-error = false
   

模块级配置

Mypy的模块级配置允许为匹配特定模式的模块设置不同的配置选项。Pyrefly的子配置机制提供了类似功能，但支持更少的选项。在迁移过程中，只有disable_error_code和enable_error_code会被保留。

迁移建议

1. 分阶段迁移：可以先在CI中并行运行Mypy和Pyrefly，逐步调整配置
2. 检查关键差异：特别注意类型推断和行为差异
3. 利用自动化工具：使用pyrefly init生成初始配置，再手动调整
4. 错误处理审查：检查错误抑制是否按预期工作

总结

从Mypy迁移到Pyrefly是一个相对平滑的过程，得益于Pyrefly提供的自动迁移工具和相似的设计理念。通过本文介绍的迁移方法和注意事项，开发者可以高效地完成迁移工作，享受Pyrefly带来的性能提升和使用体验改进。

对于复杂的项目，建议在迁移后进行全面测试，确保类型检查行为符合预期。随着Pyrefly的不断发展，未来将提供更多与Mypy兼容的功能和更完善的迁移支持。