ruff-formatting

ruff 格式化

掌握使用 ruff format 将其作为兼容 Black、速度极快的 Python 代码格式化工具。

何时使用此技能

适合使用此技能的情况……	适合改用其他工具的情况……
格式化 Python 文件	检查代码问题（使用 ruff check）
在 CI 中检查格式是否符合要求	类型检查（使用 basedpyright）
从 Black 迁移	检测无用代码（使用 vulture/deadcode）
设置保存时自动格式化	运行测试（使用 pytest）

核心专长

ruff format 的优势

• 速度比 Black 快 10–30 倍
• 可直接替代 Black（兼容率达 99.9%）
• 使用 Rust 编写，性能出色
• 支持 Black 的配置选项
• 支持格式检查和差异预览
• 自动遵循 .gitignore

基本用法

简单格式化

# Format current directory
ruff format

# Format specific files or directories
ruff format path/to/file.py
ruff format src/ tests/

# IMPORTANT: Pass directory as parameter to stay in repo root
ruff format services/orchestrator

检查格式

# Check if files are formatted (exit code 1 if not)
ruff format --check

# Show diff without modifying files
ruff format --diff

# Check specific files
ruff format --check src/ tests/

# Preview changes before applying
ruff format --diff services/orchestrator
ruff format services/orchestrator  # Apply after review

选择性格式化

# Format only Python files
ruff format src/**/*.py

# Format excluding tests
ruff format --exclude tests/

# Format only changed files (git)
git diff --name-only --diff-filter=d | grep '\.py$' | xargs ruff format

# Format files in specific directory
ruff format src/core/ src/utils/

配置

pyproject.toml

[tool.ruff]
line-length = 88
target-version = "py39"

[tool.ruff.format]
quote-style = "double"
indent-style = "space"
skip-magic-trailing-comma = false
line-ending = "auto"
docstring-code-format = true
docstring-code-line-length = "dynamic"
exclude = [
    "*.pyi",
    "**/__pycache__",
    "**/node_modules",
    ".venv",
]

ruff.toml（独立配置文件）

line-length = 88

[format]
quote-style = "single"
indent-style = "space"
skip-magic-trailing-comma = false
docstring-code-format = true

与 Black 兼容

[tool.ruff]
line-length = 88
indent-width = 4
target-version = "py39"

[tool.ruff.format]
quote-style = "double"
indent-style = "space"
skip-magic-trailing-comma = false
line-ending = "auto"

格式化工作流

1. 预览：ruff format --diff（查看更改）
2. 检查：ruff format --check（CI 验证）
3. 应用：ruff format（修改文件）
4. 验证：ruff format --check（确认）

最佳实践

• 直接传入目录参数：ruff format src/
• 先使用 --diff 预览更改
• 每个项目只使用一种格式化工具（ruff format 可替代 Black）
• 在 pyproject.toml 中排除生成的文件
• 确保 pre-commit 配置与所选格式化工具保持一致
• 启用 docstring-code-format，以改善文档

Agentic 优化

场景	命令
格式化目录	ruff format src/
检查格式	ruff format --check
显示差异	ruff format --diff
CI 检查并显示差异	ruff format --check --diff
格式化并检查代码	ruff format && ruff check
格式化已更改的文件	git diff --name-only --diff-filter=d | grep '\.py$' | xargs ruff format

快速参考

必备命令

ruff format                         # Format current directory
ruff format path/to/dir             # Format specific directory
ruff format --check                 # Check if formatted
ruff format --diff                  # Show formatting changes
ruff format file1.py file2.py       # Format specific files
ruff format --exclude tests/        # Exclude directory
ruff format --line-length 100       # Override line length

格式化与检查

命令	用途	退出代码	修改文件
ruff format	格式化文件	0	是
ruff format --check	验证格式	格式不符合要求时为 1	否
ruff format --diff	显示更改	0	否
ruff format --check --diff	验证并显示差异	格式不符合要求时为 1	否

快速开始配置

最简配置（兼容 Black）

[tool.ruff]
line-length = 88

[tool.ruff.format]
quote-style = "double"
indent-style = "space"

推荐配置

[tool.ruff]
line-length = 88
target-version = "py311"

[tool.ruff.format]
quote-style = "double"
indent-style = "space"
skip-magic-trailing-comma = false
docstring-code-format = true
line-ending = "auto"
exclude = [
    "*.pyi",
    "migrations/**/*.py",
]

如需查看详细示例、高级模式、集成指南和迁移检查清单，请参阅 REFERENCE.md。