企业官网建设流程全解析

Pyrefly v1.3 深度解析：更灵活的错误配置、可组合的张量形状 DSL 与 Polars 模式检查

【免费下载链接】pyreflyA fast type checker and language server for Python项目地址: https://gitcode.com/GitHub_Trending/py/pyrefly

Pyrefly 是一个快速的开源 Python 类型检查器与语言服务器。本文以官方 v1.3 发布说明（website/blog/2026-09-10-v1.3.md）为主线，结合仓库源码与配套文档，系统讲解 v1.3 引入的错误抑制与基线（Baseline）配置体系、全新的可组合张量形状类型级 DSL、Polars DataFrame 模式检查，以及一批新的类型检查诊断。读完本文，你将能够用更细粒度的# type: ignore[pyrefly:...]注释、可维护的 baseline 文件和--prune-baseline/--error-stale-baseline命令管理存量错误，并了解如何在 JAX / NumPy / PyTorch 与 Polars 项目中启用实验性的形状与模式检查能力。

pip install --upgrade pyrefly==1.3.0

配置与 CLI：更精细的错误抑制

1. Pyrefly 专属的# type: ignore标签

v1.3 之前，# type: ignore是一刀切的整行屏蔽。现在 Pyrefly 支持在标准的# type: ignore[...]注释中书写带pyrefly:前缀的专属错误码，只压制命名的那一条 Pyrefly 诊断，而同行的其他错误照常报告：

value: str = 0 # type: ignore[pyrefly:bad-assignment]

这种"命名式压制"的实现位于 crates/pyrefly_python/src/ignore.rs：解析器会把注释拆成(tool, kind)二元组，Tool::Type分支下，凡是pyrefly:开头的 code 都与实际诊断的错误码逐一比对，只有命中才产生SuppressionEffect::Suppress。换言之，# type: ignore[pyrefly:bad-return]出现在一个bad-assignment错误所在行时不会把它压掉，见源码中的单元测试test_type_ignore_specific_codes_require_pyrefly_prefix。

同一注释里可以混合书写多个 code，例如# type: ignore[assignment, pyrefly:bad-assignment]；若其中存在非pyrefly:前缀的 code（如 mypy 风格的assignment），其处理方式取决于下面的新配置项。此外，文件级# pyrefly: ignore-errors[code]指令仍受"必须位于文件开头代码之前"的约束，被误放时 Pyrefly 会报告misplaced-ignore警告（详见 website/docs/error-suppressions.mdx）。

2. 新增配置：type-ignore-unknown-tag-behavior

当# type: ignore[...]中出现了属于其他类型检查器（mypy、Pyright、Pyre、ty 等）的未知标签时，Pyrefly 如何处理？v1.3 用type-ignore-unknown-tag-behavior配置项来回答这个问题。从 crates/pyrefly_python/src/ignore.rs 中的TypeIgnoreUnknownTagBehavior枚举可以看出共有三个取值：

SuppressionEffect的Ord推导（None < DowngradeToWarning < Suppress）是承重的：多个压制同时命中时用.max()取最强效果。这在迁移期很实用——例如团队从 mypy 迁到 Pyrefly，代码里残留大量# type: ignore[assignment]时，先用downgrade-to-warning让它们不再隐藏新工具的错误，同时不阻塞 CI 绿灯。

3. Baseline 文件：集中管理存量错误

Baseline 是"集中压制存量错误"的机制：把当前所有错误快照进一个 JSON 文件，之后只有新增错误会被报告。它适合第一次给大项目引入类型检查、或需要批量压制错误时使用，也是从 mypy、Pyright 迁移大型代码库的推荐起点。

生成与使用：

# 生成（或重新生成）baseline 文件 pyrefly check --baseline="<path to baseline file>" --update-baseline # 携带 baseline 检查，只报告新增错误 pyrefly check --baseline="<path to baseline file>"

也可以在配置文件中声明 baseline 路径（baseline是项目级设置，不能在 sub-config 中覆盖）：

# pyrefly.toml baseline = "baseline.json"

# pyproject.toml [tool.pyrefly] baseline = "baseline.json"

