驯服代码格式：如何让 Ruff 的链式调用优雅换行？

为什么链式调用的多行格式如此重要？

在编写 Python 代码时，链式调用（Chained Method Calls）是一种非常优雅的写法。它允许我们将多个操作串联起来，像流水线一样处理数据。例如：

PYTHON
result = data.fetch().filter(condition).sort_by('date').limit(10).to_list()

然而，当这条“流水线”变得过长时，单行代码就会像拥挤的地铁车厢一样，难以阅读和维护。此时，将链式调用拆分为多行是提升代码可读性的关键。

但在使用 ruff format 进行代码格式化时，你可能会发现它倾向于将链式调用压缩成单行（如果长度允许）。这有时会违背我们对代码清晰度的追求。本文将带你一步步解决这个问题。

理解 Ruff 的格式化逻辑

ruff format 遵循 PEP 8 风格指南，但为了保持代码的整洁，它通常会尝试将表达式压缩在一行内，除非行宽超过预设限制（默认为 88 字符）。

然而，逻辑的清晰度有时比严格遵循行宽限制更重要。对于复杂的链式调用，强制多行能让读者更轻松地理解每一步的操作。

解决方案：手动控制与配置调整

ruff format 目前没有一个直接的配置选项（如 force-multiline-chained-calls = true）来强制所有链式调用换行。因此，我们需要结合代码微调和配置优化来达到目的。

方法一：利用括号强制换行（最推荐）

这是最简单且最有效的方法。ruff 会尊重括号内的换行。通过将链式调用包裹在圆括号中，你可以明确地告诉格式化工具：这里需要多行显示。

操作步骤：

识别过长的链式调用：找到那些读起来费劲的单行链式调用。
添加外层括号：在链式调用的最外层加上 ( 和 )。
手动换行：在每个点号（.）后按回车键。

对比示例：

格式化前（Ruff 可能保持单行）：

PYTHON
# 这一行很长，阅读困难
long_string = " ".join([str(i) for i in range(100)]).replace("0", "zero").upper().strip()

格式化后（添加括号强制多行）：

PYTHON
# 使用括号包裹，Ruff 会保留你的换行意图
long_string = (
    " ".join([str(i) for i in range(100)])
    .replace("0", "zero")
    .upper()
    .strip()
)

比喻：想象你在写一封长信。如果把所有话挤在一段里，读者会晕头转向。加上括号并换行，就像是分段书写，让逻辑呼吸。

方法二：调整配置文件（`pyproject.toml`）

虽然 Ruff 没有直接的选项来强制链式调用换行，但我们可以通过调整全局行宽限制，间接鼓励更长的表达式使用多行。

默认行宽是 88。如果你希望代码更宽松，可以增加这个值，但这通常不是解决链式调用的最佳方案。相反，缩短行宽有时反而能迫使 Ruff 将长链式调用换行（如果它超过了限制）。

不过，最实用的配置策略是结合 Linter 规则。

配置示例：

在你的 pyproject.toml 中：

TOML
[tool.ruff]
# 设置行宽，如果你希望更紧凑的代码，可以设大一点，但默认 88 通常足够
line-length = 88

# 启用一些有助于代码清晰度的 Linter 规则
# 虽然它们不直接格式化，但能提醒你代码结构问题
select = [
    "E",  # PEP 8 错误
    "F",  # Pyflakes
    "W",  # 警告
]

注意：单纯修改 line-length 并不能保证链式调用一定会换行。如果链式调用刚好在限制内，Ruff 依然会保持单行。因此，方法一（手动加括号）是目前最可靠的手段。

方法三：使用 Ruff 的代码修复功能

虽然 Ruff Format 主要负责格式化，但 Ruff 的 Linter 功能（ruff check --fix）非常强大。虽然没有专门针对“链式调用换行”的规则，但保持代码符合 PEP 8 有助于整体风格的统一。

如果你使用的是 VS Code 或其他 IDE，安装 Ruff 插件后，通常可以通过以下方式辅助：

自动折行设置：在编辑器设置中，开启 "Word Wrap"。这只影响视觉显示，不改变文件内容，但对于阅读长链式调用很有帮助。

最佳实践建议

可读性优先：不要为了换行而换行。如果链式调用很短（例如只有两步），保持单行是完全可以的。

对齐点号：在多行链式调用中，将点号（.）放在新行的开头，并垂直对齐。这能提供极佳的视觉引导。

PYTHON
# 良好的对齐
query = (
    session.query(User)
    .filter(User.age > 18)
    .order_by(User.created_at.desc())
    .limit(10)
)

一致性：在同一个项目或文件中，保持风格一致。如果决定使用括号包裹链式调用，那么所有类似的长链式调用都应如此处理。

总结

ruff format 是一个高效的工具，但它不会读心术。当你希望链式调用保持多行时，最直接的方法是使用圆括号包裹代码并手动换行。这不仅利用了格式化工具对括号的尊重，也让你能精确控制代码的布局。

记住，工具是为人服务的。当自动格式化无法满足特定的可读性需求时，灵活地结合手动调整是成熟开发者的标志。

希望这篇文章能帮你更好地驾驭 ruff format，写出既规范又易读的 Python 代码！