Ruff 0.5.x 版本演进全解：规则重映射、输出格式变更与语言服务器稳定化
Ruff 0.5.x 版本演进全解规则重映射、输出格式变更与语言服务器稳定化【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff本篇技术指南基于 Ruff 仓库中的 0.5.x 版本变更记录系统梳理 Ruff 0.5.0 至 0.5.7 的完整演进脉络从 0.5.0 引入的破坏性变更XDG 配置发现、ALL选择器行为、规则代码重映射、29 条预览规则的稳定化、废弃配置与 CLI 选项的移除到 0.5.3 语言服务器native server的稳定发布和 0.5.6 预览模式下 Notebook 默认启用。读完本文你将掌握升级到 0.5.x 需要做的全部配置迁移以及每个次要版本中规则行为、解析器、服务端与性能层面的具体改动并能结合仓库源码验证关键机制的实现位置。0.5.0一次面向长期稳定性的重大版本0.5.0 是 0.5.x 系列中唯一包含破坏性变更的版本。官方将其定位为一个里程碑式的发布一方面清理了此前积累的废弃配置与命令另一方面通过规则重映射remapping让 flake8-async 与 flake8-trio 两个插件体系合流并对大量预览期规则进行了稳定化。破坏性变更0.5.0 的破坏性变更共有五项升级时需要逐一确认macOS 用户级配置遵循 XDG 规范与其他 Unix 平台一致macOS 上用户级配置的发现路径改为遵循 XDG 规范。这意味着原先依赖 macOS 专属路径如~/Library/Application Support存放用户配置的使用方式不再适用。ALL选择器排除已废弃规则此前select [ALL]会包含所有规则0.5.0 起该选择器不再选中处于 deprecated 状态的规则。如果你在配置中使用ALL升级后部分规则会静默消失需要显式确认。发布压缩包多了一层目录嵌套下载的发行归档内部多了一个目录层级解压时需要用--strip-components1去除否则二进制会落在多一层子目录中。发布产物文件名不再包含版本号这一改动允许用户通过 GitHub 的/latest相对 URL 直接安装最新版简化了安装脚本。部分flake8-bandit规则的诊断范围diagnostic range被调整与 shell 相关的 bandit 规则高亮位置发生了变化对应 PR #10667依赖精确诊断范围做二次处理的工具需要回归验证。规则废弃syntax-errorE9990.5.0 起规则syntax-error代码E999被标记为废弃。原因是语法错误从此总是会被显示——解析器报错直接成为诊断输出的一部分不再需要通过选择E999来打开这一能力。这一改动在 0.5.1 中还得到了配套完善token 级别的规则可以在存在语法错误的源码上继续运行PR #11950且当源码存在语法错误时会自动禁用 autofixPR #12134避免在不完整 AST 上产生错误修复。规则重映射TRIO 并入 ASYNCASYNC10x 拆分为 ASYNC2xx这是 0.5.0 对现有用户影响最大的一组改动。flake8-trio 的规则被整体并入 flake8-async同时原来含义混杂的ASYNC100~ASYNC102被拆分为更精确的ASYNC2xx/ASYNC25x系列。完整映射表如下规则原代码新代码blocking-http-call-in-async-functionASYNC100ASYNC210open-sleep-or-subprocess-in-async-functionASYNC101拆分为ASYNC220、ASYNC221、ASYNC230、ASYNC251blocking-os-call-in-async-functionASYNC102合并进ASYNC220和ASYNC221trio-timeout-without-awaitTRIO100ASYNC100trio-sync-callTRIO105ASYNC105trio-async-function-with-timeoutTRIO109ASYNC109trio-unneeded-sleepTRIO110ASYNC110trio-zero-sleep-callTRIO115ASYNC115repeated-isinstance-callsPLR1701SIM101从源码结构看这些重定向并非仅在文档层面存在仓库中维护了一张集中式的重定向表 rule_redirects.rs其中明确标注了TRIO→ASYNC1的前缀级重定向TRIO100→ASYNC100、TRIO105→ASYNC105、TRIO109→ASYNC109、TRIO110→ASYNC110、TRIO115→ASYNC115以及PLR1701→SIM101的条目源码注释中标记为 Removed in v0.5。这张表通过get_redirect_target在解析select/ignore中的旧代码时生效——只要你在配置里写的是旧代码Ruff 会自动按新代码处理但变更记录同时提醒重映射可能导致原本被禁用的规则变为启用状态例如原ignore [ASYNC100]现在对应ASYNC210而新拆出的ASYNC220/ASYNC221/ASYNC230/ASYNC251不再被该条目覆盖。拆分后的新规则在源码中一一对应blocking_http_call.rs产出ASYNC210、blocking_process_invocation.rs产出ASYNC220/ASYNC221、blocking_open_call.rs产出ASYNC230、blocking_sleep.rs产出ASYNC251见 crates/ruff_linter/src/rules/flake8_async/。规则稳定化29 条规则脱离预览0.5.0 将以下规则从 preview 转为稳定稳定化后其行为不再随 preview 开关变化可放心用于生产配置Ruff 自有规则mutable-fromkeys-valueRUF024、default-factory-kwargRUF026flake8-banditdjango-extraS610Perflintmanual-dict-comprehensionPERF403Refurbprint-empty-stringFURB105、readlines-in-forFURB129、if-expr-min-maxFURB136、bit-countFURB161、redundant-log-baseFURB163、regex-flag-aliasFURB167、isinstance-type-noneFURB168、type-none-comparisonFURB169、implicit-cwdFURB177、hashlib-digest-hexFURB181、list-reverse-copyFURB187Pylintbad-open-modePLW1501、empty-commentPLR2044、global-at-module-levelPLW0604、misplaced-bare-raisePLE0744、non-ascii-import-namePLC2403、non-ascii-namePLC2401、nonlocal-and-globalPLE0115、potential-index-errorPLE0643、redeclared-assigned-namePLW0128、redefined-argument-from-localPLR1704、repeated-keyword-argumentPLE1132、super-without-bracketsPLW0245、unnecessary-list-index-lookupPLR1736、useless-exception-statementPLW0133、useless-with-lockPLW2101同时五条既有规则的行为调整也在 0.5.0 完成稳定化is-literalF632现在对 list、set、dict 字面量做is/is not身份检查也会告警needless-boolSIM103现在能检测隐式else分支的if表达式module-import-not-at-top-of-fileE402现在允许在导入语句之间修改os.environtype-comparisonE721现在允许type(x) is int这类惯用写法yoda-conditionSIM300现在覆盖更宽范围的表达式废弃配置与命令的移除0.5.0 按既定流程移除了所有标记为 deprecated 的配置项、CLI 选项与命令形态替代关系如下已移除的废弃配置项移除项替代方案output-format textoutput-format concise或output-format fulltab-sizeindent-width已移除的废弃 CLI 选项移除项替代方案--show-source--output-formatfull--no-show-source--output-formatconcise已移除的废弃 CLI 命令形态移除项替代方案ruff pathruff check pathruff --cleanruff cleanruff --generate-shell-completionruff generate-shell-completion配置查找与解析的实现集中在 crates/ruff_workspace/src/pyproject.rs 与 crates/ruff_workspace/src/options.rs其中说明了pyproject.toml、ruff.toml、.ruff.toml三种配置文件形态及其在解析范围respect-gitignore相关的respected_extensions默认列表中的处理——0.5.0 起这三种形态的匹配行为是稳定契约的一部分。CLI 与输出格式full成为默认值0.5.0 对 CLI 输出做了三处调整--statistics统计改用规则名而非诊断消息作为聚合维度PR #11697统计结果对不同代码风格更加稳定默认输出格式从简洁模式切换为fullPR #12010即诊断默认附带源码代码框code frame不再需要--show-source语法错误不再重复打印到控制台日志PR #11902避免诊断与日志双份刷屏。这一默认值在源码中有直接体现OutputFormat枚举将Full标记为#[default]并列出全部 13 种取值concise、full、json、json_lines、junit、grouped、github、gitlab、pylint、rdjson、azure、sarif等同时提供is_human_readable判定来决定是否输出页头/页脚见 settings/types.rs。如果 CI 中依赖旧的简洁输出做文本比对升级后应显式加--output-formatconcise。0.5.0 的其他改动预览功能新增assert-with-print-message规则PR #11981检测在assert中使用print附带消息的反模式。规则修正Ruff 自有修复gettext通过别名导入时RUF027的误报PR #12025NumPy更新NPY201中trapz、in1d的弃用判定PR #11948flake8-bandit调整 shell 相关规则的诊断范围PR #10667解析器修复6 项均影响错误恢复与诊断范围精度空类型参数列表如def f[]() - None现在正确报语法错误PR #12030未终止字符串不再吞掉换行符PR #12067且错误范围不再包含换行PR #12017行续接错误的定位使用正确的范围PR #12016行续接前的 2 字符行尾如 CRLF被正确处理PR #12035重新词法分析re-lexing时考虑行续接字符PR #12008其他用于度量line-length的 Unicode 表升级PR #11194移除 nursery 选择器的弃用报错PR #10172。0.5.1语法错误处理与缓存正确性0.5.1 是紧随 0.5.0 的修复版本重点围绕存在语法错误时的行为与缓存正确性。预览功能flake8-bugbear 新增mutable-contextvar-defaultB039PR #12113pycodestyle 新增装饰器后空白规则E204PR #12140pytest 插件交换了PT001与PT0023的默认状态PR #12106规则修正存在语法错误的源码上启用 token 级规则PR #11950flake8-bandit 的S113现在能识别httpxPR #12174NPY201覆盖异常类弃用项PR #12065PLE0241duplicate-bases新增 autofixPR #12105服务端源码动作source code actions不再触发语法错误通知PR #12148Notebook 同步时考虑新单元格内容PR #12203修复替换编辑范围计算PR #12171Bug 修复关键项源码含语法错误时禁用 autofixPR #12134修复含分隔符路径的缓存键碰撞PR #12159——这是 0.5.0 缓存键实现的缺陷修复影响 Windows 与 POSIX 混用路径的场景requires-python推断对约束更健壮PR #12091宽度计算改用逐字符char-wise宽度而非str宽度PR #12135pycodestyle关键词后跟逗号或分号时不再误报E275PR #12136、PR #12095pylintPLR1704跳过哑变量dummy variablesPR #12190性能parse_identifier去分配化PR #12103IdentifierAST 节点改用CompactString存储PR #12101——AST 节点内存布局优化的首批实践。0.5.2async 规则覆盖面扩展与 Windows 缓存容错预览功能ASYNC100、ASYNC109、ASYNC110、ASYNC115、ASYNC116五条规则统一扩展为覆盖anyio与asyncio命名空间PR #12221、#12236、#12261、#12262、#12266formatter 在带前导注释的推导式中对括号表达式使用space分隔符PR #12282。规则修正RET501将 property 从显式返回检查中豁免PR #12243NPY201增加np.NAN→np.nan诊断PR #12292FURB187list-reverse-copy的 autofix 改为 unsafe 标记PR #12303。服务端native server 开始考虑include与extend-include设置PR #12252并在设置重载时纳入嵌套配置PR #12253——这直接服务于 options.rs 中定义的文件包含/排除契约。CLI修复fix范围为空时省略代码框PR #12304对D203与 formatter 的空白行策略冲突给出 formatter 不兼容警告PR #12238。Bug 修复关键项Windows 上缓存写入失败不再致命PR #12302not运算被视为布尔测试影响若干以布尔上下文为判定条件的规则PR #12301flake8-banditHTTP 安全的 f-string 不再误报S310PR #12305S310支持显式字符串拼接的 URL 检测PR #12315无timeout参数的 httpx 调用不再误报S113PR #12213pycodestyle移除E721的非显而易见豁免PR #12300pyflakeswith块被视为单条目分支参与重定义分析PR #12311refurbopen()的newline参数转发修复限制在 Python ≥ 3.10PR #12244其他文档与帮助文本更新以反映--output-format full默认值PR #12248Python 文件发现使用更多线程PR #12258。0.5.3Ruff 语言服务器稳定发布0.5.3 的标志性事件是Ruff 语言服务器native server的正式稳定配套的编辑器文档同步重构包括编辑器安装指南与服务端设置参考文档迁移至独立文档仓库PR #12341服务端文档 PR #12344编辑器集成版本策略更新 PR #12375。仓库内 crates/ruff_server/ 即该服务器的实现其中 README.md 与 CONTRIBUTING.md 说明了其开发方式。预览功能formatter 在函数/类定义后、suite 与备选分支之间插入空行PR #12294pyupgrade 新增unnecessary-default-type-argsUP043PR #12371。规则修正B909loop-iterator-mutation检测enumerate迭代中的迭代器变更并移除对discard/remove/pop的豁免PR #12366、#12365PLR1714允许混合运算下的重复等值比较PR #12369PLR0913统计参数个数时忽略self/clsPR #12367PLW1514的 autofix 默认使用 UTF-8 编码PR #12370服务端原生服务器并行构建设置索引PR #12299索引项目时使用回退设置PR #12362server子命令开始接受--preview标志以分别控制 linter 与 formatter 的预览模式PR #12208Bug 修复C419允许sum/max推导式的额外参数PR #12364PLR1714修复 autofix 丢弃多余布尔运算PR #12368PLR1704在判定绑定类型时考虑语句前的表达式PR #12346。其他Wasm API 发布到 npmPR #12317对应仓库中的 crates/ruff_wasm/。0.5.4 与 0.5.5命名修正与 FastAPI/pydoclint 预览0.5.4体量较小核心是命名与修复质量RUF007更名为zip-instead-of-pairwisePR #12399名称更贴合规则意图flake8-builtins 不再对override方法报遮蔽诊断PR #12415flake8-comprehensions 的 autofix 为多参生成器插入括号PR #12422pydocstyle 处理 docstring 内部转义D301PR #12192文档修正Neovim 安装链接、设置参考中output-format默认值PR #12409、#124100.5.5引入了两组新的预览规则并修复 formatter 注释定位问题FastAPI 插件首发fastapi-redundant-response-modelFAST001与fastapi-non-annotated-dependencyFAST002PR #11579pydoclint 新增docstring-missing-exceptionDOC501与docstring-extraneous-exceptionDOC502PR #11471NumPy修复np.alltrue/np.sometrue的 2.0 规则PR #12473except块内忽略NPY201以兼容旧版 NumPyPR #12490pep8-namingignore-names不再作用于self/cls函数名N804/N805PR #12497formatter修复带类型参数函数的前导注释错位PR #12447Bug 修复cmp_fix的Ord实现修正PR #12471多参调用中未加括号的生成器表达式报语法错误PR #12445DOC501的 panic 修复PR #12435B013允许含星号表达式的单元素元组PR #12484文档新增 Emacs/Eglot、Zed 编辑器安装指南以及nvim-lspconfig破坏性变更说明PR #12426、#12501、#125070.5.6 与 0.5.7Notebook 预览启用与 pydoclint 完善0.5.6 的核心变化预览模式下默认启用 Notebook 的 lint 与 format。这是对 0.5.x 服务端 Notebook 支持工作的收束。如需退出该行为在配置中将*.ipynb加入extend-exclude即可[tool.ruff] extend-exclude [*.ipynb]同版本还包括预览规则flake8-builtins 实现 import/lambda/module 遮蔽检测PR #12546pydoclint 新增docstring-missing-returnsDOC201与docstring-extraneous-returnsDOC202PR #12485RET501将缓存型 property 及类似 property 的装饰器豁免出显式返回检查PR #12563服务端panic hook 增强容错PR #12610Zed 与 VS Code 使用$/logTrace输出服务端追踪日志PR #12564为单元格重排请求记录已删除单元格PR #12575flake8-implicit-str-concat禁止隐式拼接时始终允许显式多行拼接PR #12532Bug 修复重点isort 不再把必需导入标记为未使用PR #12537、保留import-from行尾内联注释PR #12498pycodestyleE305补换行、错缩进注释不附带PR #12606、#12604pyflakes 预览模式下__init__.py中一方子模块F401自动修复缺陷PR #12569pyupgrade 避免对slotsTruedataclass 建议无参 superPR #12530移除未使用导入时的 NFKC 规范化 BugPR #12571其他更多标准库装饰器被认定为 property 风格PR #12583、元类在各规则中的处理改进PR #12579、函数是否 property的判定在各规则间保持一致PR #125810.5.7继续完善 pydoclint 家族与修复质量预览C409考虑列表/集合推导PR #12657PYI044新增 autofixPR #12676RET505autofix 处理混合缩进避免语法错误PR #12740pydoclint 新增docstring-missing-yieldsDOC402与docstring-extraneous-yieldsDOC403PR #12538并处理了 stub 函数豁免、Returns 开头的 docstring 豁免、re-raise 视为显式抛出等 5 处语义细节PR #12651、#12675、#12642、#12639新增RUF031incorrectly-parenthesized-tuple-in-subscriptPR #12480RUF023在__slots__非集合且绑定被别处使用时将修复标记为 unsafePR #12692规则修正FURB177implicit-cwd与RUF007zip-instead-of-pairwise均新增 autofixPR #12708、#12663TRY002将BaseException纳入raise-vanilla-classPR #12620CLI修复嵌套pyproject.toml的缓存失效问题PR #12727Bug 修复重点ASYNC100多async with项误报PR #12643S608列表拼接构造 SQL 的误报PR #12720B909将return视为等价于breakPR #12646C419的sum接受集合推导PR #12691SIM114合并 if 分支时按优先级加括号PR #12737DOC501在未指定约定时尝试两种 Raises 段落风格PR #12649升级实践小结基于 0.5.x 的完整变更记录升级时需要检查的事项可以归纳为检查select/ignore中的旧代码TRIO*系列与ASYNC100/ASYNC101/ASYNC102/PLR1701会命中 rule_redirects.rs 中的重定向表自动换算但拆分/合并类映射ASYNC101→ 四条新规则、ASYNC102→ 并入ASYNC220/ASYNC221可能改变实际启用的规则集合建议用ruff check --statistics对比升级前后结果检查ALL选择器0.5.0 起ALL不再包含废弃规则如依赖E999需显式改为依赖语法错误直出替换被移除的配置与命令按上表将output-formattext、tab-size、--show-source及三种旧命令形态迁移到新写法CI 输出文本比对需显式指定--output-format确认 Notebook 策略若启用--preview0.5.6 起 Notebook 默认参与 lint/format不需要时用extend-exclude [*.ipynb]排除验证诊断范围依赖使用 flake8-bandit shell 相关规则S603/S604等并依赖精确高亮位置的下游工具需对 0.5.0 的诊断范围调整做回归。0.5.x 系列整体展示了 Ruff 的演进方法论破坏性变更集中于 0.5.0 一次性兑现并有重定向表兜底旧代码0.5.1–0.5.7 则以行为细化 修复质量 服务端能力为主线小步推进。后续的 0.6.x 变更记录 在此基础之上继续可作为对照参考。【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考