Ruff (Python Linter)

--- name: Ruff Python Linter description: Use when you need to lint, format, and fix Python code issues. Ruff is an extremely fast Python linter and code formatter written in Rust that combines the functionality of flake8, isort, pydocstyle, and more. metadata: author: skynet version: 1.0.0 category: dev --- # Ruff Python Linter ## Overview Ruff is an extremely fast Python linter and code formatter that replaces multiple tools (flake8, isort, pydocstyle, etc.) with a single, unified interface. It's 10-100x faster than existing Python linters. ## Installation ```bash # Install via pip pip install ruff # Install via conda conda install -c conda-forge ruff # Install via homebrew (macOS) brew install ruff ``` ## Basic Usage ### Linting Commands ```bash # Lint current directory ruff check . # Lint specific file ruff check src/main.py # Lint with auto-fix ruff check --fix . # Show fixes without applying ruff check --diff . # Lint and show rule codes ruff check --show-source . ``` ### Formatting Commands ```bash # Format code (like black) ruff format . # Check formatting without applying ruff format --check . # Show diff of formatting changes ruff format --diff . ``` ## Configuration ### pyproject.toml Configuration ```toml [tool.ruff] # Exclude a variety of commonly ignored directories exclude = [ ".bzr", ".direnv", ".eggs", ".git", ".git-rewrite", ".hg", ".mypy_cache", ".nox", ".pants.d", ".pytype", ".ruff_cache", ".svn", ".tox", ".venv", "__pypackages__", "_build", "buck-out", "build", "dist", "node_modules", "venv", ] # Set the maximum line length line-length = 88 # Assume Python 3.8+ target-version = "py38" [tool.ruff.lint] # Enable specific rule sets select = [ "E", # pycodestyle errors "W", # pycodestyle warnings "F", # Pyflakes "I", # isort "B", # flake8-bugbear "C4", # flake8-comprehensions "UP", # pyupgrade ] # Disable specific rules ignore = [ "E501", # line too long "B008", # do not perform function calls in argument defaults ] # Allow fix for all enabled rules fixable = ["ALL"] unfixable = [] # Allow unused variables when underscore-prefixed dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$" [tool.ruff.format] # Use double quotes for strings quote-style = "double" # Indent with spaces, rather than tabs indent-style = "space" # Respect magic trailing comma skip-magic-trailing-comma = false # Automatically detect the appropriate line ending line-ending = "auto" ``` ### Command Line Rule Selection ```bash # Enable specific rules ruff check --select E,W,F . # Disable specific rules ruff check --ignore E501,W503 . # Enable aggressive rules ruff check --select ALL --ignore E501 . # Check only imports (isort functionality) ruff check --select I . ``` ## Common Workflows ### CI/CD Integration ```yaml # GitHub Actions example - name: Lint with Ruff run: | pip install ruff ruff check . ruff format --check . ``` ### Pre-commit Hook ```yaml # .pre-commit-config.yaml repos: - repo: https://github.com/astral-sh/ruff-pre-commit rev: v0.1.6 hooks: - id: ruff args: [--fix, --exit-non-zero-on-fix] - id: ruff-format ``` ### Migration from Other Tools ```bash # Replace flake8 ruff check . --select E,W,F # Replace isort ruff check . --select I --fix # Replace black (formatting) ruff format . # Replace multiple tools ruff check . --select E,W,F,I,B,C4,UP --fix ruff format . ``` ## Decision Trees ### When to Use Different Commands ``` Need to check code quality? ├── Just check issues → ruff check . ├── Check and fix automatically → ruff check --fix . └── Check formatting only → ruff format --check . Setting up new project? ├── Start with basics → --select E,W,F ├── Add import sorting → --select E,W,F,I └── Full setup → --select E,W,F,I,B,C4,UP Performance issues? ├── Exclude large directories → Add to exclude list ├── Target specific files → ruff check src/ tests/ └── Use specific rules only → --select F,E ``` ### Rule Selection Strategy ``` Code maturity level? ├── New project → --select E,W,F,I (basics) ├── Mature project → --select E,W,F,I,B,C4,UP └── Legacy project → Start with F only, gradually add more Team experience? ├── Beginner → Focus on E,W,F ├── Intermediate → Add I,B,C4 └── Advanced → Consider ALL with selective ignores ``` ## Advanced Features ### Custom Rule Configuration ```bash # Show all available rules ruff linter # Explain specific rule ruff rule E501 # Check specific rule across codebase ruff check --select E501 . ``` ### Integration with Editors ```bash # Generate VS Code settings echo '{ "python.linting.enabled": true, "python.linting.ruffEnabled": true, "python.formatting.provider": "none", "[python]": { "editor.defaultFormatter": "charliermarsh.ruff", "editor.formatOnSave": true } }' > .vscode/settings.json ``` ### Performance Optimization ```bash # Cache results for faster subsequent runs ruff check --cache-dir .ruff_cache . # Parallel processing (default behavior) ruff check . --statistics # Target specific Python version ruff check . --target-version py311 ``` ## Troubleshooting ### Common Errors and Solutions **Error**: `ruff: command not found` ```bash # Solution: Install ruff pip install ruff # or pip install --user ruff export PATH="$HOME/.local/bin:$PATH" ``` **Error**: `F401 'module' imported but unused` ```bash # Solution: Remove unused imports or mark as intentional # Option 1: Remove the import # Option 2: Use noqa comment import unused_module # noqa: F401 # Option 3: Use underscore prefix import unused_module as _unused_module ``` **Error**: `E501 line too long` ```bash # Solution: Configure line length or ignore # Option 1: In pyproject.toml [tool.ruff] line-length = 120 # Option 2: Ignore the rule ruff check --ignore E501 . ``` **Error**: `I001 Import block is un-sorted or un-formatted` ```bash # Solution: Auto-fix import sorting ruff check --select I --fix . # Or configure isort-style settings [tool.ruff.lint.isort] known-first-party = ["mypackage"] ``` **Error**: Configuration not being read ```bash # Check configuration discovery ruff check --show-settings . # Verify file location and syntax ruff check . --config pyproject.toml ``` ### Performance Issues ```bash # Profile performance ruff check . --statistics # Reduce scope for large codebases ruff check src/ --exclude "src/generated/" # Use minimal rule set for speed ruff check . --select F ``` ### Integration Issues ```bash # Test pre-commit setup pre-commit run ruff --all-files # Check editor integration ruff check --output-format=json . # Verify CI compatibility ruff check . --format=github ```