Ruff v0.5.0 现已可用！可以从 PyPI 或您选择的包管理器安装。

pip install --upgrade ruff

提醒一下：Ruff 是一个用 Rust 编写的超快速 Python 代码检查器和格式化工具。Ruff 可以用来替代 Black、Flake8（以及数十个插件）、isort、pydocstyle、pyupgrade 等工具，而且执行速度比任何单个工具快数十倍或数百倍。

迁移到 v0.5

在大多数情况下，您应该能够无缝升级到 Ruff v0.5，无需进行任何更改。尽管如此，此版本仍包含一些弃用和重大变更，可能需要在升级时采取行动。

此版本中最显著的重大变更包括

输出格式现默认为 full

Ruff 用于报告代码检查违规的确切格式可以使用 --output-format 选项进行配置。Ruff v0.2 引入了一个新选项 --output-format=full：与其他格式不同，它会显示触发代码检查违规的代码片段以及违规的错误代码和错误消息。当您尝试解决 Ruff 报告的违规问题时，这可以提供重要的上下文信息。

我们希望我们的诊断信息尽可能具有信息性和可操作性，因此此版本将 --output-format=full 设置为 Ruff 的默认行为。将来，此更改还将使我们能够在报告违规时显示建议的修复方案，进一步改善用户体验。

新的默认违规格式如下所示

❯ ruff check
bundled/tool/ruff_server.py:2:8: F401 [*] `pathlib` imported but unused
  |
1 | import os
2 | import pathlib
  |        ^^^^^^^ F401
3 | import shutil
4 | import site
  |
  = help: Remove unused import: `pathlib`

Found 1 error.
[*] 1 fixable with the `--fix` option.

使用 --output-format=concise 或 RUFF_OUTPUT_FORMAT 环境变量可以回到不带代码片段的更简洁输出。

❯ ruff check --output-format=concise
bundled/tool/ruff_server.py:2:8: F401 [*] `pathlib` imported but unused
Found 1 error.
[*] 1 fixable with the `--fix` option.

选择 ALL 现在排除已弃用的规则

ALL 选择器是从命令行或通过配置文件启用所有 Ruff 规则的简便方法。在 Ruff 的早期版本中，我们将其理解得相当字面化——在命令行上使用 --select=ALL 会选择所有 Ruff 规则，甚至包括已弃用的规则！这反过来可能导致 Ruff 发出关于选择了已弃用规则的警告。

选择 ALL 现在会选择所有 Ruff 规则，除了任何已弃用的规则。我们预计这正是大多数使用 --select=ALL 的用户一直以来想要的。已弃用的规则仍然可以启用，但您现在必须在命令行或配置文件中明确指定它们。

ruff check my_code.py --select=ALL,DEPRECATED_RULE001

macOS 上现使用 XDG 规范

此前，Ruff 在 macOS 上从 ~/Library/Application Support/ruff/ruff.toml 中发现用户级配置，并在其他 Unix 系统上遵循 XDG 规范（默认为 ~/.config/ruff/ruff.toml）。Ruff 现在在所有 Unix 平台（包括 macOS）上都遵循 XDG 规范。

升级时，如果您的用户级配置文件存储在 Application Support/ruff 目录中，Ruff 会告知您并提供有关如何移动配置文件的提示。

规则重新映射

Ruff 的许多规则是其他旧工具的 Lint 规则的重新实现。有时这意味着我们需要合并重叠的规则、移除重复的规则，或为了与其他代码检查工具保持一致性而重命名规则。

此版本将 [flake8-trio] 和 flake8-async 类别合并为一个 flake8-async 类别，这是由于许多这些规则最初派生自的 flake8 插件的合并。这两个类别中的所有规则都已重新映射到新的代码。

flake8-async

  • blocking-http-call-in-async-function: ASYNC100 已重新映射到 ASYNC210
  • open-sleep-or-subprocess-in-async-function: ASYNC101 已被拆分为 ASYNC220、ASYNC221、ASYNC230 和 ASYNC251
  • blocking-os-call-in-async-function: ASYNC102 已合并到 ASYNC220 和 ASYNC221

flake8-trio

尝试使用已弃用的 TRIO 代码选择规则将导致 Ruff 发出警告；但是，Ruff 会自动将已弃用的代码映射到更新后的代码。旧的 ASYNC100、ASYNC101、ASYNC102 或 ASYNC1 代码需要手动更新为其新的 ASYNC2XX 代码。

除了 ASYNC 和 TRIO 的重新映射外，repeated-isinstance-calls 也已从 PLR1701 重新映射到 SIM101。

E999 和语法错误报告的变更

