Refurb

一个用于翻新和现代化Python代码库的工具。

示例

# main.py

for filename in ["file1.txt", "file2.txt"]:
    with open(filename) as f:
        contents = f.read()

    lines = contents.splitlines()

    for line in lines:
        if not line or line.startswith("# ") or line.startswith("// "):
            continue

        for word in line.split():
            print(f"[{word}]", end="")

        print("")

运行:

$ refurb main.py
main.py:3:17 [FURB109]: 使用 `in (x, y, z)` 替代 `in [x, y, z]`
main.py:4:5 [FURB101]: 使用 `y = Path(x).read_text()` 替代 `with open(x, ...) as f: y = f.read()`
main.py:10:40 [FURB102]: 用 `x.startswith((y, z))` 替换 `x.startswith(y) or x.startswith(z)`
main.py:16:9 [FURB105]: 使用 `print()` 替代 `print("")`

安装

$ pipx install refurb
$ refurb file.py folder/

注意 Refurb 必须在 Python 3.10+ 上运行，但通过设置 --python-version 标志，它可以检查 Python 3.7+ 的代码。

检查项说明

你可以使用 refurb --explain FURB123，其中 FURB123 是你想查找的错误代码。例如:

$ refurb --explain FURB123
如果变量或字面量已经是该类型，就不要对其进行类型转换。例如：

不好的做法：

```
name = str("bob")
num = int(123)
```

好的做法：

```
name = "bob"
num = 123
```

所有可用检查项的在线列表可以在这里查看。

忽略错误

使用 --ignore 123 来忽略错误 123。错误代码可以是 FURB123 或 123 的形式。这个标志可以重复使用。

FURB 前缀表示这是一个内置错误。FURB 前缀是可选的，但对于所有其他错误（如 ABC123），前缀是必需的。

你也可以使用内联注释来禁用错误：

x = int(0)  # noqa: FURB123
y = list()  # noqa

这里，noqa: FURB123 特别忽略了该行的 FURB123 错误，而 noqa 忽略了该行的所有错误。

你也可以通过用逗号/空格分隔来指定多个要忽略的错误：

x = not not int(0)  # noqa: FURB114, FURB123
x = not not int(0)  # noqa: FURB114 FURB123

启用/禁用检查

某些检查默认是禁用的，需要先启用。你可以使用 --enable ERR 标志来做到这一点，其中 ERR 是你想启用的检查的错误代码。禁用的检查与忽略的检查不同，禁用的检查永远不会被加载，而忽略的检查会被加载，会发出错误，但错误会被抑制。

使用 --verbose/-v 标志获取已启用检查的完整列表。

--enable 的反面是 --disable，它将禁用一个检查。当通过命令行同时指定 --enable 和 --disable 时，最后一个会优先。当通过配置文件使用 enable 和 disable 时，disable 总是优先。

使用 --disable-all 标志禁用所有检查。这允许你根据需要逐步 --enable 检查，而不是添加一堆 --ignore 标志。要在配置文件中使用这个，将 disable_all 设为 true。

使用 --enable-all 标志默认启用所有检查。这允许你选择使用 Refurb（和 Refurb 插件）提供的所有检查。这对新代码库来说是一个不错的选择。要在配置文件中使用这个，将 enable_all 设为 true。

在配置文件中，首先应用 disable_all/enable_all，然后应用 enable 和 disable 字段。

注意 disable_all 和 enable_all 是互斥的，无论是在命令行还是在配置文件中。如果你尝试同时指定两者，将会得到一个错误。

你也可以使用 #category 语法按类别禁用检查。例如，--disable "#readability" 将禁用所有具有 readability 类别的检查。这同样适用于 enable 和 ignore。此外，如果你禁用了整个类别，你仍然可以显式地重新启用该类别中的某个检查。

注意 #readability 被引号包裹，因为你的 shell 会将 # 解释为注释的开始。

设置 Python 版本

使用 --python-version 标志告诉 Refurb 你的代码库使用的是哪个版本的 Python。这应该能更好地检测语言特性，并提供更好的错误信息。这个标志的参数必须是 x.y 的形式，例如，3.10。

在配置文件中使用这个的语法是 python_version = "3.10"。

当未指定 Python 版本时，Refurb 使用你本地 Python 安装的版本。例如，如果你的 python --version 是 3.11.5，Refurb 使用 3.11，删除了 5 补丁版本。

更改输出格式

