3分钟上手Ruff：pyproject.toml配置最佳实践与完整示例
项目地址: https://gitcode.com/GitHub_Trending/ru/ruff 你还在为Python代码检查工具配置复杂而头疼吗？作为一款用Rust编写的超快速Python代码检查工具和格式化程序，Ruff的配置其实可以很简单。本文将通过一个完整的pyproject.toml配置示例，带你快速掌握Ruff的配置技巧，让代码检查和格式化变得高效而轻松。读完本文，你将能够：
- 理解Ruff配置文件的基本结构
- 掌握常用配置选项的设置方法
- 学会针对不同场景自定义规则
- 了解配置文件的发现机制和优先级
Ruff配置基础
Ruff支持通过pyproject.toml、ruff.toml或.ruff.toml文件进行配置。其中，pyproject.toml是Python项目中常用的配置文件，推荐优先使用。Ruff的配置主要包括通用设置、检查器(lint)设置和格式化器(format)设置三个部分。
默认配置
如果没有指定配置文件，Ruff会使用默认配置。默认配置启用了Pyflakes (F)和部分pycodestyle (E)规则，行长度为88，假设Python版本为3.9。以下是默认配置的简化版本：
[tool.ruff]
line-length = 88
indent-width = 4
target-version = "py39"
[tool.ruff.lint]
select = ["E4", "E7", "E9", "F"]
ignore = []
fixable = ["ALL"]
unfixable = []
[tool.ruff.format]
quote-style = "double"
indent-style = "space"
完整配置示例
以下是一个完整的pyproject.toml配置示例，涵盖了常用的配置选项：
[tool.ruff]
# 通用设置
target-version = "py38"
line-length = 88
indent-width = 4
extend-exclude = [
"crates/ty_vendored/vendor/",
"crates/ruff/resources/",
"crates/ruff_linter/resources/",
]
[tool.ruff.lint]
# 启用的规则集
select = [
"E", # pycodestyle (error)
"F", # pyflakes
"B", # bugbear
"B9",
"C4", # flake8-comprehensions
"SIM",# flake8-simplify
"I", # isort
"UP", # pyupgrade
"PIE",# flake8-pie
"PGH",# pygrep-hooks
"PYI",# flake8-pyi
"RUF",
]
# 忽略的规则
ignore = [
"B011", # 仅在使用python -0时相关
"E501" # 行长度检查
]
# isort配置
[tool.ruff.lint.isort]
required-imports = ["from __future__ import annotations"]
# 按文件忽略规则
[tool.ruff.lint.per-file-ignores]
"__init__.py" = ["E402"]
"**/{tests,docs,tools}/*" = ["E402"]
[tool.ruff.format]
# 格式化设置
quote-style = "double"
indent-style = "space"
skip-magic-trailing-comma = false
line-ending = "auto"
关键配置选项解析
通用设置
| 选项 | 说明 | 示例值 |
|---|---|---|
| target-version | 指定目标Python版本 | "py38" |
| line-length | 行长度限制 | 88 |
| indent-width | 缩进宽度 | 4 |
| exclude | 排除文件/目录 | ["venv/", "dist/"] |
| extend-exclude | 在默认排除基础上添加排除项 | ["crates/ruff/resources/"] |
检查器设置
规则选择
Ruff的规则通过代码标识，如"E"代表pycodestyle错误，"F"代表Pyflakes等。可以通过select和ignore来控制启用和禁用哪些规则。
[tool.ruff.lint]
select = ["E", "F", "B", "I"] # 启用的规则集
ignore = ["E501", "B011"] # 忽略的具体规则
按文件忽略
通过per-file-ignores可以为特定文件或目录设置忽略规则：
[tool.ruff.lint.per-file-ignores]
"__init__.py" = ["E402"] # 所有__init__.py文件忽略E402
"**/{tests,docs,tools}/*" = ["E402"] # 测试、文档和工具目录忽略E402
格式化器设置
Ruff的格式化器可以配置引号风格、缩进方式等：
[tool.ruff.format]
quote-style = "double" # 使用双引号
indent-style = "space" # 使用空格缩进
skip-magic-trailing-comma = false # 保留魔法尾逗号
line-ending = "auto" # 自动检测行结束符
配置文件发现机制
Ruff采用层级配置，会在目录树中查找最近的配置文件。配置文件的优先级为：.ruff.toml > ruff.toml > pyproject.toml。
如果需要继承其他配置文件，可以使用extend选项：
[tool.ruff]
extend = "../pyproject.toml" # 继承父目录的配置
line-length = 100 # 覆盖行长度设置
常见问题解决
如何只对特定文件应用规则？
可以使用per-file-ignores配置，如忽略测试目录中的某些规则：
[tool.ruff.lint.per-file-ignores]
"tests/**/*.py" = ["E402", "F401"]
如何启用Jupyter Notebook支持？
Ruff默认支持Jupyter Notebook文件。如果需要禁用，可以在格式化器设置中排除：
[tool.ruff.format]
exclude = ["*.ipynb"] # 排除Notebook文件
如何在命令行覆盖配置？
可以使用--config选项在命令行临时覆盖配置：
ruff check --config "lint.select=['E','F']" src/
总结
通过pyproject.toml配置Ruff可以灵活控制代码检查和格式化行为。关键是合理选择规则集，根据项目需求自定义配置，并利用按文件忽略等功能针对不同场景进行优化。Ruff的配置系统既强大又易用，只需几分钟就能完成设置，让你的Python代码质量提升一个台阶。
项目配置示例：pyproject.toml 完整配置文档：docs/configuration.md
希望本文能帮助你更好地配置和使用Ruff，如有任何问题，欢迎查阅官方文档或提交issue。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