配置文件声明后，每次调用无需再传--baseline；若同时给出，CLI 标志优先。注意：--update-baseline、--prune-baseline、--error-stale-baseline三者互斥，且都必须有 baseline 路径（来自 CLI 或配置）。仓库中的端到端测试见 test/baseline.md，覆盖了"配置缺失字段时报错并提示重跑--update-baseline"、"缺失文件时--prune-baseline报错而非静默通过"等边界场景。

baseline-matching-mode：按列还是按描述匹配

• "column"（默认）：按文件、错误 kind 和起始列匹配。
• "concise-description"：按文件、错误 kind 和精简描述匹配。

后者在代码换行、插入无关代码导致列号漂移时依然能命中，从而减少 baseline 的无效 churn（crates/pyrefly_config/src/config.rs 中默认值为BaselineMatchingMode::Column）。

baseline-format：full 还是 minimal

• "full"（默认）：写入全部基线元数据（path、name、column、concise_description、severity）。
• "minimal"：只写文件、错误 kind 以及匹配模式所需的最小字段（column模式即["column","name","path"]）。

两个设置都是仅配置项（configuration-only），保证所有用户对检入的 baseline 文件有一致的解释与更新方式：

baseline = "baseline.json" baseline-matching-mode = "concise-description" baseline-format = "minimal"

baseline-error-level：让匹配到的错误"可见"

默认ignore会从 CLI 输出中省略被 baseline 匹配的错误；设为info/warn/error后，匹配项会以（可能降低后的）严重级别重新出现，且带来源标记：文本输出追加[baselined]，JSON 输出在结果上置"baselined": true，SARIF 输出则把baselineState设为unchanged（未匹配的为new）。注意baseline-error-level不会把某个 finding 的严重级别提高到超过其原始级别（test/baseline.md 中有对应验证）。

baseline = "baseline.json" baseline-error-level = "warn"

让 baseline 保持新鲜：prune 与 CI 拒绝

随着错误被修复，baseline 中的条目会过时（stale）。v1.3 提供了两个方向相反的维护命令：

# 只删除过时条目，绝不记录新错误（保守策略：即使 --min-severity 隐藏了某诊断，只要它仍发生就不删） pyrefly check --prune-baseline # CI 用：一旦 baseline 含过时条目就以非零状态退出 pyrefly check --error-stale-baseline

两者的判定都基于本次检查的作用域：被检查的文件中不再出现该错误、或文件确认已不存在，则条目视为 stale；被收窄检查范围之外的文件条目会被保留。baseline 文件无法读取、解析失败或缺少匹配模式所需字段时，检查会失败而不是静默放行——这正是"基线必须可信"的设计意图（对应测试见 test/baseline.md 的A baseline that cannot be parsed fails instead of silently passing）。

4. 无类型三方依赖的处理：replace-untyped-imports-with-any

mypy 用follow_untyped_imports决定是否跟进无类型模块；Pyrefly v1.3 用新选项replace-untyped-imports-with-any实现等价控制。它把匹配指定 ModuleGlob 的已安装三方包，在没有 stub 包、也没有py.typed标记时替换为typing.Any。判定"无类型"时不考虑 Pyrefly 自带的 bundled stubs（即项目仍然受益于内置 stub）。

# pyrefly.toml replace-untyped-imports-with-any = []

• 类型：regex 列表；默认[]
• CLI 等价：--replace-untyped-imports-with-any
• mypy 对应：follow_untyped_imports = false；["*"]表示对每个模块生效
• 迁移：pyrefly init会自动把 mypy 的全局与 per-modulefollow_untyped_imports翻译成新选项（见 website/docs/configuration.mdx）

配合pyrefly init的自动翻译，从 mypy 迁移时无需手写这份映射。

张量形状：从装饰器到可组合的类型级 DSL

1. V2 DSL 取代@shaped_array

张量形状检查在 v1.3 中依然是实验特性，但其底层机制发生了根本变化：JAX、NumPy、PyTorch 的 stub 不再使用旧的@shaped_array装饰器（V1），而是迁移到一个可组合的、直接写在类型签名里的"类型级 DSL"（V2）。旧 API 已被移除，自定义形状注解必须迁移到IntTuple泛型类与 V2 DSL。

这套 DSL 建立在两个扩展之上（详见 website/docs/tensor-shapes.mdx）：