默认情况下，所有内容都以纯文本输出：

file.py:1:5 [FURB123]: 用 `x` 替换 `int(x)`

以下是所有可用的格式：

text：默认格式
github：打印用于 GitHub Annotations 的输出
更多格式即将推出！

要更改默认格式，在命令行中使用 --format XYZ，或在配置文件中使用 format = "XYZ"。

更改排序顺序

默认情况下，错误按文件名排序，然后按错误代码排序。要更改这一点，在命令行中使用 --sort XYZ 标志，或在配置文件中使用 sort_by = "XYZ"，其中 XYZ 是以下排序模式之一：

filename：按字母顺序对文件排序（默认）
error：先按错误排序，然后按文件名排序

覆盖 Mypy 标志

这通常用于开发目的，但也可以用于从 Refurb 内部更好地微调 Mypy。-- 之后的任何命令行参数都会传递给 Mypy。例如：

$ refurb files -- --show-traceback

这告诉 Mypy 在崩溃时显示回溯。

你也可以在配置文件中使用这个，方法是将一个值数组赋给 mypy_args 字段。注意，通过命令行参数传递的任何 Mypy 参数都会覆盖配置文件中的 mypy_args 字段。

配置 Refurb

除了命令行参数，你还可以在 pyproject.toml 文件中添加你的设置。例如，以下命令行参数：

refurb file.py --ignore 100 --load some_module --quiet

对应于 pyproject.toml 文件中的以下内容：

[tool.refurb]
ignore = [100]
load = ["some_module"]
quiet = true

现在你只需要输入 refurb file.py！

注意，配置文件中的值将与通过命令行指定的值合并。对于像 --quiet 这样的布尔参数，命令行参数优先。所有其他参数（如 ignore 和 load）将被合并。

你可以使用 --config-file 标志告诉 Refurb 使用与默认 pyproject.toml 文件不同的配置文件。注意，它仍然必须与正常的 pyproject.toml 文件具有相同的形式。

点击这里查看一些示例配置文件。

按文件/文件夹忽略检查

如果你有一个大型代码库，你可能想忽略某些文件或文件夹的错误，这允许你根据需要逐步修复错误。要做到这一点，在你的 pyproject.toml 文件中添加以下内容：

# 这些设置将全局应用
[tool.refurb]
enable_all = true

# 这些只会应用于 "src" 文件夹
[[tool.refurb.amend]]
path = "src"
ignore = ["FURB123", "FURB120"]

# 这些只会应用于 "src/util.py" 文件
[[tool.refurb.amend]]
path = "src/util.py"
ignore = ["FURB125", "FURB148"]

注意，在 amend 部分中只有 ignore 字段可用。这是因为检查只能为整个代码库启用/禁用，不能在每个文件的基础上选择性地启用/禁用。假设一个检查已启用，你可以简单地为你选择的文件 ignore 错误。

与 `pre-commit` 一起使用 Refurb

你可以通过在 .pre-commit-config.yaml 文件中添加以下内容来与 pre-commit 一起使用 Refurb：

  - repo: https://github.com/dosisod/refurb
    rev: REVISION
    hooks:
      - id: refurb

将 REVISION 替换为你选择的版本或 SHA（或留空让 pre-commit 为你找到最新的版本）。

插件

为 Refurb 安装插件非常简单：

$ pip install refurb-plugin-example

其中 refurb-plugin-example 是插件的名称。Refurb 将自动加载任何已安装的插件。

要制作你自己的 Refurb 插件，请查看 refurb-plugin-example 仓库以获取更多信息。

编写你自己的检查

如果你想扩展 Refurb 但不想制作一个完整的插件，你可以使用 refurb gen 命令轻松创建一个一次性检查文件。

注意，此命令使用 fzf 模糊查找器来获取用户输入，所以在继续之前你需要安装 fzf。

以下是使用 refurb gen 命令创建新检查的基本概述：

首先选择你想接受的节点类型
然后输入你想保存自动生成文件的位置
在新文件中添加你的代码

要了解你需要在检查中添加什么，使用 --debug 标志来查看给定文件的 AST 表示（例如，refurb --debug file.py）。查看 refurb/checks/ 文件夹中的文件以获取一些示例。

然后，要加载你的新检查，使用 refurb file.py --load your.path.here

注意，当使用 --load 时，你需要在参数中使用点，就像导入普通的 python 模块一样。如果 your.path.here 是一个目录，该目录中的所有检查都将被加载。如果它是一个文件，只有该文件会被加载。

