使用 Ruff 在指定目录中忽略特定规则

本文介绍了如何使用 Ruff 工具在 Python 项目中，针对特定目录或文件，忽略指定的规则。通过 pyproject.toml 配置文件中的 per-file-ignores 设置，可以灵活地控制 Ruff 的检查行为，例如忽略测试目录下的文档字符串规范检查。

Ruff 是一款快速的 Python 代码检查工具，可以进行代码格式化和 linting。在实际项目中，我们可能需要在某些特定目录或文件中忽略某些规则，以满足特定的需求或兼容现有的代码风格。Ruff 提供了 per-file-ignores 配置项，允许我们针对单个文件或目录树指定需要忽略的规则。

配置 per-file-ignores

per-file-ignores 配置项位于 pyproject.toml 文件中的 tool.ruff.lint 部分。它是一个键值对，键是文件或目录的模式，值是一个包含需要忽略的规则的列表。

[tool.ruff.lint.per-file-ignores]

忽略特定文件中的特定规则

要忽略特定文件中的特定规则，可以使用以下语法：

[tool.ruff.lint.per-file-ignores]
"foofile.py" = ["E501"]

这个配置表示在 foofile.py 文件中忽略 E501 规则（通常是行长度超限）。

忽略整个目录树中的一类规则

要忽略整个目录树中的一类规则，可以使用通配符 * 来匹配目录，并指定规则的字母类别。例如，要忽略 tests/ 目录下所有文件的 pydocstyle 错误（规则以 “D” 开头），可以使用以下配置：

[tool.ruff.lint.per-file-ignores]
"tests/*" = ["D"]

这个配置表示在 tests/ 目录及其所有子目录下的所有文件中，忽略所有以 “D” 开头的规则，即 pydocstyle 相关的规则。

示例

假设我们的项目结构如下：

.
├── LICENSE
├── pyproject.toml
├── README.md
├── src
│   └── mypackage/mymodule.py
└── tests
   ├── doc.md
   └── test_mymodule.py

如果我们想在 tests/ 目录下忽略 pydocstyle 规则，可以在 pyproject.toml 文件中添加以下配置：

[tool.ruff.lint.per-file-ignores]
"tests/*" = ["D"]

这样，Ruff 在检查 tests/ 目录下的文件时，将不会报告 pydocstyle 相关的错误。

注意事项

• per-file-ignores 配置项中的模式是相对于项目根目录的。
• 可以使用多个模式来匹配不同的文件或目录。
• 规则列表可以包含单个规则或规则的字母类别。
• 详细的配置信息可以参考 Ruff 官方文档：Ruff Configuration.

总结

per-file-ignores 是 Ruff 中一个非常实用的配置项，可以帮助我们灵活地控制 Ruff 的检查行为，使其更好地适应不同的项目需求。通过合理地使用 per-file-ignores，我们可以提高代码质量，同时避免不必要的警告和错误。