gh-jwplatta-prompt-library-claude-plugins-pythonic/skills/python-code-quality/ruff-configuration.md

Ruff Configuration Guide

Ruff is a fast Python linter and formatter that replaces multiple tools (isort, flake8, pyupgrade, etc.).

Basic Configuration

Add to pyproject.toml:

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

[tool.ruff.lint]
select = [
    "E",      # pycodestyle errors
    "W",      # pycodestyle warnings
    "F",      # pyflakes
    "I",      # isort
    "B",      # flake8-bugbear
    "C4",     # flake8-comprehensions
    "UP",     # pyupgrade
    "ARG",    # flake8-unused-arguments
    "SIM",    # flake8-simplify
    "TCH",    # flake8-type-checking
    "RUF",    # Ruff-specific rules
]

ignore = [
    "E501",   # line too long (handled by formatter)
    "B008",   # do not perform function calls in argument defaults
]

[tool.ruff.lint.per-file-ignores]
"tests/**/*.py" = [
    "ARG",    # Unused function arguments allowed in tests
    "S101",   # Assert allowed in tests
]
"__init__.py" = [
    "F401",   # Unused imports allowed in __init__.py
]

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

[tool.ruff.lint.isort]
known-first-party = ["project_name"]

Rule Categories

Error Detection (E, W, F)

• E: PEP 8 style errors
• W: PEP 8 style warnings
• F: PyFlakes logical errors

Code Quality (B, C4, SIM)

• B: Bugbear - likely bugs and design problems
• C4: Comprehensions - simplify list/dict/set comprehensions
• SIM: Simplify - code simplification suggestions

Modernization (UP)

• UP: PyUpgrade - use modern Python syntax
  • typing.List → list
  • Optional[str] → str | None (Python 3.10+)

Organization (I)

• I: isort - import sorting and organization

Performance (ARG, TCH)

• ARG: Detect unused function arguments
• TCH: Type checking imports (move to TYPE_CHECKING block)

Common Rules

E/W Series (PEP 8)

• E111: Indentation is not a multiple of 4
• E201: Whitespace after '('
• E202: Whitespace before ')'
• E203: Whitespace before ':'
• E302: Expected 2 blank lines
• E303: Too many blank lines
• W291: Trailing whitespace

F Series (PyFlakes)

• F401: Unused import
• F811: Redefinition of unused name
• F821: Undefined name
• F841: Local variable assigned but never used

B Series (Bugbear)

• B002: Using * in exception handling
• B006: Mutable default argument
• B007: Loop variable not used
• B008: Function calls in default arguments
• B904: Use raise ... from ... for exception chaining

UP Series (PyUpgrade)

• UP006: Use list instead of typing.List
• UP007: Use X | Y instead of typing.Union[X, Y]
• UP032: Use f-strings instead of .format()

Commands Reference

Linting

# Check all files
ruff check .

# Check specific file
ruff check src/module.py

# Auto-fix issues
ruff check --fix .

# Show fixes without applying
ruff check --diff .

# Watch mode (re-run on file changes)
ruff check --watch .

# Output JSON format
ruff check --output-format=json .

Formatting

# Format all files
ruff format .

# Format specific file
ruff format src/module.py

# Check if formatting needed (CI)
ruff format --check .

# Show diff without applying
ruff format --diff .

Configuration Testing

# Show active configuration
ruff check --show-settings

# Show all available rules
ruff rule --all

# Show specific rule documentation
ruff rule F401

Per-File Ignores

Ignore specific rules for specific files:

[tool.ruff.lint.per-file-ignores]
"tests/**/*.py" = ["ARG", "S101"]      # Tests can use assert and unused args
"__init__.py" = ["F401"]                # Unused imports OK in __init__
"scripts/**/*.py" = ["T201"]            # print() OK in scripts
"migrations/**/*.py" = ["E501"]         # Long lines OK in migrations

VSCode Integration

Add to .vscode/settings.json:

{
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.organizeImports": "explicit",
      "source.fixAll": "explicit"
    }
  },
  "ruff.enable": true,
  "ruff.lint.enable": true,
  "ruff.format.enable": true
}

Performance Tips

Ruff is extremely fast (10-100x faster than alternatives):

• Written in Rust for performance
• Parallel processing by default
• Incremental linting in watch mode
• Caching for repeated runs

Migration from Other Tools

From Black

Ruff's formatter is compatible with Black:

ruff format .  # Replaces: black .

From isort

ruff check --select I --fix .  # Replaces: isort .

From flake8

ruff check .  # Replaces: flake8 .

From pyupgrade

ruff check --select UP --fix .  # Replaces: pyupgrade .

Best Practices

1. Run formatter last: ruff check --fix . && ruff format .
2. Use in CI: Check both linting and formatting
3. Configure per-file ignores: For tests, init files, migrations
4. Enable auto-fix: Most issues can be fixed automatically
5. Use with pre-commit: Run checks before commits
6. Review rule changes: Stay updated with new releases