故障排除

如果 Refurb 运行缓慢，使用 --timing-stats 标志来诊断原因：

$ refurb file --timing-stats /tmp/stats.json

这将输出一个包含以下信息的 JSON 文件：

Mypy 解析模块所花费的总时间（通常是大部分时间）。
Mypy 解析每个模块所花费的时间。用于查找非常大/未使用的文件。
Refurb 检查每个模块所花费的时间。这些数字应该非常小（小于 100ms）。

较大的文件自然需要更长的时间来检查，但是花费太长时间的文件应该被调查，因为问题可能只在文件达到一定大小时才会显现。

禁用颜色

Refurb 默认启用颜色输出。要禁用它，请执行以下操作之一：

设置 NO_COLOR 环境变量。
使用 --no-color 标志。
在配置文件中设置 color = false。
将 Refurb 输出管道/重定向到另一个程序或文件。

可以使用 make 一次性运行所有测试，或者使用 make black、make flake8 等命令分别运行每个工具。

单元测试可以通过 pytest 或 make test 来运行。

由于端到端（e2e）测试较慢，在运行 make 时不会执行。你需要运行 make test-e2e 来执行它们。

更新文档

我们鼓励大家在发现拼写错误和其他问题时更新文档！

考虑到这一点，请不要直接修改 docs/checks.md 文件。它是自动生成的，在添加新的检查项时会被覆盖。检查项的文档可以通过修改检查项本身的文档字符串来更新。例如，要更新 FURB100，请修改 refurb/checks/pathlib/with_suffix.py 文件中 ErrorInfo 类的文档字符串。你可以通过 grep 搜索 code = XYZ 来找到特定检查项的文件，其中 XYZ 是你要查找的检查项代码，但需要去掉 FURB 前缀。

使用 --verbose 标志和 --explain 来找到特定检查项的文件名。例如：

$ refurb --explain FURB123 --verbose
Filename: refurb/checks/readability/no_unnecessary_cast.py

FURB123: no-redundant-cast [readability]

...

为什么会有这个项目？

我喜欢做代码审查：我喜欢把某样东西变得更好、更快、更优雅等。已经存在很多静态分析工具，但似乎没有一个专注于让代码更优雅、更易读或更现代化。这就是 Refurb 的用武之地。

Refurb 深受 Rust 内置 linter clippy 的启发。

Refurb 不是什么

Refurb 不是一个风格/类型检查器。它不是用于 linting 和发现 bug 的第一道防线，而是用于让好代码变得更好。

与其他工具的比较

已经有很多用于 linting 和分析 Python 代码的工具，所以你可能会想知道为什么会有 Refurb（保持怀疑态度是好事！）。如上所述，Refurb 检查可以让代码更优雅的地方，这是我所知的其他 linter 都不专注的领域。以下是一些类似的 linter 和分析器列表，以及它们与 Refurb 的区别：

Black：更专注于代码的格式和样式（行长、尾随逗号、缩进等）。它在让使用 Black 的其他项目看起来或多或少相同方面做得很好。它不做更复杂的事情，如类型检查或代码异味/反模式检测。

flake8：flake8 也是一个 linter，非常可扩展，并执行许多与语义分析相关的检查，如"未使用的变量"、"循环外的 break" 等。它还检查 PEP8 的一致性。Refurb 不会试图取代 flake8，因为你可能已经在使用 flake8 了。

Pylint 有很多检查项，涵盖了很多方面，但总的来说，它们专注于糟糕或有 bug 的代码，即你可能不是有意这样做的东西。Refurb 假设你知道自己在做什么，并会尽可能地清理已有的代码。

Mypy、Pyright、Pyre 和 Pytype 都是类型检查器，基本上只是强制执行类型，确保参数匹配，函数以类型安全的方式调用等。它们做的远不止这些，但这是大致的想法。Refurb 实际上是建立在 Mypy 之上的，并使用其 AST 解析器以获得良好的类型信息。

pyupgrade：Pyupgrade 有很多很好的检查项，用于将旧的 Python 代码升级到新的语法，这非常有用。Refurb 的不同之处在于，Pyupgrade 更专注于将代码升级到新版本，而 Refurb 更专注于清理和简化现有代码。

总之，Refurb 不希望你抛弃旧工具，因为它们涵盖了代码的不同领域，都有不同的用途。Refurb 旨在与上述工具一起使用。