Ruff 0.10.x 变更日志深度解析TYPE_CHECKING 行为变化、统一 noqa 语法与规则稳定化清单【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff本文以 Ruff 仓库官方变更日志 changelogs/0.10.x.md 为主体完整梳理 0.10.0 版本的全部破坏性变更、规则弃用/重映射/稳定化清单以及 Server、配置、CLI 等周边变化并结合仓库源码核对关键变更的实际实现。读完本文你可以对 0.10 升级做出完整风险评估并按清单完成迁移。一、0.10.0 发布概览一项变更被推迟到 0.11.00.10.0 的官方说明将迁移指南与变更总览放在官方博客发布此处不转载外链仓库内的变更日志 changelogs/0.10.x.md 是核对细节的权威来源。有一个容易误判的点必须首先说明日志明确记载target-version未指定时的 Python 版本推断requires-pythoninference对应 PR #16319因发布流程失误并未包含在 0.10.0 中而是随 0.11.0 一起发布。如果你在评估 0.10.x 升级不要将这项变更计入影响面它的完整说明见 0.11.0 版本的日志changelogs/0.11.x.md。二、破坏性变更Breaking Changes变更日志开头特别提示除本节列出的破坏性变更外“Remapped rules”规则重映射一节也可能导致你的配置中某些规则被禁用迁移时需要一并检查。2.1TYPE_CHECKING识别行为更新PR #16669这是 0.10.0 对静态分析语义影响最大的一项变更之前Ruff 只识别判定typing.TYPE_CHECKING符号的 if 块现在Ruff 会识别任何名为TYPE_CHECKING的局部变量即使它并非来自typing模块同时移除了对遗留写法if 0:和if False:型 type-checking 块的识别官方建议统一改用局部TYPE_CHECKING变量。该行为在语义模型中的实现可以直接在源码中核对核心判定函数is_type_checking_block位于 analyze/typing.rs/// Return true if [ast::StmtIf] is a guard for a type-checking block. pub fn is_type_checking_block(stmt: ast::StmtIf, semantic: SemanticModel) - bool { let ast::StmtIf { test, .. } stmt; match test.as_ref() { // As long as the symbols name is TYPE_CHECKING we will treat it like typing.TYPE_CHECKING // for this specific check even if its defined somewhere else, like the current module. // Ex) if TYPE_CHECKING: Expr::Name(ast::ExprName { id, .. }) { // Ex) if TC: with from typing import TYPE_CHECKING as TC id TYPE_CHECKING || semantic.match_typing_expr(test, TYPE_CHECKING) } // Ex) if typing.TYPE_CHECKING: Expr::Attribute(ast::ExprAttribute { attr, .. }) attr TYPE_CHECKING, _ false, } }源码注释与实现证实了日志的描述只要测试表达式是一个名为TYPE_CHECKING的 Nameid TYPE_CHECKING即使它在本模块内被局部定义也会被当作 type-checking 块守卫typing.TYPE_CHECKING属性访问同样匹配。该判定由语义模型以位标志形式贯穿整个分析过程——SemanticModelFlags::TYPE_CHECKING_BLOCK定义在 model.rs 中并可通过in_type_checking_block()查询直接影响flake8-type-checkingTC 系列、F401等一组依赖该状态的规则。迁移建议全局搜索代码库中的if 0:、if False:型导入块将其改写为标准的if TYPE_CHECKING:块同时注意0.10 起任何局部变量只要叫TYPE_CHECKING都会触发该语义命名上避免与之冲突。2.2 更健壮的 noqa 解析PR #16483文件级抑制# ruff: noqa与行内抑制# noqa/# noqa: F401两类注释的语法在 0.10.0 被统一并增强了对若干错误的容忍度。日志给出的净效果是多数场景下 Ruff 会读取到更多原本被漏掉的抑制注释但少数原本能被读取的注释现在会向用户报告错误。完整语法规范见官方文档 docs/linter.md 的 Error suppression 章节。从源码结构看这一统一体现在 noqa.rs 中对两类指令的重构NoqaDirectives负责行内指令Directive::All与Directive::Codes两种形态FileNoqaDirectives负责文件级豁免FileExemption二者共用同一套基于词法分析的lex_directive解析路径并对非法位置/非法语法输出明确的warn!/错误如 “Invalid# ruff: noqadirective at ...”。迁移建议升级后完整运行一次ruff check重点观察两类输出——新出现的 “invalid noqa directive” 报错以及因注释被正确读取而减少的告警减少可能是好事但需要确认对应规则确实应该被抑制。2.3 格式化器不再为单上下文管理器加多余括号PR #14005这是一项格式化器的 bug 修复当with语句只有一个上下文管理器且带行尾注释时旧版 Ruff 会引入不必要的括号。修复后这类语句的格式化输出可能发生变化属于“修复导致的格式 diff”。with语句的格式化实现位于 stmt_with.rs。迁移建议如果项目以ruff format管理格式升级后对全仓跑一次格式化并提交 diff确认变化仅集中在这类with语句上。2.4 官方 Docker 镜像alpine 默认 tag 升至 3.21PR #16456Alpine 3.21 于 2024 年 12 月发布也是官方 Alpine 系 Python 镜像使用的版本。因此ruff:alpine镜像从 3.20 切换到3.21而ruff:alpine3.20tag 将停止更新。仓库中的 Dockerfile 是多阶段构建的定义可据此了解官方镜像的构建方式。迁移建议如果你的 CI 或容器配置硬编码了ruff:alpine3.20应迁移到ruff:alpine或显式的 3.21 tag。三、弃用规则Deprecated Rules以下两条规则在 0.10.0 被标记为弃用规则代码non-pep604-isinstanceUP038suspicious-xmle-tree-usageS320弃用意味着这两条规则仍会被执行但已不推荐后续版本可能移除。配置中显式select了UP038或S320的项目应规划替代方案并关注后续日志。四、规则重映射RUF035→S704规则unsafe-markup-use从 RUF 前缀重映射到 bandit 前缀新代码为S704即unsafe-markup-use规则更名后归入flake8-bandit命名空间。重映射的兼容层在源码中可见rule_redirects.rs 的转发表里登记了(RUF035, S704)确保旧代码在select/ignore/noqa注释中继续生效并解析到新规则。日志开头的警告正指向这里重映射可能导致原本被禁用的规则重新生效。典型场景是配置中按前缀批量操作如select [RUF]或ignore列表含RUF035——重映射后规则归属变化启停状态可能与升级前不同。迁移建议审计配置与noqa注释中所有RUF035的出现确认该规则在新代码S704下的启停符合预期。五、规则稳定化清单19 条脱离 preview以下规则从 preview 转为正式稳定稳定后不再受preview true门控可在非 preview 模式下直接使用规则代码规则代码batched-without-explicit-strictB911invalid-pathlib-with-suffixPTH210unnecessary-dict-comprehension-for-iterableC420invalid-assert-message-literal-argumentRUF040datetime-min-maxDTZ901unnecessary-nested-literalRUF041fast-api-unused-path-parameterFAST003unnecessary-cast-to-intRUF046root-logger-callLOG015map-int-version-parsingRUF048len-testPLC1802if-key-in-dict-delRUF051shallow-copy-environPLW1507unsafe-markup-use由RUF035更名S704os-listdirPTH208split-static-stringSIM905runtime-cast-valueTC006unquoted-type-aliasTC007non-pep646-unpackUP044六、规则行为稳定化10 项细节变化除整条规则稳定外0.10.0 还稳定了一批行为调整这些是升级后告警数量发生变化的常见来源PLW0211/N804__new__方法不再被invalid-first-argument-name-for-class-methodN804标记改由bad-staticmethod-argumentPLW0211负责PLE1310bad-str-strip-call现在也应用于已知类型为str或bytes的对象PYI019custom-type-var-for-self对可被Self替代的自定义TypeVar检测更准确且诊断范围从仅返回注解扩展为整个函数头N803invalid-argument-name忽略被typing.override装饰的函数的参数名PLW1508invalid-envvar-default现在会检测os.environ.get中类型非法的默认值实参PT012/PT031允许pytest.raises/pytest.warns的with语句中出现空语句体的for循环UP015redundant-open-modes诊断范围从整个open调用收窄为多余的 mode 参数本身——这意味着原有覆盖整个调用的noqa注释可能需要替换日志原文特别强调了这一点A005stdlib-module-shadowinglint.flake8-builtins.strict-checking的默认值从true改为falseFURB169type-none-comparison现在也识别expr不是名字表达式的type(expr) is type(None)比较组合项第 6 条同时覆盖PT012与PT031两条 pytest 规则。关于第 8 项源码层面可以佐证其影响机制strict_checking是 flake8_builtins/settings.rs 中的布尔设置规则实现 stdlib_module_shadowing.rs 中在非严格模式下会跳过多段模块名components.next().is_some()的检查——默认从严格切为非严格意味着A005的默认告警覆盖面缩小升级后该类告警可能减少。七、自动修复稳定化3 条以下三条规则在 preview 中的修复fix或修复改进在 0.10.0 转正规则代码对应 PRrepeated-equality-comparisonPLR1714#16685needless-boolSIM103#16684unused-private-type-varPYI018#16682稳定后在非 preview 模式下ruff check --fix也会应用这些自动修复升级后建议对--fix输出做一次抽样 diff 审查。八、其余变更Server、配置、Bug 修复与 CLIServerLSP移除了ruff.printDebugInformation的日志输出PR #16617。依赖该选项打印调试日志的 IDE 集成需要改用其他日志通道。配置flake8-builtins选项去前缀PR #16092flake8-builtins插件下所有builtins-前缀选项被弃用改用无前缀名称例如builtins-allowed-modules弃用、由allowed-modules取代。源码中弃用与回退逻辑位于 options.rs/// This option is ignored if both allowed-modules and builtins-allowed-modules are set. pub(crate) builtins_allowed_modules: OptionVecString, // 已弃用 pub(crate) allowed_modules: OptionVecString, // 新名称 // 解析时新名称优先 allowed_modules: self.allowed_modules.or(self.builtins_allowed_modules)文档注释同文件 L1414 附近明确写着 “builtins-allowed-moduleshas been renamed toallowed-modules”且同名新旧选项同时设置时以新名称为准。同样的改名也适用于builtins-strict-checking→strict-checkingL1442-L1469。迁移建议将pyproject.toml中lint.flake8-builtins.*下的builtins-前缀选项全部替换为无前缀写法旧写法虽仍解析但已被标记弃用。Bug 修复flake8-bandit修复混合大小写哈希算法名的漏报S324PR #16552。CLI修复ruff version命令中last_tag/commits_since_last_tag字段的错误PR #16686。九、0.10 升级迁移清单按风险从高到低升级前建议完成以下检查均以本仓库 changelogs/0.10.x.md 的记载为准TYPE_CHECKING语义将if 0:/if False:块改写为if TYPE_CHECKING:排查与局部TYPE_CHECKING变量意外同名带来的语义变化noqa注释全仓跑ruff check处理新增的非法指令报错与告警数量变化特别注意UP015诊断范围收窄导致的既有noqa失配RUF035→S704核对select/ignore/noqa中旧代码引用确认重映射后的启停状态配置项改名flake8-builtins下的builtins-前缀选项换成无前缀写法A005默认行为确认strict-checking默认false后A005告警减少是否符合预期需要原严格行为的团队应显式设置lint.flake8-builtins.strict-checking true格式与修复ruff format输出可能因with语句括号修复变化--fix因三条修复稳定化而覆盖面扩大建议对 diff 做抽样审查容器镜像ruff:alpine3.20停更改用ruff:alpine3.21 基底边界提醒requires-python推断变更不在 0.10.0 内若升级计划同时跨到 0.11.0需另行阅读 0.11.0 章节的影响说明。【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考