1. 核心类型系统中的符号整数运算：Tensor[[B, C, H, W]]这样的注解允许在类型层面做D // NHead之类的算术。
2. 算子的形状变换规范：一套形状规则库告诉 Pyrefly 每个算子如何变换形状。

Int[X]把运行时整数值桥接到类型层——当x: Tensor[[3, 4]]时，x.shape的类型是tuple[Int[3], Int[4]]，可以直接抽取维度构造新张量；a: Int[3]与b: Int[4]相乘得到Int[12]。泛型参数则用于书写形状多态模块：

class Linear[N: IntVar, M: IntVar]: def __init__(self, n: Int[N], m: Int[M]): ... def forwardXs: IntTuple -> Tensor[[*Elements[Xs], M]]: ... linear: Linear[3, 4] = Linear(3, 4) inp: Tensor[[2, 5, 3]] = ... x: Tensor[[2, 5, 4]] = linear(inp)

对reshape、cat、F.interpolate这类形状逻辑复杂的算子，Pyrefly 用小型 DSL 在 stub 内部描述变换，从而可以在不触碰 Pyrefly 内部实现的情况下扩展新算子的形状覆盖。

2. 形状感知的 JAX 与 NumPy stub

v1.3 大幅扩展了形状感知的 JAX stub，覆盖数组创建、索引、归约、搜索与排序、FFT、线性代数、einsum 等收缩运算以及jax.lax的大部分内容；同时新发布的pyrefly-numpy-stubs包把同样风格的形状检查带到 NumPy，与既有的 PyTorch 支持并列。这些 stub 与测试可以在仓库的 tensor-shapes/ 目录下找到：

• tensor-shapes/pyrefly-jax-stubs/
• tensor-shapes/pyrefly-numpy-stubs/
• tensor-shapes/pyrefly-torch-stubs/

各包均带pyproject.toml、pyrefly.toml与测试套件（suites.py、run_pyrefly.py），可独立运行验证。

实验性提醒：该 API 仍处于实验阶段，随着覆盖范围扩大与真实世界使用经验的积累，后续版本可能继续演进。最新 API 以 website/docs/tensor-shapes.mdx 与配套的 Reference 页面（website/docs/tensor-shapes-reference.mdx）为准。

DataFrame 模式检查：用Annotated约束 Polars Schema

v1.3 让 Pyrefly 能够在常见的 DataFrame 变换中追踪 Polars schema，并通过 PEP 593 的Annotated元数据强制 schema 契约：

from typing import Annotated import polars as pl class ReportSchema: name: pl.String score: pl.Int64 Report = Annotated[pl.DataFrame, ReportSchema] def publish(report: Report) -> None: ... publish(pl.DataFrame({"name": ["Ada"], "score": [98]})) # OK publish(pl.DataFrame({"name": ["Ada"]})) # Error: missing `score`

从 release_notes/release-notes-v1.3.0.md 的细节看，Polars 分析现在能追踪构造、select、with_columns、group_by().agg()、join、CSV 读取器以及 lazy/eager 转换过程中的 schema，并支持类型化Series、嵌套与自有（owned）dtype，以及从变量、调用和TypedDict中提取 schema 信息。配合新增的column-schema-mismatch与duplicate-column诊断，可以在运行时之前就捕获非法 schema 与冲突的输出列。

此外，pandas DataFrame 通过columns=构造时，现在会把推断出的 schema 投影到请求的列集合与列顺序上。与张量形状一样，DataFrame schema 检查也是实验特性，支持的操作与库会随反馈逐步增加。

其他类型检查改进：五类新诊断

v1.3 为"能活到运行时才爆雷"的错误新增了诊断，全部记录在 website/docs/error-kinds.mdx 中：

非法正则表达式：regex

Pyrefly 现在会静态检查字面量正则的语法错误与无意中的捕获组：

import re re.compile("(") # missing ), unterminated subpattern [regex]

非法的 patch 目标：missing-attribute-patch-target

传给unittest.mock.patch的字符串若指向不存在的属性，会收到警告（默认严重级别warn）：

from unittest import mock @mock.patch("dep.nonexistent_attr") # missing-attribute-patch-target def f(): ...

它是missing-attribute的子类，压制父类诊断时本诊断同样被压制。

Dataclass 问题：bad-dataclass-descriptor与dataclass_transform检查

