Skip to content

Linting Guide

Linting Strategy Guide for UVI Development

Overview

This guide documents our linting approach using Ruff as our primary linter. Ruff is a fast, modern Python linter that includes Pylint-equivalent rules for comprehensive code quality checks.

Linter Configuration

Ruff Configuration

Our Ruff settings in pyproject.toml:

[tool.ruff]
target-version = "py39"
line-length = 120
fix = true

[tool.ruff.lint]
select = [
  # flake8-2020
  "YTT",
  # flake8-bandit
  "S",
  # flake8-bugbear
  "B",
  # flake8-builtins
  "A",
  # flake8-comprehensions
  "C4",
  # flake8-debugger
  "T10",
  # flake8-simplify
  "SIM",
  # isort
  "I",
  # mccabe
  "C90",
  # pycodestyle
  "E", "W",
  # pyflakes
  "F",
  # pygrep-hooks
  "PGH",
  # pyupgrade
  "UP",
  # ruff
  "RUF",
  # tryceratops
  "TRY",
  # Pylint-equivalent rules
  "PLC", # pylint-convention
  "PLE", # pylint-error
  "PLR", # pylint-refactor
  "PLW", # pylint-warning
]
ignore = [
  # LineTooLong
  "E501",
  # DoNotAssignLambda
  "E731",
]

Running Linters

Development Checks

# Check code
ruff check .

# Fix auto-fixable issues
ruff check --fix .

# Format code
ruff format .

Pre-commit Integration

Our .pre-commit-config.yaml configuration:

repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: "v0.6.3"
    hooks:
      - id: ruff
        args: [--exit-non-zero-on-fix, --config=pyproject.toml]
        exclude: ^{{cookiecutter.project_name}}
      - id: ruff-format
        args: [--config=pyproject.toml]
        exclude: ^{{cookiecutter.project_name}}

Linting Strategy

Why Ruff?

  1. Comprehensive Coverage

  2. Includes most functionality from tools like Flake8, Black, isort, pyupgrade, etc.

  3. Incorporates Pylint-equivalent rules for deeper code analysis

  4. Detects security issues, antipatterns, and complexity issues

  5. Performance

  6. Extremely fast execution (written in Rust)

  7. Efficient for CI/CD pipelines

  8. Quick developer feedback

  9. Modern Features

  10. Auto-fix capabilities for many issues
  11. Type annotation checks
  12. Pre-commit integration
  13. Built-in formatter

What Ruff Catches

  • Import sorting and organization
  • Code style and formatting issues
  • Type annotation problems
  • Security vulnerabilities
  • Unused imports and variables
  • Complex code and high cyclomatic complexity
  • Documentation issues
  • And much more!

Best Practices

  1. Development Workflow

  2. Run Ruff frequently during development

  3. Use Ruff's auto-fix capability (ruff check --fix)
  4. Format code with ruff format

  5. Address all warnings before committing

  6. Issue Resolution

  7. Fix issues immediately during development

  8. Use proper exception handling instead of noqa directives

  9. Document necessary suppressions (rare cases only)

  10. Configuration Management

  11. Keep Ruff rules up to date
  12. Minimize rule suppressions
  13. Document why rules are ignored when necessary

For the best development experience:

  1. VS Code

  2. Install the Ruff extension

  3. Configure auto-formatting on save

  4. Enable lint-on-save

  5. PyCharm/IntelliJ

  6. Use the Ruff plugin
  7. Configure auto-formatting

CI Integration

Ruff runs in CI:

  1. Checks all code for issues
  2. Verifies formatting standards
  3. Must pass for PR approval

Future Considerations

  1. Stay current with Ruff updates

  2. Ruff is actively developed

  3. New rules and features are added regularly

  4. Update to newer versions as available

  5. Regular Review

  6. Reassess linting strategy periodically
  7. Update rules as project needs change
  8. Consider new tools as they emerge