尧图网站建设 
Ruff Python Formatter 深入解析作为 Ruff CLI 内建格式化引擎的设计、实现与 Black 兼容策略【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruffcrates/ruff_python_formatter是 Ruff 代码库中负责 Python 源码格式化的核心 crate它被封装进ruffCLI以ruff format命令对外提供服务目标是在保持与 Black 近乎一致输出风格的同时把性能与工具链统一做到极致。本文以 crates/ruff_python_formatter/README.md 为骨架结合该 crate 的源码、测试快照以及仓库内的格式化功能文档、Black 偏差清单系统梳理它的设计目标、命令行用法、底层格式化流水线、可配置项与版本化策略。读完你将理解 Ruff formatter 与 Black 的兼容边界、它快且一致的实现思路以及如何在实际项目中配置、使用并排查格式化差异。一、Ruff Formatter 是什么作为ruffCLI 一部分的格式化引擎crates/ruff_python_formatter在项目中的作用用 crate README 原文概括即是The Ruff formatter is an extremely fast Python code formatter that ships as part of theruffCLI.也就是说这个 crate 是 Ruff 体系内负责格式化的内部组件它本身不提供面向终端用户的独立二进制入口而是与ruffCLI 深度绑定。在根工作区中crates/ruff/Cargo.toml将ruff_python_formatter { workspace true }声明为ruff主 crate 的依赖而从目录结构上看crate 内部也自带cli.rs与main.rs见 src 目录其主要用途是对格式化行为做独立调试与基准化。用户在命令行中真正触达的入口是crates/ruff/src/commands/format.rs文件/目录格式化与crates/ruff/src/commands/format_stdin.rs标准输入流格式化所实现的ruff format命令。在仓库内该 crate 的顶层使用方式沉淀在 docs/formatter.md 中。基本调用非常直接ruff format # Format all files in the current directory. ruff format path/to/code/ # Format all files in path/to/code (and any subdirectories). ruff format path/to/file.py # Format a single file.与 Black 的行为一致ruff format path/to/file.py会就地改写文件而ruff format --check path/to/file.py只做检查、不写回文件一旦发现存在未格式化的文件就以非零退出码结束。完整选项可用ruff format --help查看。二、设计目标做 Black 的 drop-in 替代但聚焦性能与工具链统一1. 三条核心目标根据 crate READMERuff formatter 的设计目标可归纳为三点作为 Black 的 drop-in 替代在已经用 Black 格式化过的代码上运行 Ruff期望产出与 Black 近乎一致的输出。官方文档给出的量化说明是在 Django、Zulip 这类大规模、长期使用 Black 格式化的项目上运行时超过 99.9% 的行被格式化得与 Black 完全相同该数据出自 crates/ruff_python_formatter/README.md 及 docs/formatter.md 对 Black 兼容性的陈述。把性能当作首要创新点Ruff formatter 的初始目标不是去发明一种新的代码风格而是在性能上做创新同时把 lint、format 以及未来的工具统一到一条工具链上。追求最小迁移扰动由于 Black 在 Python 生态中的流行度以 Black 兼容为目标可以确保项目从 Black 迁移到 Ruff 时绝大多数代码保持不变。README 也明确指出迁移时在边缘情况上会遇到少量差异但不应期待大范围改动。2. 偏差的分层处理策略README 对偏差给出了两条处理路径这个区分非常关键有意偏差intentional deviations先对照仓库内的已知偏差清单Known Deviations from Black逐条核验。这些是 Ruff 有意为之的差异多数出现在Ruff 的行为被认为更一致或在底层实现差异下显著更简单、且对终端用户影响可忽略的场景。无意偏差unintentional deviations若确认是 Bug 类偏差则应作为 issue 提交到项目问题跟踪器README 中附有以formatter标签检索与新建 issue 的指引供维护者修复。另外README 特别提醒在未经 Black 格式化过的代码上运行 Ruff 时Ruff 会做出一些与 Black 不同的决策因此会看到更多偏差尤其是**行尾注释end-of-line comments**的处理方式。这正是稳定输入上高度一致、非标准输入上存在风格差异的行为边界。3. 风格参照Black 的稳定代码风格在设计哲学上Ruff formatter 遵循 Black 的稳定版代码风格其美学取向是一致性、通用性、可读性、减少 git diff。README 没有自带风格示例仓库文档 docs/formatter.md 给出了一个直观的前后对比_make_ssl_transport长参数列表可以看到 Ruff 将每个参数独占一行、统一缩进、把文档字符串由单引号改为双引号等行为与 Black 的稳定风格一致# Input一段参数拥挤、缩进混乱的代码 def _make_ssl_transport( rawsock, protocol, sslcontext, waiterNone, *, server_sideFalse, server_hostnameNone, extraNone, serverNone, ssl_handshake_timeoutNone, call_connection_madeTrue): Make an SSL transport. if waiter is None: waiter Future(looploop) ... # Ruff 格式化输出 def _make_ssl_transport( rawsock, protocol, sslcontext, waiterNone, *, server_sideFalse, server_hostnameNone, extraNone, serverNone, ssl_handshake_timeoutNone, call_connection_madeTrue, ): Make an SSL transport. if waiter is None: waiter Future(looploop) ...三、与 Black 的兼容边界已知有意偏差速览docs/formatter/black.md完整枚举了 Ruff 相对 Black 的所有有意偏差全文 800 余行。理解这些偏差是项目从 Black 迁移到 Ruff 时评估那 0.1% 差异会不会落在我的代码上的关键。摘取几条最具代表性的完整清单请直接阅读 docs/formatter/black.md行尾注释Trailing end-of-line commentsBlack 优先把整条语句压缩进一行并把注释挪到折叠语句末尾可能改变注释语义Ruff 效仿 Prettier会展开任何含有行尾注释的语句让注释留在贴近原始位置的地方代价是保留更多纵向空间。计算行宽时忽略 pragma 注释# type、# noqa、# pyright、# pylint等 pragma 注释不参与行宽计算从而避免 Ruff 搬动注释、改变其抑制/注解范围例如# noqa被移到行尾会同时压制first()与second()的错误。这类似 Pyink但与 Black 不同。行宽计算口径Ruff 用 Unicode 宽度display width判断一行是否放得下字符串、标识符与注释均按 Unicode 宽度计算而 Black 对非字符串 token 使用字符数。F-stringsBlack 不格式化 f-string 花括号{...}内的表达式部分而 Ruff 会格式化Ruff 0.9.0 起稳定详见偏差清单中的 F-strings 小节。不保留过长嵌套表达式外层括号、调用中单个多行字符串参数的缩进处理、assert/global/nonlocal语句的断行方式等均与 Black 存在细节差异。也就是说drop-in是就 Black-formatted 代码这一稳定输入而言的一旦输入本身不符合 Black 风格Ruff 与 Black 在边缘上的不同决策就会被放大这正是文档要求迁移用户逐条核对偏差清单的原因。四、内部实现源码级解读格式化流水线1. crate 模块划分从 src 目录结构 可以清楚看到该 crate 按 Python 语法范畴组织格式化规则是典型的每种 AST 节点一个格式化规则架构statement/语句级规则如stmt_if.rs、stmt_function_def.rs、stmt_class_def.rs、stmt_with.rs、stmt_match.rs等expression/表达式级规则覆盖调用、二元运算、推导式、f-string、lambda、字典、元组、切片等pattern/match语句的模式匹配格式化comments/注释的放置placement.rs、映射与格式化含大量独立快照测试string/字符串与文档字符串处理docstring.rs、normalize.rs、implicit.rsmodule/、type_param/、builders.rs、context.rs、verbatim.rs模块级、类型参数、公共 builder、格式化上下文与原样输出verbatim例如fmt: off区域。这种一节点一规则的结构配合统一的FormatNodeRuleNtrait定义于 lib.rs使每条格式化规则都遵循同一范式先输出节点前置注释leading comments再输出字段格式化结果最后兜底断言并输出后置注释trailing comments与 source map 位置标记。2. 顶层流水线parse → trivia → format → printlib.rs 中的format_module_source是理解整个格式化主流程的最佳起点pub fn format_module_source( source: str, options: PyFormatOptions, ) - ResultPrinted, FormatModuleError { let source_type options.source_type(); let parsed parse(source, ParseOptions::from(source_type))?; let trivia TriviaRanges::from(parsed.tokens()); let formatted format_module_ast(parsed, trivia, source, options)?; Ok(formatted.print()?) }完整链路为先用ruff_python_parser把源码解析为 AST同时保留 token 信息再由ruff_python_trivia::TriviaRanges从 token 流构造注释/空白等trivia区间注释、空行信息在此被单独管理这正是 Ruff 能在格式化的同时妥善处理行尾注释与 pragma 的原因之一随后将 AST 与 trivia 交给格式化器产出中间格式文档Formatted对应ruff_formattercrate 的 IR 文档模型最后由 printer 打印为最终文本。若源码无法解析为合法 Python或打印过程出错则统一包装为FormatModuleError源码中同时实现了到Diagnostic的转换供上层工具展示诊断信息。3. 配置模型的底层形态PyFormatOptions格式化一个文件的全部决策参数收敛在 options.rs 的PyFormatOptions中。它区别于面向整个项目/子目录的设置是解析完配置后落到单个文件上的最终快照。从源码可见其字段与默认值与Default实现一致字段默认值说明source_type随扩展名推导.py与.pyi类型存根遵循不同规则target_version默认 Python 版本决定哪些语法可用如 3.12 的 PEP 701 嵌套 f-stringindent_styleSpace空格空格或 Tabindent_width4一个 Tab 或缩进级别的可视宽度line_width88换行阈值与 Black 默认一致line_ending平台默认换行符风格quote_styleDouble双引号或单引号偏好magic_trailing_comma遵循 Black 语义决定(a, b,)这类魔幻尾逗号是否触发展开source_map_generation关闭是否生成源位置→格式化后位置的映射范围格式化等高级能力用docstring_code关闭opt-in是否格式化文档字符串中的 Python 代码示例docstring_code_line_widthdynamic文档字符串代码示例的行宽dynamic表示跟随外层代码行宽preview关闭是否启用预览风格nested_string_quote_stylealternatingPython 3.12 嵌套字符串的引号策略这些字段与quote_style、nested_string_quote_style等枚举在 lib.rs 中被公开 re-export作为格式化库的能力边界。4. 从库到 CLIruff format的命令实现在ruff侧format.rs 承接文件发现与任务调度收集目标文件含对 Python、Jupyter Notebook、Markdown 等类型的识别与过滤多线程执行格式化统计已格式化/未变更并处理--check、--diff、--exit-non-zero-on-format等标志format_stdin.rs 则面向管道输入如编辑器与 pre-commit 场景。关于退出码约定仓库文档 docs/formatter.md 给出精确语义可直接用于 CI 判断ruff format0表示正常结束无论是否改动了文件1表示正常结束且至少一个文件被格式化、同时指定了--exit-non-zero-on-format2表示配置非法、CLI 选项非法或内部错误。ruff format --check0表示没有文件需要格式化1表示存在至少一个需要格式化的文件2表示异常终止。五、配置指南在 pyproject.toml 或 ruff.toml 中调整格式化行为尽管 Ruff formatter 不提供 YAPF 式的大规模风格定制但它支持配置引号风格、缩进风格、行宽、行尾、文档字符串内代码格式化等。这一点与 Black 形成对照Black 几乎不可配置Ruff 则开放了若干 Black 所没有的选项源码字段与文档配置项一一对应见 options.rs。仓库文档 docs/formatter.md 给出的综合示例单引号 Tab 缩进 行宽 100 格式化文档字符串中的代码示例# pyproject.toml [tool.ruff] line-length 100 [tool.ruff.format] quote-style single indent-style tab docstring-code-format true# ruff.toml line-length 100 [format] quote-style single indent-style tab docstring-code-format true关于配置文件的整体解析机制可以进一步参考 docs/configuration.md 与ruff_workspacecrate负责pyproject.toml/ruff.toml的发现、分层与合并本仓库的ruff.schema.json亦为格式化选项的完整 JSON Schema 约束。六、版本化与稳定性内部 crate 的使用边界关联 README 的 Versioning 段落crates/ruff_python_formatter/README.md是对使用者最重要的契约声明其要点如下该段落在源码仓库中以BEGIN/END GENERATED CRATE VERSIONING标记自动维护本 crate 是Ruff 的内部组件internal component对应的 Rust 公共 API不稳定会频繁发生破坏性变更当前版本为0.0.12与 Cargo.toml 一致是Ruff 0.16.6见 crates/ruff/Cargo.toml的组成部件版本化遵循 Ruff 的 crate 版本化策略crate versioning policy。给集成方的两条实操建议由此而来其一不要直接以 Rust 库的方式依赖ruff_python_formatter的 API 编写长期代码因为它随时可能重构其二日常使用应始终通过随ruff一起发布的ruff format命令把格式化功能当作 CLI 能力而非稳定库 API 来消费这样 crate 内部如何演进都不会影响你的使用方式。七、质量保障体系快照测试与格式化偏差的实证追踪ruff_python_formatter拥有非常重的测试资产这是与 Black 兼容这个目标能被工程化验证的基础测试入口tests/fixtures.rs 以datatest-stable驱动Cargo.toml 中声明了独立的fixturestest target对tests/snapshots/下 260 个快照文件逐一执行输入 → 格式化 → 与期望输出比对快照资产tests/snapshots 覆盖各类 Python 语法与边界情况注释专项src/comments/snapshots/下存放了 30 余个注释处理专项快照覆盖前导/尾随/悬空注释、if/elif/else注释、try/except注释、match分支注释、嵌套二元表达式注释等说明注释放置是格式化正确性的高敏感区一致性快照src/snapshots还包含string_processing之类的处理级快照。这种每种语法结构 每种注释位置 若干真实风格样例组合出来的快照矩阵正是 Ruff formatter 能对非 Black 输入也保持可预期、可回归的核心机制。八、扩展能力与协同使用1. 文档字符串代码与 Markdown 代码块的格式化opt-in除普通 Python 文件外Ruff formatter 还提供可选的文档内代码格式化其能力边界由 src/string/docstring.rs 等实现文档细节见 docs/formatter.mddocstring 代码示例能识别 Python doctest、CommonMark fenced code blockinfo string 为python/py/python3/py3无 info string 的代码块默认按 Python 处理、reStructuredText literal block以及code-block/sourcecode指令。若示例解析失败、或重排后产生非法 Python则自动跳过不改。行宽跟随默认docstring-code-line-length dynamic即示例内行宽跟随外层代码的line-length保证缩进过的文档字符串里换行也不超限也可固定行宽例如[tool.ruff.format] docstring-code-format true docstring-code-line-length 20Markdown 文件ruff format会格式化 Markdown 中的 Python fenced code blocks含pyi存根风格与pyconREPL 风格也支持 Quarto 风格{python}花括号 info string。若要处理.md以外的扩展名可用extension映射如把.mdx、.qmd归为markdown要整体禁用 Markdown 格式化则把*.md加入extend-exclude。通过ruff-pre-commit使用时需要在types_or里显式追加markdown。2. 格式化抑制# fmt: off/# fmt: on/# fmt: skip与 Black 一致Ruff 支持三种 pragma也兼容 YAPF 的# yapf: disable/# yapf: enable但在作用域语义上有明确规则详见 docs/formatter.md 的 Format suppression 一节# fmt: on/# fmt: off在语句级生效——写在表达式内部例如列表元素之间不会起任何作用必须把整条语句包裹起来# fmt: off not_formatted3 also_not_formatted4 # fmt: on# fmt: skip作用于 case 头、装饰器、函数/类定义头或同一逻辑行上前面的语句放在表达式末尾同样无效需作用于整条语句if True: pass elif False: # fmt: skip pass a [1,2,3,4,5] # fmt: skip def test(a,b,c,d,e,f) - int: # fmt: skip pass x1;x2;x3 # fmt: skipMarkdown 代码块内部除普通 pragma 外还可用!-- fmt:off --/!-- fmt:on --以及 blacken-docs 风格的!-- blacken-docs:off/on --成对包裹代码块未闭合的off注释会覆盖文档剩余部分。从实现侧看verbatim原样保留能力由 src/verbatim.rs 支撑# fmt: skip等注释的识别入口可从 comments 模块的has_skip_comment与注释放置逻辑src/comments/placement.rs中找到。3. 与 linter 协同排序导入与冲突规则Ruff formatter不做导入排序文档给出的推荐做法是先用 linter 修Iisort再格式化ruff check --select I --fix ruff format同时formatter 与若干 lint 规则存在天然张力详见 docs/formatter.md 的 Conflicting lint rules 一节若启用了缩进类W191/E111/E114/E117、引号类Q000–Q004、D300、D206等、尾逗号类COM812/COM819等规则格式化产物可能反过来触发新的 lint 报错。Ruff 的兼容性目标是运行 formatter 不应引入新的 lint 错误因此官方建议避免启用上述规则并避免把 isort 的force-single-line、force-wrap-aliases、lines-after-imports等选项设为非默认值——当检测到不兼容配置时ruff format会打印警告无警告即代表配置安全。4. Preview 风格渐进式风格演进与 Black 的 preview style 机制类似Ruff 将尚未转正的格式化风格放在preview模式 下试验通过次版本发布逐步转正。仓库中 src/preview.rs 是该机制的实现载体。docs/formatter.md 给出过一个直观例子——方法链的 fluent layout预览风格当df.filter(cond).agg(func).merge(other)这类链式调用超过行宽时预览风格选择在首个属性访问之前断行.filter单独缩进一行突出对固定对象df的连续变换这一语义而稳定风格与 Black 一致则把首个调用留在首行。对同一段代码两种风格的选择差异只在属性访问与紧随其后的调用/下标的断行位置上这正体现了 preview 模式下风格演进的收敛与克制。结语ruff_python_formatter的设计取舍可以浓缩为一句话风格上不创新、实现上创新——以 Black 稳定风格为兼容基线、以 99.9% 行级一致官方对 Django/Zulip 等大型项目的声明数据为兼容标尺把工程能量投入格式化的正确性、可回归性与工具链统一而不是另起炉灶发明代码风格。如果你打算把项目从 Black 迁移到 Ruff建议依次做三件事对照已知偏差清单评估你的代码形态在 CI 中用ruff format --check接替 Black 的--check遇到非预期差异时先在仓库的格式化快照测试中确认是否属于已覆盖场景再决定是按偏差清单理解它、还是反馈给上游修复。【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Ruff Python Formatter 深入解析：作为 Ruff CLI 内建格式化引擎的设计、实现与 Black 兼容策略
Ruff Python Formatter 深入解析作为 Ruff CLI 内建格式化引擎的设计、实现与 Black 兼容策略【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruffcrates/ruff_python_formatter是 Ruff 代码库中负责 Python 源码格式化的核心 crate它被封装进ruffCLI以ruff format命令对外提供服务目标是在保持与 Black 近乎一致输出风格的同时把性能与工具链统一做到极致。本文以 crates/ruff_python_formatter/README.md 为骨架结合该 crate 的源码、测试快照以及仓库内的格式化功能文档、Black 偏差清单系统梳理它的设计目标、命令行用法、底层格式化流水线、可配置项与版本化策略。读完你将理解 Ruff formatter 与 Black 的兼容边界、它快且一致的实现思路以及如何在实际项目中配置、使用并排查格式化差异。一、Ruff Formatter 是什么作为ruffCLI 一部分的格式化引擎crates/ruff_python_formatter在项目中的作用用 crate README 原文概括即是The Ruff formatter is an extremely fast Python code formatter that ships as part of theruffCLI.也就是说这个 crate 是 Ruff 体系内负责格式化的内部组件它本身不提供面向终端用户的独立二进制入口而是与ruffCLI 深度绑定。在根工作区中crates/ruff/Cargo.toml将ruff_python_formatter { workspace true }声明为ruff主 crate 的依赖而从目录结构上看crate 内部也自带cli.rs与main.rs见 src 目录其主要用途是对格式化行为做独立调试与基准化。用户在命令行中真正触达的入口是crates/ruff/src/commands/format.rs文件/目录格式化与crates/ruff/src/commands/format_stdin.rs标准输入流格式化所实现的ruff format命令。在仓库内该 crate 的顶层使用方式沉淀在 docs/formatter.md 中。基本调用非常直接ruff format # Format all files in the current directory. ruff format path/to/code/ # Format all files in path/to/code (and any subdirectories). ruff format path/to/file.py # Format a single file.与 Black 的行为一致ruff format path/to/file.py会就地改写文件而ruff format --check path/to/file.py只做检查、不写回文件一旦发现存在未格式化的文件就以非零退出码结束。完整选项可用ruff format --help查看。二、设计目标做 Black 的 drop-in 替代但聚焦性能与工具链统一1. 三条核心目标根据 crate READMERuff formatter 的设计目标可归纳为三点作为 Black 的 drop-in 替代在已经用 Black 格式化过的代码上运行 Ruff期望产出与 Black 近乎一致的输出。官方文档给出的量化说明是在 Django、Zulip 这类大规模、长期使用 Black 格式化的项目上运行时超过 99.9% 的行被格式化得与 Black 完全相同该数据出自 crates/ruff_python_formatter/README.md 及 docs/formatter.md 对 Black 兼容性的陈述。把性能当作首要创新点Ruff formatter 的初始目标不是去发明一种新的代码风格而是在性能上做创新同时把 lint、format 以及未来的工具统一到一条工具链上。追求最小迁移扰动由于 Black 在 Python 生态中的流行度以 Black 兼容为目标可以确保项目从 Black 迁移到 Ruff 时绝大多数代码保持不变。README 也明确指出迁移时在边缘情况上会遇到少量差异但不应期待大范围改动。2. 偏差的分层处理策略README 对偏差给出了两条处理路径这个区分非常关键有意偏差intentional deviations先对照仓库内的已知偏差清单Known Deviations from Black逐条核验。这些是 Ruff 有意为之的差异多数出现在Ruff 的行为被认为更一致或在底层实现差异下显著更简单、且对终端用户影响可忽略的场景。无意偏差unintentional deviations若确认是 Bug 类偏差则应作为 issue 提交到项目问题跟踪器README 中附有以formatter标签检索与新建 issue 的指引供维护者修复。另外README 特别提醒在未经 Black 格式化过的代码上运行 Ruff 时Ruff 会做出一些与 Black 不同的决策因此会看到更多偏差尤其是**行尾注释end-of-line comments**的处理方式。这正是稳定输入上高度一致、非标准输入上存在风格差异的行为边界。3. 风格参照Black 的稳定代码风格在设计哲学上Ruff formatter 遵循 Black 的稳定版代码风格其美学取向是一致性、通用性、可读性、减少 git diff。README 没有自带风格示例仓库文档 docs/formatter.md 给出了一个直观的前后对比_make_ssl_transport长参数列表可以看到 Ruff 将每个参数独占一行、统一缩进、把文档字符串由单引号改为双引号等行为与 Black 的稳定风格一致# Input一段参数拥挤、缩进混乱的代码 def _make_ssl_transport( rawsock, protocol, sslcontext, waiterNone, *, server_sideFalse, server_hostnameNone, extraNone, serverNone, ssl_handshake_timeoutNone, call_connection_madeTrue): Make an SSL transport. if waiter is None: waiter Future(looploop) ... # Ruff 格式化输出 def _make_ssl_transport( rawsock, protocol, sslcontext, waiterNone, *, server_sideFalse, server_hostnameNone, extraNone, serverNone, ssl_handshake_timeoutNone, call_connection_madeTrue, ): Make an SSL transport. if waiter is None: waiter Future(looploop) ...三、与 Black 的兼容边界已知有意偏差速览docs/formatter/black.md完整枚举了 Ruff 相对 Black 的所有有意偏差全文 800 余行。理解这些偏差是项目从 Black 迁移到 Ruff 时评估那 0.1% 差异会不会落在我的代码上的关键。摘取几条最具代表性的完整清单请直接阅读 docs/formatter/black.md行尾注释Trailing end-of-line commentsBlack 优先把整条语句压缩进一行并把注释挪到折叠语句末尾可能改变注释语义Ruff 效仿 Prettier会展开任何含有行尾注释的语句让注释留在贴近原始位置的地方代价是保留更多纵向空间。计算行宽时忽略 pragma 注释# type、# noqa、# pyright、# pylint等 pragma 注释不参与行宽计算从而避免 Ruff 搬动注释、改变其抑制/注解范围例如# noqa被移到行尾会同时压制first()与second()的错误。这类似 Pyink但与 Black 不同。行宽计算口径Ruff 用 Unicode 宽度display width判断一行是否放得下字符串、标识符与注释均按 Unicode 宽度计算而 Black 对非字符串 token 使用字符数。F-stringsBlack 不格式化 f-string 花括号{...}内的表达式部分而 Ruff 会格式化Ruff 0.9.0 起稳定详见偏差清单中的 F-strings 小节。不保留过长嵌套表达式外层括号、调用中单个多行字符串参数的缩进处理、assert/global/nonlocal语句的断行方式等均与 Black 存在细节差异。也就是说drop-in是就 Black-formatted 代码这一稳定输入而言的一旦输入本身不符合 Black 风格Ruff 与 Black 在边缘上的不同决策就会被放大这正是文档要求迁移用户逐条核对偏差清单的原因。四、内部实现源码级解读格式化流水线1. crate 模块划分从 src 目录结构 可以清楚看到该 crate 按 Python 语法范畴组织格式化规则是典型的每种 AST 节点一个格式化规则架构statement/语句级规则如stmt_if.rs、stmt_function_def.rs、stmt_class_def.rs、stmt_with.rs、stmt_match.rs等expression/表达式级规则覆盖调用、二元运算、推导式、f-string、lambda、字典、元组、切片等pattern/match语句的模式匹配格式化comments/注释的放置placement.rs、映射与格式化含大量独立快照测试string/字符串与文档字符串处理docstring.rs、normalize.rs、implicit.rsmodule/、type_param/、builders.rs、context.rs、verbatim.rs模块级、类型参数、公共 builder、格式化上下文与原样输出verbatim例如fmt: off区域。这种一节点一规则的结构配合统一的FormatNodeRuleNtrait定义于 lib.rs使每条格式化规则都遵循同一范式先输出节点前置注释leading comments再输出字段格式化结果最后兜底断言并输出后置注释trailing comments与 source map 位置标记。2. 顶层流水线parse → trivia → format → printlib.rs 中的format_module_source是理解整个格式化主流程的最佳起点pub fn format_module_source( source: str, options: PyFormatOptions, ) - ResultPrinted, FormatModuleError { let source_type options.source_type(); let parsed parse(source, ParseOptions::from(source_type))?; let trivia TriviaRanges::from(parsed.tokens()); let formatted format_module_ast(parsed, trivia, source, options)?; Ok(formatted.print()?) }完整链路为先用ruff_python_parser把源码解析为 AST同时保留 token 信息再由ruff_python_trivia::TriviaRanges从 token 流构造注释/空白等trivia区间注释、空行信息在此被单独管理这正是 Ruff 能在格式化的同时妥善处理行尾注释与 pragma 的原因之一随后将 AST 与 trivia 交给格式化器产出中间格式文档Formatted对应ruff_formattercrate 的 IR 文档模型最后由 printer 打印为最终文本。若源码无法解析为合法 Python或打印过程出错则统一包装为FormatModuleError源码中同时实现了到Diagnostic的转换供上层工具展示诊断信息。3. 配置模型的底层形态PyFormatOptions格式化一个文件的全部决策参数收敛在 options.rs 的PyFormatOptions中。它区别于面向整个项目/子目录的设置是解析完配置后落到单个文件上的最终快照。从源码可见其字段与默认值与Default实现一致字段默认值说明source_type随扩展名推导.py与.pyi类型存根遵循不同规则target_version默认 Python 版本决定哪些语法可用如 3.12 的 PEP 701 嵌套 f-stringindent_styleSpace空格空格或 Tabindent_width4一个 Tab 或缩进级别的可视宽度line_width88换行阈值与 Black 默认一致line_ending平台默认换行符风格quote_styleDouble双引号或单引号偏好magic_trailing_comma遵循 Black 语义决定(a, b,)这类魔幻尾逗号是否触发展开source_map_generation关闭是否生成源位置→格式化后位置的映射范围格式化等高级能力用docstring_code关闭opt-in是否格式化文档字符串中的 Python 代码示例docstring_code_line_widthdynamic文档字符串代码示例的行宽dynamic表示跟随外层代码行宽preview关闭是否启用预览风格nested_string_quote_stylealternatingPython 3.12 嵌套字符串的引号策略这些字段与quote_style、nested_string_quote_style等枚举在 lib.rs 中被公开 re-export作为格式化库的能力边界。4. 从库到 CLIruff format的命令实现在ruff侧format.rs 承接文件发现与任务调度收集目标文件含对 Python、Jupyter Notebook、Markdown 等类型的识别与过滤多线程执行格式化统计已格式化/未变更并处理--check、--diff、--exit-non-zero-on-format等标志format_stdin.rs 则面向管道输入如编辑器与 pre-commit 场景。关于退出码约定仓库文档 docs/formatter.md 给出精确语义可直接用于 CI 判断ruff format0表示正常结束无论是否改动了文件1表示正常结束且至少一个文件被格式化、同时指定了--exit-non-zero-on-format2表示配置非法、CLI 选项非法或内部错误。ruff format --check0表示没有文件需要格式化1表示存在至少一个需要格式化的文件2表示异常终止。五、配置指南在 pyproject.toml 或 ruff.toml 中调整格式化行为尽管 Ruff formatter 不提供 YAPF 式的大规模风格定制但它支持配置引号风格、缩进风格、行宽、行尾、文档字符串内代码格式化等。这一点与 Black 形成对照Black 几乎不可配置Ruff 则开放了若干 Black 所没有的选项源码字段与文档配置项一一对应见 options.rs。仓库文档 docs/formatter.md 给出的综合示例单引号 Tab 缩进 行宽 100 格式化文档字符串中的代码示例# pyproject.toml [tool.ruff] line-length 100 [tool.ruff.format] quote-style single indent-style tab docstring-code-format true# ruff.toml line-length 100 [format] quote-style single indent-style tab docstring-code-format true关于配置文件的整体解析机制可以进一步参考 docs/configuration.md 与ruff_workspacecrate负责pyproject.toml/ruff.toml的发现、分层与合并本仓库的ruff.schema.json亦为格式化选项的完整 JSON Schema 约束。六、版本化与稳定性内部 crate 的使用边界关联 README 的 Versioning 段落crates/ruff_python_formatter/README.md是对使用者最重要的契约声明其要点如下该段落在源码仓库中以BEGIN/END GENERATED CRATE VERSIONING标记自动维护本 crate 是Ruff 的内部组件internal component对应的 Rust 公共 API不稳定会频繁发生破坏性变更当前版本为0.0.12与 Cargo.toml 一致是Ruff 0.16.6见 crates/ruff/Cargo.toml的组成部件版本化遵循 Ruff 的 crate 版本化策略crate versioning policy。给集成方的两条实操建议由此而来其一不要直接以 Rust 库的方式依赖ruff_python_formatter的 API 编写长期代码因为它随时可能重构其二日常使用应始终通过随ruff一起发布的ruff format命令把格式化功能当作 CLI 能力而非稳定库 API 来消费这样 crate 内部如何演进都不会影响你的使用方式。七、质量保障体系快照测试与格式化偏差的实证追踪ruff_python_formatter拥有非常重的测试资产这是与 Black 兼容这个目标能被工程化验证的基础测试入口tests/fixtures.rs 以datatest-stable驱动Cargo.toml 中声明了独立的fixturestest target对tests/snapshots/下 260 个快照文件逐一执行输入 → 格式化 → 与期望输出比对快照资产tests/snapshots 覆盖各类 Python 语法与边界情况注释专项src/comments/snapshots/下存放了 30 余个注释处理专项快照覆盖前导/尾随/悬空注释、if/elif/else注释、try/except注释、match分支注释、嵌套二元表达式注释等说明注释放置是格式化正确性的高敏感区一致性快照src/snapshots还包含string_processing之类的处理级快照。这种每种语法结构 每种注释位置 若干真实风格样例组合出来的快照矩阵正是 Ruff formatter 能对非 Black 输入也保持可预期、可回归的核心机制。八、扩展能力与协同使用1. 文档字符串代码与 Markdown 代码块的格式化opt-in除普通 Python 文件外Ruff formatter 还提供可选的文档内代码格式化其能力边界由 src/string/docstring.rs 等实现文档细节见 docs/formatter.mddocstring 代码示例能识别 Python doctest、CommonMark fenced code blockinfo string 为python/py/python3/py3无 info string 的代码块默认按 Python 处理、reStructuredText literal block以及code-block/sourcecode指令。若示例解析失败、或重排后产生非法 Python则自动跳过不改。行宽跟随默认docstring-code-line-length dynamic即示例内行宽跟随外层代码的line-length保证缩进过的文档字符串里换行也不超限也可固定行宽例如[tool.ruff.format] docstring-code-format true docstring-code-line-length 20Markdown 文件ruff format会格式化 Markdown 中的 Python fenced code blocks含pyi存根风格与pyconREPL 风格也支持 Quarto 风格{python}花括号 info string。若要处理.md以外的扩展名可用extension映射如把.mdx、.qmd归为markdown要整体禁用 Markdown 格式化则把*.md加入extend-exclude。通过ruff-pre-commit使用时需要在types_or里显式追加markdown。2. 格式化抑制# fmt: off/# fmt: on/# fmt: skip与 Black 一致Ruff 支持三种 pragma也兼容 YAPF 的# yapf: disable/# yapf: enable但在作用域语义上有明确规则详见 docs/formatter.md 的 Format suppression 一节# fmt: on/# fmt: off在语句级生效——写在表达式内部例如列表元素之间不会起任何作用必须把整条语句包裹起来# fmt: off not_formatted3 also_not_formatted4 # fmt: on# fmt: skip作用于 case 头、装饰器、函数/类定义头或同一逻辑行上前面的语句放在表达式末尾同样无效需作用于整条语句if True: pass elif False: # fmt: skip pass a [1,2,3,4,5] # fmt: skip def test(a,b,c,d,e,f) - int: # fmt: skip pass x1;x2;x3 # fmt: skipMarkdown 代码块内部除普通 pragma 外还可用!-- fmt:off --/!-- fmt:on --以及 blacken-docs 风格的!-- blacken-docs:off/on --成对包裹代码块未闭合的off注释会覆盖文档剩余部分。从实现侧看verbatim原样保留能力由 src/verbatim.rs 支撑# fmt: skip等注释的识别入口可从 comments 模块的has_skip_comment与注释放置逻辑src/comments/placement.rs中找到。3. 与 linter 协同排序导入与冲突规则Ruff formatter不做导入排序文档给出的推荐做法是先用 linter 修Iisort再格式化ruff check --select I --fix ruff format同时formatter 与若干 lint 规则存在天然张力详见 docs/formatter.md 的 Conflicting lint rules 一节若启用了缩进类W191/E111/E114/E117、引号类Q000–Q004、D300、D206等、尾逗号类COM812/COM819等规则格式化产物可能反过来触发新的 lint 报错。Ruff 的兼容性目标是运行 formatter 不应引入新的 lint 错误因此官方建议避免启用上述规则并避免把 isort 的force-single-line、force-wrap-aliases、lines-after-imports等选项设为非默认值——当检测到不兼容配置时ruff format会打印警告无警告即代表配置安全。4. Preview 风格渐进式风格演进与 Black 的 preview style 机制类似Ruff 将尚未转正的格式化风格放在preview模式 下试验通过次版本发布逐步转正。仓库中 src/preview.rs 是该机制的实现载体。docs/formatter.md 给出过一个直观例子——方法链的 fluent layout预览风格当df.filter(cond).agg(func).merge(other)这类链式调用超过行宽时预览风格选择在首个属性访问之前断行.filter单独缩进一行突出对固定对象df的连续变换这一语义而稳定风格与 Black 一致则把首个调用留在首行。对同一段代码两种风格的选择差异只在属性访问与紧随其后的调用/下标的断行位置上这正体现了 preview 模式下风格演进的收敛与克制。结语ruff_python_formatter的设计取舍可以浓缩为一句话风格上不创新、实现上创新——以 Black 稳定风格为兼容基线、以 99.9% 行级一致官方对 Django/Zulip 等大型项目的声明数据为兼容标尺把工程能量投入格式化的正确性、可回归性与工具链统一而不是另起炉灶发明代码风格。如果你打算把项目从 Black 迁移到 Ruff建议依次做三件事对照已知偏差清单评估你的代码形态在 CI 中用ruff format --check接替 Black 的--check遇到非预期差异时先在仓库的格式化快照测试中确认是否属于已覆盖场景再决定是按偏差清单理解它、还是反馈给上游修复。【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考