Ruff项目配置指南：深入理解Python代码检查与格式化配置

最新推荐文章于 2025-06-15 23:15:46 发布

娄妃元Kacey

最新推荐文章于 2025-06-15 23:15:46 发布

阅读量461

点赞数 3

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_00806/article/details/148325438

Ruff项目配置指南：深入理解Python代码检查与格式化配置

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

Ruff作为一款新兴的Python代码检查(linter)和格式化(formatter)工具，其强大功能很大程度上依赖于灵活的配置系统。本文将全面解析Ruff的配置机制，帮助开发者根据项目需求定制代码检查规则。

一、配置文件基础

Ruff支持三种配置文件格式，按优先级从高到低排序：

.ruff.toml - 项目级隐藏配置文件
ruff.toml - 标准项目配置文件
pyproject.toml - 兼容Python生态的标准配置文件

三种文件采用相同的配置结构，区别仅在于pyproject.toml需要在配置项前添加[tool.ruff]前缀。

默认配置解析

Ruff的默认配置相当于以下内容（以pyproject.toml格式为例）：

[tool.ruff]
# 排除常见忽略目录
exclude = [
    ".git", ".venv", "__pypackages__",
    "build", "dist", "node_modules"
]

# 代码风格设置（与Black保持一致）
line-length = 88
indent-width = 4
target-version = "py39"  # 默认Python 3.9

[tool.ruff.lint]
# 默认启用的规则集
select = ["E4", "E7", "E9", "F"]  # 基础pycodestyle和Pyflakes规则
ignore = []
fixable = ["ALL"]  # 所有规则都可自动修复
unfixable = []

# 允许下划线前缀的未使用变量
dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"

[tool.ruff.format]
# 格式化风格（与Black兼容）
quote-style = "double"
indent-style = "space"
skip-magic-trailing-comma = false
line-ending = "auto"
docstring-code-format = false  # 默认不格式化文档字符串中的代码示例

二、配置实战案例

案例1：扩展检查规则

[tool.ruff.lint]
# 1. 添加flake8-bugbear规则集
select = ["E4", "E7", "E9", "F", "B"]

# 2. 忽略行长度限制
ignore = ["E501"]

# 3. 禁止自动修复bugbear规则
unfixable = ["B"]

# 4. 文件级特殊规则
[tool.ruff.lint.per-file-ignores]
"__init__.py" = ["E402"]  # 忽略__init__.py中的导入顺序
"**/{tests,docs}/*" = ["E402"]  # 忽略测试和文档目录的导入顺序

[tool.ruff.format]
# 5. 使用单引号格式化
quote-style = "single"

案例2：插件配置

某些规则集需要额外配置参数：

[tool.ruff.lint]
select = ["E4", "E7", "E9", "F", "Q"]  # 启用flake8-quotes

[tool.ruff.lint.flake8-quotes]
docstring-quotes = "double"  # 文档字符串使用双引号

三、配置文件发现机制

Ruff采用类似ESLint的层级配置发现策略：

就近原则：对每个文件，使用其目录树中"最近"的配置文件
例外情况：
- 显式通过--config指定的配置具有最高优先级
- 未找到配置文件时，会检查用户级配置（~/.config/ruff/pyproject.toml）
- 命令行参数会覆盖所有配置文件设置

继承配置示例

可通过extend字段继承父目录配置：

# 继承父目录配置但修改行长度
extend = "../pyproject.toml"
line-length = 100

四、文件发现策略

默认包含文件类型

*.py - Python源文件
*.pyi - 类型存根文件
*.ipynb - Jupyter Notebook
pyproject.toml - 项目配置文件

可通过include和extend-include扩展支持的文件类型。

特殊文件处理

Jupyter Notebook配置：

# 仅检查不格式化.ipynb文件
[tool.ruff.format]
exclude = ["*.ipynb"]

# Notebook特定规则忽略
[tool.ruff.lint.per-file-ignores]
"*.ipynb" = ["T20"]  # 忽略Notebook中的T20规则

五、命令行接口详解

基本用法

# 检查指定目录/文件
ruff check path/to/code/

# 指定检查规则并静默输出
ruff check path/to/code/ --select F401 --select F403 --quiet

高级配置覆盖

# 通过CLI覆盖配置文件设置
ruff check path/to/file \
  --config "lint.dummy-variable-rgx = '__.*'" \
  --config "lint.per-file-ignores = {'some_file.py' = ['F841']}"