数据描述符（同时定义了__set__/__delete__）会优先于实例字典，因此作为 dataclass 字段时读走__get__、写走__set__，两侧类型必须一致：

from dataclasses import dataclass class Desc: def __get__(self, obj, cls) -> int: ... def __set__(self, obj, value: str) -> None: ... @dataclass class C: x: Desc = Desc() # `__get__` 返回 int，而 `__set__` 接收 str [bad-dataclass-descriptor]

同时，Pyrefly 会报告不支持的dataclass_transform参数。

非法协议实现：Protocol.__call__覆写检测

不兼容的Protocol.__call__覆写现在会被检出。

开放类型上的穷尽匹配：non-exhaustive-match-open-type

默认情况下 Pyrefly 只对有限集合做 match 穷尽性检查。新错误类让项目可以选择对所有类型开启穷尽性检查——包括int、str、object等开放主题类型：

non-exhaustive-match-open-type

该错误默认严重级别为ignore（即默认不启用），是non-exhaustive-match的子类，配置或压制父类时同样生效。模式匹配穷尽性、重载选择、窄化与泛型推断的精度在 v1.3 中都有所提升（例如元组主题与 union 开放类型的穷尽性检查）。

更多亮点：LSP、性能与迁移工具

语言服务器

• 工作区符号搜索：现在覆盖方法、嵌套类、嵌套函数与类属性，即使在未打开的文件中也能搜到；跨文件调用层级、类型层级与查找引用无需预先打开相关文件。
• 新的重构与快速修复：Change Signature 重构同步更新函数签名与其调用点；新增"移除未使用 import"与"插入assert x is not None"快速修复；inlay hints 可以插入所需 import、支持点击跳转。
• 编辑器集成：LSP 客户端可在初始化时提供extraSearchPaths与extraProjectExcludes；自定义pyrefly.lspPath现正确支持 Windows、home 相对与 workspace 相对路径。

性能

• TSP 复用未打开文件的分析结果：在一次捕获的 Pylance 会话中，22,294 个未打开文件的getComputedType请求耗时从 668 秒降到 3.4 秒，总请求时间从 671 秒降到 6.4 秒。
• 超大作用域文件中"未知名称建议"显著提速：Pyrefly 会跳过注定被丢弃的诊断的建议工作，并在计算完整编辑距离前拒绝不可能的候选。

升级存量代码库的推荐流程

升级 Pyrefly 或第三方库版本会暴露新的类型错误，一次性修完往往不现实。官方推荐的四步流程（详见 website/docs/error-suppressions.mdx）：

# 1. 自动为所有错误添加抑制注释 pyrefly suppress # 2. 运行你惯用的格式化工具 # 3. 清理不再需要的抑制注释 pyrefly suppress --remove-unused # 4. 重复直至格式化与类型检查双双干净

其中pyrefly suppress等价于pyrefly check --suppress-errors；若项目里还有其他工具在错误前一行放抑制注释，可用pyrefly suppress --comment-location=same-line让 Pyrefly 的注释改为放在错误行尾，避免注释冲突。

总结与后续方向

Pyrefly v1.3 的主题是"可配置、可组合、可维护"：# type: ignore[pyrefly:...]与type-ignore-unknown-tag-behavior让错误压制从"整行开关"细化为"单条诊断开关"；baseline 的四项新配置与两个新 CLI 标志让存量错误管理进入 CI 可审计、可自动修剪的工程化阶段；replace-untyped-imports-with-any配合pyrefly init打通了 mypy 迁移的最后一段路。实验特性方面，张量形状从装饰器 API 彻底转向可组合的类型级 DSL，并把覆盖从 PyTorch 扩展到 JAX 与 NumPy；Polars DataFrame schema 检查则用Annotated把 schema 契约带入了静态检查。

v1.4 及以后，官方计划继续在减少误报、提升性能与拓宽库支持上发力，同时根据早期采用者的反馈持续打磨张量形状与 DataFrame schema 检查。如果想深入了解某项能力，仓库内的 website/docs/error-suppressions.mdx、website/docs/error-kinds.mdx、website/docs/tensor-shapes.mdx、website/docs/configuration.mdx 以及 test/baseline.md 提供了完整的参考与可运行验证。

【免费下载链接】pyreflyA fast type checker and language server for Python项目地址: https://gitcode.com/GitHub_Trending/py/pyrefly