Ruff 0.11.x 版本演进全解析：Python 版本推断新机制、PGH004 稳定化与 Compile-time Syntax Errors 体系

Ruff 0.11.x 版本演进全解析Python 版本推断新机制、PGH004 稳定化与 Compile-time Syntax Errors 体系【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff本文围绕 Ruff 官方变更记录 changelogs/0.11.x.md 展开完整覆盖 0.11.0 至 0.11.13 共 14 个版本的核心变更。读完本文你将掌握 0.11.0 中requires-python推断这一破坏性变更的确切语义与源码实现、PGH004稳定化后的检测范围以及贯穿整个 0.11.x 系列的 compile-time syntax errors编译期语法错误检测体系是如何逐版本铺开的并了解--exit-non-zero-on-format等 CLI 新选项的实际行为。0.11.0 的由来一次发布流程修正0.11.0 并不是一个常规的迭代版本而是对 0.10.0 的补发follow-up release。变更记录开篇明确说明由于发布流程中的一个失误requires-python推断相关的变更没有包含进 0.10.0因此 Ruff 0.11.0 补上了这一变更同时完成了PGH004preview 行为的稳定化。也就是说升级 0.11.0 时实际引入的“新行为”有两块Python 版本推断机制的变更破坏性变更与blanket-noqa检测范围的扩大。破坏性变更target-version缺失时的版本推断在此之前指定 Python 版本只有两条途径在ruff.toml或pyproject.toml的[tool.ruff]段中显式配置target-version在带有[tool.ruff]段的pyproject.toml中依赖project.requires-python字段。问题出在 Ruff 的配置发现机制上一个不含[tool.ruff]段的pyproject.toml会被整个忽略其中的requires-python也随之被忽略Ruff 会回退到默认 Python 版本记录写作时为 3.9——当你明明声明了目标版本时这个行为出人意料。0.11.0 更新后的配置发现规则如下变更记录原文列出三条当前 docs/configuration.md 中“Inferring the Python version”一节的完整表述为四条如果直接传入了配置文件Ruff 不会尝试推断缺失的target-version如果在文件系统层级中发现配置文件如ruff.toml没有target-versionRuff 会检查同一目录下的pyproject.toml并尊重其requires-python字段——即使该文件不含[tool.ruff]段如果使用用户级配置user-level configuration则取父目录中最近的pyproject.toml的requires-python字段优先如果被检查文件所在目录没有任何配置文件ruff.toml或带[tool.ruff]段的pyproject.tomlRuff 会向上查找最近的pyproject.toml并使用其requires-python。源码实现apply_fallbacks与回退版本推导从源码结构看这套逻辑的落点在ruff_workspacecrateconfiguration.rs 中的apply_fallbacks方法当配置来源为ConfigurationOrigin::Ancestor即从父目录层级发现且target_version为空时调用pyproject::find_fallback_target_version(dir)推导回退版本pyproject.rs 中的find_fallback_target_version沿路径祖先目录逐级查找找到第一个含requires-python的pyproject.toml即返回关键的版本提取逻辑在 pyproject.rs 的get_minimum_supported_version它从VersionSpecifiers中只筛选、、~、、等下界类操作符取各操作数版本截断到 major.minor 后的最小值再映射到PythonVersion枚举。例如requires-python 3.13会推导出py313。需要注意的细节load_optionspyproject.rs在解析pyproject.toml时如果其中已显式给出target_version则显式配置优先不会再去读requires-python。也就是说target-version依旧是“细粒度控制”的第一选择推断只作为兜底。PGH004blanket-noqa稳定化blanket-noqa规则PGH004在 0.11.0 稳定化行为变化是同时检测文件级的 blanket noqa 注释而不仅仅是行级注释。即# noqa整行/整文件地关闭所有规则的行为现在也会被告警。配合 0.11.5 中RUF100对“带具体规则码的未使用文件级noqa指令”的检测修复0.11.x 系列对 noqa 卫生管理的整体覆盖明显增强。贯穿系列的 Preview 主线compile-time syntax errors0.11.x 系列最具系统性的一条线索是[syntax-errors]类别的 preview 功能——把 CPython 在编译期才会报错的语法问题前移到 lint 阶段检测。按版本梳理其演进0.11.1一批针对“低版本 Python 使用高版本语法”的检测先行落地包括 PEP 701 f-string 在 Python 3.12 之前、括号化上下文管理器PEP 634/614 相关在 3.9 之前、星号注解PEP 646在 3.11 之前、for语句迭代子句中的元组解包在 3.9 之前等同时改进了 pre-PEP-614 装饰器语法错误的消息与范围range0.11.2修复 3.11 之前可变参数variadic注解上的误报0.11.3正式宣布Start detecting compile-time syntax errors开始检测编译期语法错误并补充 match 模式相关问题映射模式重复键、类模式重复属性、case模式中多重赋值等、__debug__赋值/删除检测0.11.4补充注解annotations中的非法语法检测、match模式中的重复键/属性同期还实现了RUF102invalid-rule-code0.11.5将注解检查扩展到await表达式与带注解赋值新增同步推导式中出现异步推导式的检测0.11.8新增模块级nonlocal声明、单星号赋值x *y检测并将“未加括号的 except 元组”语法错误限定为 3.14 之前的行为0.11.9两项关键调整——版本相关的语法错误默认按最新受支持 Python 版本判定以及为 Python 3.14 实现 deferred annotations0.11.13其他变更parser 与 formatter 双双支持 Python 3.14 的 t-strings模板字符串。这条线索的意义在于Ruff 的 Rust 解析器在解析成功之后还维护了一套semantic_errors检查层可参见 ruff_python_parser 与 error.rs 的目录结构0.11.x 系列把它逐步暴露为可启用的 preview 诊断让“这份代码在目标 Python 版本下根本编译不过”的问题在 lint 阶段即可被捕获。由于均处于 preview 状态启用方式是在配置或 CLI 中开启preview模式正式稳定化前的行为仍可能调整。值得逐条关注的规则与修复变更Airflow 规则AIR3xx的大规模演进flake8-airflow插件是 0.11.x 中改动最密集的插件核心是 Airflow 3 的模块迁移检测AIR301/AIR302等从 0.11.1 起陆续补充chain、chain_linear、cross_downstream检测0.11.3 引入AIR312拆分、规则编号多次迁移AIR301→AIR002、AIR302→AIR301、AIR303→AIR302等使用这些编码时注意版本差异0.11.10–0.11.13 则持续补全 autofix含针对 Airflow 3 中重命名场景的不安全修复并扩展到单个符号级别的模块路径检查。如果你的项目依赖 Airflow 且使用这些规则升级时应留意规则码映射变化。CLI--exit-non-zero-on-format0.11.1这是一个 CI 场景下很实用的新选项只要格式化实际修改了任何文件即使全部文件都格式化成功ruff format也返回非零退出码。实现位于 args.rs定义为FormatCommand的布尔参数并带有历史别名--exit-non-zero-on-fix。其典型用法是让 CI 以“检查失败”的方式守护格式一致性而不是静默修改工作区。配置与 CLI 的其他新增0.11.3stdin 传入的pyproject.toml现在能被正确解析检查此前作为普通文本处理会导致误判flake8-import-conventions的默认别名新增numpy.typing as npt0.11.8新增禁用typing_extensions相关导入建议的选项对应 configuration.rs 中LintConfiguration的typing_extensions字段0.11.9 还修复了该设置缺少combine调用的 bug配置选项中新增 Python 3.14target-version可用py3140.11.9ruff analyze graph允许传入虚拟环境。规则行为变更与自动修复安全性收紧0.11.x 系列体现了一个清晰的工程取向——把更多自动修复标记为“不安全unsafe”以避免破坏性变更例如0.11.7FURB161refurb修复除整数字面量与布尔量外一律不安全PLR1730在删除注释时不安全0.11.10PIE804在字典含注释时修复标记为不安全0.11.12/0.11.13UP010、UP004、UP050在删除注释时标记为不安全同期也有“放宽”方向0.11.7 中E712冗余布尔比较获得自动修复PERF401允许用推导式替换列表函数调用。若你的 CI 使用--fix而非--unsafe-fixes这些安全性调整直接影响修复覆盖面升级后值得对 diff 做一次抽查。代表性 bug 修复变更记录中篇幅最大的部分是 bug fixes其中几类修复模式值得关注文件描述符fd参数导致的误报0.11.8–0.11.10 集中修复了flake8-use-pathlib一族规则PTH104/PTH116/PTH123/PTH208等在函数参数是文件描述符时仍建议Path方法的误报0.11.10 进一步推广为“对所有带dir_fd参数的os.*函数抑制诊断”自动修复产生非法代码如SIM905的rsplit修复会产生反转的列表字面量0.11.10 修复、UP018修复丢失空格或括号0.11.7/0.11.9 修复、FURB129修复生成非法语法0.11.12 修复稳定性0.11.1 中 Server 端在有版本特定语法错误时允许FixAll操作0.11.3 中“从已删除目录运行 Ruff 时panic!”改为正常报错。升级建议如果从 0.10.x 或更早版本升级到 0.11.x首要关注的是未配置target-version的项目新推断机制可能改变 Ruff 实际使用的目标版本尤其是目录中存在pyproject.toml但无[tool.ruff]段、且声明了requires-python的场景从而改变部分版本相关规则如UP系列 pyupgrade 规则的触发行为。可用ruff check --show-settings查看解析后的target-version验证使用 Airflow 相关规则码的项目需对照 0.11.3 起的规则码迁移记录核对配置依赖ruff format退出码的 CI 脚本可考虑改用--exit-non-zero-on-format获得“有文件被改动即失败”的语义preview 相关的 syntax-errors 检测在整个 0.11.x 系列中持续变动且默认不启用建议在稳定化之前不要在非 preview 流程中依赖其输出。本系列变更记录的完整明细含全部 PR 编号见 changelogs/0.11.x.md版本推断的现行文档表述见 docs/configuration.md。【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考