Ruff 项目中的代码格式化工具详解

Ruff 项目中的代码格式化工具详解

ruff 一个极其快速的 Python 代码检查工具和代码格式化程序，用 Rust 编写。 项目地址: https://gitcode.com/gh_mirrors/ru/ruff

前言

在 Python 开发中，代码格式化是保证代码风格一致性的重要环节。Ruff 项目提供了一个名为 Ruff Formatter 的代码格式化工具，它以极高的性能和与 Black 的高度兼容性著称。本文将深入解析 Ruff Formatter 的核心特性、使用方法和最佳实践。

Ruff Formatter 简介

Ruff Formatter 是一个极速的 Python 代码格式化工具，设计为 Black 的直接替代品。它作为 Ruff CLI 的一部分，通过 ruff format 命令提供。

核心特点

1. 超高性能：相比传统格式化工具，Ruff Formatter 的执行速度显著提升
2. Black 兼容：与 Black 的代码风格高度一致，确保平滑迁移
3. 一体化工具链：与 Ruff 的 linter 等其他工具无缝集成

基础使用

基本命令格式

ruff format                   # 格式化当前目录下所有文件
ruff format path/to/code/     # 格式化指定目录及其子目录下所有文件
ruff format path/to/file.py   # 格式化单个文件

检查模式

使用 --check 参数可以检查文件是否需要格式化而不实际修改文件：

ruff format --check /path/to/file.py

此模式下，如果发现需要格式化的文件，命令会返回非零状态码。

设计哲学

Ruff Formatter 的设计遵循以下原则：

1. 性能优先：在保持代码质量的前提下最大化执行效率
2. Black 兼容：确保与 Black 格式化结果的极高一致性（>99.9%）
3. 最小化配置：减少风格选项，保持团队代码一致性

代码风格示例

以下是一个格式化前后的对比示例：

# 格式化前
def _make_ssl_transport(
    rawsock, protocol, sslcontext, waiter=None,
    *, server_side=False, server_hostname=None,
    extra=None, server=None,
    ssl_handshake_timeout=None,
    call_connection_made=True):
    '''Make an SSL transport.'''
    if waiter is None:
      waiter = Future(loop=loop)

    if extra is None:
      extra = {}

# 格式化后
def _make_ssl_transport(
    rawsock,
    protocol,
    sslcontext,
    waiter=None,
    *,
    server_side=False,
    server_hostname=None,
    extra=None,
    server=None,
    ssl_handshake_timeout=None,
    call_connection_made=True,
):
    """Make an SSL transport."""
    if waiter is None:
        waiter = Future(loop=loop)

    if extra is None:
        extra = {}

配置选项

虽然 Ruff Formatter 强调最小化配置，但仍提供了一些关键选项：

常用配置项

[tool.ruff]
line-length = 100  # 行长度限制

[tool.ruff.format]
quote-style = "single"  # 引号风格：single/double
indent-style = "tab"    # 缩进风格：tab/space
docstring-code-format = true  # 是否格式化文档字符串中的代码示例

配置说明

1. 引号风格：可选择单引号或双引号
2. 缩进风格：支持制表符或空格缩进
3. 行长度：默认88字符，与 Black 一致
4. 文档字符串代码格式化：可选是否格式化文档字符串中的代码示例

文档字符串代码格式化

Ruff Formatter 提供了一个独特功能：自动格式化文档字符串中的代码示例。它支持多种文档字符串格式：

1. Python doctest 格式
2. CommonMark 围栏代码块（标记为 python/py/python3/py3）
3. reStructuredText 字面块
4. reStructuredText 的 code-block 和 sourcecode 指令

配置示例

[tool.ruff.format]
docstring-code-format = true
docstring-code-line-length = 20  # 文档字符串中代码的行长度限制

格式化示例

# 格式化前
def f(x):
    '''
    Something about `f`. And an example:

    .. code-block:: python

        foo, bar, quux = this_is_a_long_line(lion, hippo, lemur, bear)
    '''
    pass

# 格式化后
def f(x):
    """
    Something about `f`. And an example:

    .. code-block:: python

        (
            foo,
            bar,
            quux,
        ) = this_is_a_long_line(
            lion,
            hippo,
            lemur,
            bear,
        )
    """
    pass

格式化抑制

Ruff Formatter 支持通过特殊注释临时禁用格式化：

禁用方式

1. 代码块禁用：

   # fmt: off
   not_formatted=3
   also_not_formatted=4
   # fmt: on
   

2. 单行禁用：

   a = [1, 2, 3, 4, 5] # fmt: skip
   

注意事项

• # fmt: on/off 必须在语句级别使用
• Ruff 也兼容 YAPF 的 # yapf: disable/enable 注释

与 Linter 的兼容性

虽然 Ruff Formatter 设计为与 linter 协同工作，但某些 lint 规则可能导致冲突。建议禁用以下规则：

1. 缩进相关规则（如 W191、E111 等）
2. 引号相关规则（如 Q000-Q003）
3. 逗号相关规则（如 COM812、COM819）
4. 隐式字符串连接规则（ISC002）

最佳实践

1. 使用 ruff format 时检查警告信息
2. 通过 lint.ignore 设置禁用冲突规则
3. 避免修改 isort 的相关默认设置

退出代码说明

• 普通模式：

  • 0：成功执行（无论是否有文件被格式化）
  • 2：配置错误或内部错误

• 检查模式：

  • 0：没有需要格式化的文件
  • 1：发现需要格式化的文件
  • 2：配置错误或内部错误

风格指南

与 Black 的差异

虽然 Ruff Formatter 以 Black 兼容为目标，但在以下方面存在有意差异：

1. f-string 处理：Ruff 会格式化 f-string 中的表达式部分
2. 多行处理：对于 Python 3.12+，Ruff 采用更智能的多行断行策略
3. 引号处理：嵌套 f-string 中会交替使用引号风格

预览风格

类似于 Black，Ruff 通过 preview 标志引入实验性格式化特性，这些特性可能会在后续版本中稳定。

结语

Ruff Formatter 作为 Python 代码格式化领域的新秀，凭借其卓越的性能和与 Black 的高度兼容性，为开发者提供了高效的代码风格统一方案。通过合理的配置和使用，可以显著提升团队开发效率和代码质量。

ruff 一个极其快速的 Python 代码检查工具和代码格式化程序，用 Rust 编写。 项目地址: https://gitcode.com/gh_mirrors/ru/ruff