在 Ruff v0.4.0 之前，如果 Ruff 遇到单个语法错误，它会立即停止解析 Python 文件。这意味着 Ruff 的代码检查器只会报告一个关于无效语法的违规，即使文件中存在多个语法错误。随着 Ruff v0.4.0 中新手动编写的解析器的发布，Ruff 可以从语法错误中恢复并继续解析文件。这意味着 Ruff 现在可以报告文件中所有的语法错误，而不仅仅是第一个。

E999 规则曾用于报告语法错误，允许用户通过 Ruff 的禁用机制来抑制这些报告。此版本弃用 E999 规则，该规则将在未来版本中移除。Ruff 现在将始终报告它遇到的所有语法错误，这意味着用户将无法再忽略它们。这一更改的动机是确保用户始终了解语法错误，因为这些错误会阻碍正常的代码检查。通过强制报告语法错误，我们消除了用户错过这些关键问题的风险。

为了应对这一变化，我们建议您移除任何对 E999 规则的禁用，因为它将不再有任何效果。您可以使用我们的 unused-noqa 规则和自动修复功能来自动移除代码中任何未使用的 noqa: E999 注释。

新服务器设置：showSyntaxErrors

既然 Ruff 始终报告语法错误，我们理解一些用户可能希望在编辑器中隐藏这些诊断信息。这在使用多个 Python 语言服务器时尤为相关，Ruff 是其中之一：多个服务器都抱怨相同的语法错误可能会造成混乱的用户体验。

为了适应这种用例并让用户更好地控制其编辑器体验，此版本引入了一个新的 showSyntaxErrors 服务器设置。此设置默认为 true，用于控制是否在编辑器中显示语法错误诊断信息。

在 Ruff 的 VS Code 扩展中，您可以使用 ruff.showSyntaxErrors 设置进行配置。

{
  "ruff.showSyntaxErrors": false
}

在使用新的 ruff server 或 ruff-lsp 的其他编辑器中，您可以使用 showSyntaxErrors 服务器设置进行配置。例如，在 Neovim 中您可以使用以下配置：

require('lspconfig').ruff.setup({
  init_options = {
    settings = {
      showSyntaxErrors = false
    },
  },
})
-- Same configuration for `ruff_lsp`

--statistics 现在显示规则名称

ruff check --statistics 可用于获取一份报告，汇总您项目中所有按代码检查规则分组的违规。此报告的格式现已更改，以在规则代码旁边显示规则名称。新格式如下所示：

❯ ruff check . --statistics
236 W191    [ ] tab-indentation
 85 PLR2004 [ ] magic-value-comparison
 84 UP031   [*] printf-string-formatting
 81 PLR0913 [ ] too-many-arguments
 73 RUF012  [ ] mutable-class-default
 65 Q000    [*] bad-quotes-inline-string

以前，Ruff 显示的是第一次违规的错误消息，而不是规则名称。然而，这有时可能导致奇怪的结果，因为同一规则的不同违规之间消息可能有所不同。例如：

❯ ruff check . --statistics
236 W191    [ ] Indentation contains tabs
 85 PLR2004 [ ] Magic value used in comparison, consider replacing `-128` with a constant variable
 84 UP031   [*] Use format specifiers instead of percent format
 81 PLR0913 [ ] Too many arguments in function definition (10 > 5)
 73 RUF012  [ ] Mutable class attributes should be annotated with `typing.ClassVar`
 65 Q000    [*] Double quotes found but single quotes preferred

稳定规则

以下规则已稳定，不再处于预览状态：

还有许多新的规则仍在预览中。我们强烈建议您查看它们！您可以 开启预览并逐个选择规则。

稳定行为

在此版本中，我们的一些稳定代码检查规则的范围得到了显著扩展或缩小。当我们发现需要进行此类更改时，我们通常会在多个次要版本中仅在预览模式下进行（即使是稳定规则），然后才将行为更改“提升”到稳定模式，以便所有用户都能从中受益。

以下行为更改已在 Ruff v0.5 中提升为稳定版：

已移除的弃用功能

此版本移除了对以下弃用功能的支持：

命令行界面

  • ruff <path>：请使用 ruff check <path>
  • ruff --clean：请使用 ruff clean
  • ruff --generate-shell-completion：请使用 ruff generate-shell-completion

设置

  • output-format=text 和 show-source
    • 当 show-source=true 时：请使用 output-format=full
    • 当 show-source=false 时：请使用 output-format=concise
    • 没有 show-source 时：我们推荐使用 output-format=full，但 concise 也可用。
  • tab-size=<size>：请使用 indent-width=<size>

升级时，如果使用到这些命令或设置中的任何一个，Ruff 会通知您并建议您改用哪个命令或设置。

在 GitHub 上查看完整的更新日志。

了解更多关于 Astral — Ruff 背后的公司。

感谢 Micha Reiser 和 Dhruv Manilawala，他们都为这篇博客文章做出了贡献。