ruff

当用户需要使用Ruff命令行工具对Python代码进行代码检查、格式化或验证时,应使用此技能。用于涉及Python代码质量检查、自动代码格式化、强制执行样式规则(PEP 8)、识别错误和安全问题或现代化Python代码的任务。每当编写或修改Python代码时,应主动调用此技能以确保代码质量。

📖 中文导读:当用户需要使用Ruff命令行工具对Python代码进行代码检查、格式化或验证时,应使用此技能。用于涉及Python代码质量检查、自动代码格式化、强制执行样式规则(PEP 8)、识别错误和安全问题或现代化Python代码的任务。每当编写或修改Python代码时,应主动调用此技能以确保代码质量。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: ruff description: This skill should be used when users need to lint, format, or validate Python code using the Ruff command-line tool. Use this skill for tasks involving Python code quality checks, automatic code formatting, enforcing style rules (PEP 8), identifying bugs and security issues, or modernizing Python code. This skill should be invoked PROACTIVELY whenever Python code is written or modified to ensure code quality.

Ruff Skill

Contents

Proactive Usage

IMPORTANT: Use this skill proactively after writing or modifying Python code.

Standard Workflow

# Step 1: Format the code
uv run ruff format .

# Step 2: Fix auto-fixable linting issues
uv run ruff check --fix .

# Step 3: Report remaining issues
uv run ruff check .

Project Commands

just fmt-python    # Format Python code
just lint-python   # Lint Python code

Quick Reference

Commands

Command Purpose
uv run ruff check . Lint code
uv run ruff check --fix . Fix auto-fixable issues
uv run ruff format . Format code
uv run ruff format --check . Check formatting
uv run ruff check --diff . Preview fixes

Common Flags

Flag Effect
--fix Auto-fix issues
--unsafe-fixes Apply risky fixes
--diff Show changes without applying
--select E,F Check specific rules
--ignore E501 Skip specific rules
--statistics Show issue counts
--watch Continuous linting

Linting Workflow

1. Check for Issues

uv run ruff check .                    # All files
uv run ruff check src/                 # Directory
uv run ruff check script.py            # Single file

2. Auto-fix Safe Issues

uv run ruff check --fix .

3. Review Unsafe Fixes

uv run ruff check --diff --unsafe-fixes .   # Preview
uv run ruff check --fix --unsafe-fixes .    # Apply

4. Address Remaining Issues

Fix manually or suppress with # noqa:

import unused_module  # noqa: F401

Formatting Workflow

1. Format Code

uv run ruff format .

2. Check Without Modifying (CI/CD)

uv run ruff format --check .

3. Preview Changes

uv run ruff format --diff .

Rule Selection

Essential Rules (Start Here)

[tool.ruff]
select = ["F", "E", "I"]
Prefix Source Purpose
F Pyflakes Errors, undefined names
E pycodestyle PEP 8 errors
I isort Import sorting
[tool.ruff]
select = ["F", "E", "I", "W", "UP", "B", "SIM"]
Prefix Source Purpose
W pycodestyle PEP 8 warnings
UP pyupgrade Modernize syntax
B bugbear Likely bugs
SIM simplify Simplification

Security Rules

[tool.ruff]
extend-select = ["S"]

Project Configuration

Basic pyproject.toml

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

select = ["E", "F", "I", "B", "UP"]
ignore = ["E501"]

[tool.ruff.per-file-ignores]
"tests/**/*.py" = ["S101"]
"__init__.py" = ["F401"]

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

Per-file Ignores

Pattern Common Ignores Reason
tests/**/*.py S101 Allow assert
__init__.py F401 Allow unused imports
scripts/*.py T201 Allow print

Inline Suppression

# Ignore all rules for line
import os  # noqa

# Ignore specific rule
import os  # noqa: F401

# Ignore for entire file (at top)
# ruff: noqa: F401

Troubleshooting

Too Many Issues

  1. Start with essential rules only:

    uv run ruff check --select=F,E .
    
  2. Add noqa comments to existing violations:

    uv run ruff check --add-noqa .
    
  3. Fix auto-fixable issues first:

    uv run ruff check --fix .
    
  4. Enable rules gradually over time

Configuration Not Loading

  1. Check file names: ruff.toml, .ruff.toml, or pyproject.toml
  2. Validate syntax: uv run ruff check --config=ruff.toml .
  3. Check for conflicts in parent directories

Formatter vs Linter Conflicts

Run formatter before linter to avoid conflicts:

uv run ruff format .
uv run ruff check --fix .

Output Formats for CI

uv run ruff check --output-format=github .   # GitHub Actions
uv run ruff check --output-format=gitlab .   # GitLab CI
uv run ruff check --output-format=json .     # JSON

References

Project References

External Resources

Best Practices

  1. Format first - Run ruff format before ruff check
  2. Use --fix liberally - Most auto-fixes are safe
  3. Review unsafe fixes - Always check --unsafe-fixes changes
  4. Start simple - Begin with F, E, I rules; expand gradually
  5. Configure CI/CD - Enforce checks in continuous integration
  6. Document exceptions - Comment why rules are disabled