Ruff 0.1.x 版本演进深度解析：unsafe fixes 默认关闭、`ruff format` Beta 落地与 Preview 规则机制

Ruff 0.1.x 版本演进深度解析unsafe fixes 默认关闭、ruff formatBeta 落地与 Preview 规则机制【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff本文以 Ruff 官方变更日志 changelogs/0.1.x.md 为主体完整梳理 0.1.0 到 0.1.15 共 16 个版本的关键变更脉络并结合仓库源码印证 0.1.x 周期最重要的三项机制修复fix的三档适用性模型Safe/Unsafe/Display、ruff format格式化器的 Beta 发布与逐步完善、以及 Preview 模式下的新规则孵化流程。读完后你可以准确理解从 0.0.x 升级到 0.1.x 需要处理哪些破坏性变更、如何在项目中安全地启用 unsafe fixes、以及如何利用extend-safe-fixes/extend-unsafe-fixes按规则调整修复的激进程度。0.1.x 版本链总览changelogs/0.1.x.md记录了 0.1.0 至 0.1.15 的完整变更历史每个版本按固定维度组织Breaking changes破坏性变更、Rule changes规则行为调整、Preview features预览功能与新规则、Configuration配置项、CLI命令行、Formatter格式化器、Bug fixes缺陷修复、Documentation文档与 Internals内部实现。几个标志性节点版本标志性事件0.1.0首个使用CHANGELOG文件的版本unsafe fixes 改为显式 opt-in移除废弃的format设置0.1.1引入lint.preview与[format\|lint].exclude配置项0.1.2Ruff 格式化器 Beta 版随版本发布ruff format命令可用0.1.3格式化器批量消除与 Black 的已知偏差0.1.4引入按 Ruff 版本隔离的缓存目录、注释/字符串解析性能优化0.1.5RUFF_NO_CACHE环境变量、隐藏--extension参数0.1.6flake8-bandit、pylint、refurb等插件批量新增规则0.1.7ruff check与ruff format默认操作当前目录0.1.8通过docstring-code-format设置支持格式化 docstring 内代码片段0.1.9破坏性变更默认排除site-packages0.1.10–0.1.15持续补充 preview 规则RUF021、RUF022等与修复能力0.1.x 周期的核心叙事是Ruff 从一个“极快的 Python linter”扩展为“linter 格式化器”双引擎产品同时通过 Preview 机制为 0.2.x 稳定规则集蓄水。0.2.x 及以后版本见 changelogs/0.2.x.md。0.1.0首个正式使用 CHANGELOG 的版本及其破坏性变更变更日志开篇明确0.1.0 是第一个使用仓库内CHANGELOG文件的发布更早的变更条目位于 GitHub ReleasesRuff 同时启用了新的版本策略仓库内对应 docs/versioning.md。移除废弃的format设置0.1.0 删除了此前已废弃的format设置并给出三条明确替代路径配置层面format设置不能再用于配置输出格式改用output-format环境变量层面RUFF_FORMAT被忽略改用RUFF_OUTPUT_FORMAT命令行层面ruff check的--format选项被移除改用--output-format。从源码结构看这一替换在 CLI 层留下了完整的迁移痕迹crates/ruff/src/args.rs 中仍保留了针对旧--format的弃用警告修复0.1.0 条目 “Fix use of deprecated--formatoption in warning”说明官方在移除过程中保证了过渡期用户能看到清晰的提示而非静默失败。默认规则集收缩“Drop formatting specific rules from the default set”#7900将纯格式化取向的规则从默认 lint 集合中移除。这与 0.1.2 引入ruff format的动作一脉相承格式化职责交给专门的格式化器linter 默认集合聚焦于静态检查两者边界由此划清。unsafe fixes 改为显式 opt-in这是 0.1.x 周期影响面最大的行为变更“Unsafe fixes are no longer displayed or applied without opt-in”#7769。其动机可在 docs/linter.md 中找到官方解释某些修复即使语法正确也可能改变运行时行为、移除用户注释或改变异常类型从而破坏上游错误处理因此这类修复必须被用户显式“认领”后才能显示和应用。修复适用性模型从 CLI 参数到源码实现0.1.0 引入的 opt-in 机制并非孤立的 CLI 开关而是一套贯穿配置、CLI、输出渲染的三档模型。三档 Applicability在 crates/ruff_diagnostics/src/fix.rs 中Applicability枚举定义了修复的三个级别注释直接说明了各自语义DisplayOnly修复不安全仅用于展示供用户手动应用可能产生错误意图或无效语法对应 0.1.0 CLI 条目中重命名后的Display级别Unsafe修复结果语法有效但可能改变运行时行为或删除用户注释需要用户 opt-in 才能应用Safe修复可无条件应用要么肯定是用户意图要么完全保持代码语义除非整条语句被移除否则保留注释。docs/versioning.md 的 “Fix stabilization” 一节给出了同一模型的文档化表述Display永不应用、只展示Unsafe需显式 opt-in 才应用Safe自动应用。并且明确降低某个修复的适用性applicability不算破坏性变更而提升则遵循稳定化流程。CLI 与配置入口ruff check侧的参数定义见 crates/ruff/src/args.rs--unsafe-fixes使用overrides_with与隐藏的--no-unsafe-fixes互斥配对解析后折叠为一个布尔结果。与 0.1.0 变更日志条目一一对应的是--unsafe-fixesopt-in 显示并应用 unsafe fixes#7769配置项unsafe-fixes新增#7769允许在pyproject.toml中长期开启--fix的默认行为随之变化不再包含 unsafe 修复help 文本也更新为 “Use--no-fixto disable or--unsafe-fixesto include unsafe fixes”。输出提示与 per-rule 升降级在 crates/ruff/src/printer.rs 中可以看到提示信息的渲染逻辑当UnsafeFixes处于仅提示hint状态时汇总消息会追加 “{n} hidden fix(es) can be enabled with the--unsafe-fixesoption” 字样这正是变更日志中 “Update fix summary message incheck --diffto include unsafe fix hints”#7790的实现落点而 “Renames applicability levels toSafe,Unsafe, andDisplay”#7843则统一了文档与输出中的命名。0.1.0 还配套提供了按规则调整修复安全性的配置项#7841extend-safe-fixes将某条规则的修复提升为 safeextend-unsafe-fixes则降级为 unsafe。docs/linter.md 给出了可直接复制的示例[tool.ruff.lint] extend-safe-fixes [F601] extend-unsafe-fixes [UP034]支持使用前缀选择整组规则例如用F将 Pyflakes 所有规则的修复提升为 safe。0.1.5 进一步补全了该机制的边界情况合并extend-unsafe-fixes与extend-safe-fixes时会考虑选择器selector的特异性#8444避免同名规则在不同层级配置下升降级结果不一致。0.1.2ruff formatBeta 版随包发布变更日志对 0.1.2 的定性是“This release includes the Beta version of the Ruff formatter — an extremely fast, Black-compatible Python formatter. Try it today withruff format!”。围绕格式化器的 0.1.x 演进呈现出清晰的三阶段节奏Beta 发布0.1.20.1.2 的 Formatter 条目密度是整条 0.1.x 链中最高的之一反映了 Beta 前的集中打磨line-ending默认值改为auto#8057为format命令加入缓存#8089并进一步避免读取已命中缓存的文件#8134移除--line-length命令行选项#8131行宽统一由配置line-length驱动同时补充了line-length文档中的格式化器说明#8150对与 linter 不兼容的旧格式化选项发出警告#8088并在 0.1.3 继续细化针对isort.force-single-line等具体场景的警告文案#8192、#8244移除实验性警告#8148完成从 “experimental” 到 “Beta” 的姿态切换0.1.2 同时新增ruff version命令并支持长版本显示#8034以及配置项pycodestyle.max-line-length#8039。偏差消除0.1.30.1.3 的主题是 “removing several known and unintentional deviations from Black”消除与 Black 的已知非故意偏差。代表性修复包括None/True/False的幂运算两侧不再添加空格#8189注解赋值中避免引入多余括号#8233类定义与前置注释之间插入必要的空行#8224仅当表达式以括号开头或结尾时才省略可选括号#8238使用源类型source type决定格式化解析模式#8205使# fmt: skip/# fmt: off场景下的解析更准确为格式化器引入 preview 模式的测试与基础实现#8044为 0.1.4 起各版本中大量 “preview style” 条目奠定基础fmt: off尾部子注释修复#8234、IPython escape command 的括号支持#8207。0.1.3 还顺手修正了一个文档与实现不一致的问题isort 的行宽判断改回使用line-length设置而非pycodestyle.max-line-length#8235。持续精修0.1.4–0.1.9此后各版本持续收敛格式化器行为0.1.4fmt: off/fmt: skip保留尾部分号#8273、#8275、避免将字节串误判为 docstring#8350、return 位置的元组优先按逗号拆分#8280、--line-length选项回归format命令#83630.1.5多行 lambda 表达式语句的格式稳定性修复#84660.1.6await链式调用的不稳定格式修复#8676、Notebook 尾部分号保留#8590、测试期间对比格式化前后 AST 的一致性#86240.1.7preview 风格的多行字典/列表 “hugging”#8293、类型别名的尾随注释内联#8941、单参数换行的函数插入尾逗号#89210.1.9dynamic行宽模式下修复 doctest 超过配置行宽的问题#9129、can_omit_optional_parentheses在右端含 f-string 时的修复#9124、target-version进入格式化器选项#9220。0.1.8docstring-code-format与文档代码片段格式化0.1.8 引入了 opt-in 的docstring-code-format设置#8854允许格式化 docstring 中的 Python 代码片段。围绕该特性同一版本还完成了配套能力“dynamic” 行宽模式#9098、Markdown 代码块重排#9030、reStructuredText 代码片段支持#9003以及将 “preserve” 引号风格加入 preview#8822以对齐 Black 的skip-string-normalization。这使 Ruff 成为少数能同时统一源码与文档内代码片段格式的工具。Preview 机制新规则的孵化器变更日志中每个版本的 “Preview features” 小节是观察 Ruff 规则演进的最佳样本。docs/versioning.md 的 “Rule stabilization” 一节规定了游戏规则新规则一律先进 previewpreview 规则至少经历一个 minor 版本才有资格转正例如 0.6.1 加入的规则最早 0.8.0 才能稳定preview 期内行为可能随时调整甚至移除。从 0.1.x 的 preview 条目可以归纳出三条孵化轨迹既有插件的补齐。pylint插件在 0.1.1–0.1.15 间连续落地了PLR6201、PLR0916、E0704、W0604、PLW15140.1.1PLR1704、W0108修复0.1.6PLR1733、PLe1132、PLR0917、PLR17360.1.7PLR09140.1.9直至E0237、PLE0643、PLR17020.1.15flake8-bandit则在 0.1.12 一次性引入S4XX可疑导入系列#8831与 SSL 系列规则S502/S503/S504#9384–#9391。Ruff 自有规则RUF前缀的扩展。0.1.12 新增RUF021parenthesize-chained-operators强制a or b and c加括号#9440与RUF011的变量键支持#94110.1.14 新增RUF022__all__排序#94740.1.15 则加入了RUF024mutable-fromkeys-value、RUF025无必要的dict推导、RUF026default_factory位置守卫与__slots__/__match_args__排序规则#9564。修复能力的 preview 先行。大量条目以 “Add fix for …” 形式出现例如 0.1.6 为E221–E228、E271/E272系列补充修复#8622、#86230.1.14 为B033、SIM113、PGH002、TRY400补充修复0.1.15 一次性覆盖flake8-return的RET505–RET508全家族#9595。按 docs/versioning.md 的规则preview 期新增 safe fix 只触发 patch 版本号这也解释了 0.1.x 各 patch 版本为何条目繁密却不提升 minor。0.1.15 还出现了一条机制性条目当NURSERY选择器与--preview同时使用时直接报错#9682体现了 preview 选择器语义在 0.1.x 末尾的收紧——0.1.0 已将其调整为“仅在启用规则时对空 preview 选择器给出警告”#7842。0.1.9 破坏性变更默认排除site-packages0.1.x 周期中唯一的独立 “Breaking changes” 小节出现在 0.1.9“Add site-packages to default exclusions”#9188。对扫描目录包含依赖环境如虚拟环境、node_modules式 vendored 代码的项目升级后这些路径默认不再进入 lint/format 流程。从变更日志的表述看这是一次默认扫描范围的收缩属于 docs/versioning.md 中 “Configuration changes in a backwards incompatible way” 触发 minor 升版的典型情形——但 Ruff 将其放进了 patch 版本属于 0.x 阶段版本策略下的特例升级时值得单独核对exclude配置。缺陷修复中的高频主题浏览 0.1.x 的 “Bug fixes” 小节可以归纳出四个反复出现的修复主题它们恰好对应 Ruff 的四个解析子系统f-string 与 PEP 701 新词法器。0.1.0 修复了 match 模式字面量中误允许 f-string#7857、f-string 内花括号转义#7780、单引号 f-string 多行 format spec 的词法#77870.1.4 处理了未终止 f-string#8154与r/f前缀顺序#84640.1.7 修复了 ur 字符串前缀导致的语法错误#8971。Notebook 支持。0.1.0 为 JSON 输出新增cell字段#76640.1.4 支持 Jupyter automagics 检测#83980.1.7 让E402在 cell 级别工作、E703/B015/B018豁免 cell 尾表达式#8821、#8815、#88720.1.12 为所有诊断补充 cell 索引#93870.1.14 起 Notebook 格式化生成确定性 ID#9359。类型系统相关规则的误报治理。flake8-type-checking系列在 0.1.6–0.1.15 间连续修正订阅式基类的 TYPE_CHECKING 判定#7954 的后续修复、typing_extensions全成员视为 typing 别名#9335、PydanticBaseConfig/BaseSettings的默认拷贝语义#8793、#9650、InitVar不再标记为 typing-only#9688。修复fix自身的安全性。0.1.2 将B006mutable-argument-defaults与PLR6201literal-membership的修复降级为 unsafe#8097、#81080.1.8 允许flake8-type-checking规则自动为运行时求值引用加引号#60010.1.10 对自动加引号修复做了防嵌套引号与编辑去重处理#9168、#9140。这些条目共同说明在 0.1.x 周期中“修复的适用性标注”本身成为了一类被持续审计的对象。内部实现与性能条目0.1.4 的 Internals 小节是观察 Ruff 工程结构的一个窗口按 Ruff 版本隔离缓存目录#8333、为--fix与--diff启用选择性缓存#8316、注释解析#8193与字符串解析#8227的性能优化、为 isort 引入专用排序键#7963。0.1.14 则改进--show-settings的可读性输出#94640.1.15 为动态配置项生成专用 JSON schema#9632。此外 0.1.5 支持通过RUFF_NO_CACHE环境变量禁用缓存#85380.1.10 为 TOML 解析错误补充文件路径#9358、为格式化器解析错误补充行列号#9321显著提升了配置排错体验。升级 0.1.x 的实操核对清单结合变更日志与 docs/linter.md、docs/configuration.md 中的说明从 0.0.x 升级到 0.1.x 时建议按以下顺序核对移除format设置配置中的format改为output-format环境变量RUFF_FORMAT改为RUFF_OUTPUT_FORMAT命令行--format改为--output-format确认 unsafe fixes 行为默认不再显示/应用 unsafe 修复。若工作流依赖自动修复激进规则显式启用# 仅显示 unsafe fixes ruff check --unsafe-fixes # 显示并应用 unsafe fixes ruff check --fix --unsafe-fixes或在配置中长期开启unsafe-fixes true若希望连提示都关闭设为false或传--no-unsafe-fixes按需微调修复安全性用lint.extend-safe-fixes/lint.extend-unsafe-fixes按规则或规则前缀升降级参考 0.1.2 中修复过的示例文档#8139检查exclude与默认规则集格式化取向规则已移出默认集合依赖它们的用户需显式--select0.1.9 起site-packages默认排除必要时用 0.1.1 引入的[format|lint].exclude#8000或全局exclude精确控制--force-exclude在 0.1.4 起对二者均生效#8393格式化器迁移若此前使用 Black可用ruff format --check0.1.9 起对已格式化文件给出明确消息#9153对比差异再结合 0.1.1 引入的--target-version#8055与--diff#7937选项做灰度切换关注 JSON 输出消费者诊断输出新增了cell字段0.1.0#7664与applicability字段语义重命名0.1.0#7843json格式下所有修复始终展示、安全级别可从applicability字段读取docs/linter.md。小结0.1.x 是 Ruff 从 0.0.x 走向 1.0 的第一段正式航程0.1.0 确立了 “CHANGELOG 版本策略 修复三档适用性” 的工程基线0.1.2 让ruff formatBeta 版进入发行包其后九个 patch 版本则围绕“消除与 Black 的偏差”“Preview 规则孵化”“修复安全性审计”三条主线高频迭代。理解这一周期关键在于把握两个贯穿始终的机制修复适用性模型源码见 crates/ruff_diagnostics/src/fix.rs与 Preview 稳定化流程策略见 docs/versioning.md——前者决定--fix的边界后者决定你在任何 patch 版本中会看到哪些“即将转正”的新规则。【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考