Python linter

Python Linter

Run ruff (lint + format) and optionally mypy (type checking) on Python code. Auto-fixes what it can and reports what needs manual attention.

Prerequisites

• Python project with .py files

Workflow

Step 1 — Set Up .venv

Always use .venv — create it if it doesn't exist:

[ -d .venv ] || python -m venv .venv
PYTHON=$(if [ -f .venv/Scripts/python ]; then echo .venv/Scripts/python; else echo .venv/bin/python; fi)

Install ruff into the venv if not already present:

$PYTHON -m ruff --version 2>/dev/null || $PYTHON -m pip install ruff

Optionally install mypy for type checking:

$PYTHON -m mypy --version 2>/dev/null || $PYTHON -m pip install mypy

Check for an existing pyproject.toml or ruff.toml config. If neither exists, offer to create a sensible default (see references/python-linter-reference.md for the recommended config).

Step 2 — Run Ruff Lint (with auto-fix)

$PYTHON -m ruff check --fix .

• --fix auto-corrects safe issues (unused imports, style violations, etc.)
• Note any remaining violations that require manual fixes
• If the user wants to see all issues first without fixing:

  $PYTHON -m ruff check .
  

Step 3 — Run Ruff Format

$PYTHON -m ruff format .

• Formats all .py files in place (replaces black + isort)
• To preview changes without applying:

  $PYTHON -m ruff format --diff .
  

Step 4 — Run Type Checking (optional)

Ask the user if they want type checking. If yes:

$PYTHON -m mypy .

Or for stricter checking:

$PYTHON -m mypy --strict .

See references/python-linter-reference.md for mypy configuration options.

Step 5 — Report Results

Summarise:

• How many lint issues were auto-fixed
• Any remaining issues that need manual attention (with file + line references)
• Formatting changes applied
• Type errors found (if mypy was run)

If issues remain, explain each one clearly and offer to fix them.

Additional Resources

• references/python-linter-reference.md — Recommended ruff/mypy configs, rule sets, pyproject.toml templates, CI integration