Linting & Formatting Highlights Summary

Every highlight bullet from the 10 pages in this section, gathered on one page and grouped by the page it came from.

The Static Analysis Pipeline Model

• A linter and a formatter both read your source, but they answer different questions and rarely share logic
• Ruff's linter walks an AST and matches rule patterns; its formatter throws that AST away and re-prints it deterministically
• A type checker is not a linter with extra rules - it builds an inferred type graph across your whole codebase
• The same check running in editor, pre-commit, and CI is a deliberate shift-left strategy, not redundancy
• Auto-fixable violations and structural violations require fundamentally different remediation paths

Ruff Setup

• Ruff replaces flake8, isort, pyupgrade in one Rust tool, 10-100x faster
• Commit [tool.ruff] to pyproject.toml; defaults may not match your team style
• Set target-version and src in config for proper syntax and import detection
• Ignore E501 and let ruff format handle line length to avoid double enforcement
• Pick one formatter in CI; Black and ruff format fighting causes linting conflicts
• Ruff runs lint, format, and import sorting with a single binary and config block

Black / Ruff Format

• Ruff format is faster and recommended for new projects over Black
• Use --check mode in CI to detect formatting drift without modifying files
• Mixing Black and Ruff format causes subtle output differences and churn
• Formatters eliminate style debates with deterministic, same-every-time output
• Exclude migrations and generated code from formatting to avoid noisy diffs
• Formatters only change whitespace and quotes, never code semantics or behavior

Essential Lint Rules

• E, F, I, UP provide core coverage for style bugs imports and syntax issues
• I catches import disorder before review prevents style drift in production
• F catches dead code and undefined names before they reach production
• Start with core rules then add incrementally, never enable everything at once
• Tests need per-file overrides allowing S101 assert and T20 print debugging
• Every ignore requires a comment explaining why it is necessary and safe

isort & Import Organization

• Ruff's isort rules auto-sort imports, no separate isort install needed
• Configure known-first-party to distinguish your packages from third-party
• Order imports: future, stdlib, third-party, first-party, then local-folder
• Using both isort and ruff together creates conflicting rules, use ruff only
• Replace star imports with explicit imports to avoid obscuring module origin
• Circular imports need module restructuring or lazy imports, not just reordering

mypy & pyright in CI

• Catch None access, type mismatches, and missing attributes before runtime
• Run mypy or pyright in CI to enforce type hints as contracts
• Start with check_untyped_defs before enabling strict mode on legacy code
• Choose pyright for speed or mypy for broader plugin support
• Make type failures block merges, not just warnings
• Use ignore_missing_imports temporarily for untyped third-party deps

pre-commit Hooks

• Pre-commit catches linting and formatting errors locally in seconds, not CI minutes later
• Use ruff with --fix and ruff-format hooks to auto-correct staged files before commit
• Keep mypy in CI only, not pre-commit, to avoid frustrating slow commits on dev
• Pin hook versions in config to ensure consistent results between local and CI
• Hooks run on staged files only in isolated environments, blocking failed commits
• Document pre-commit install in README and run --all-files in CI to catch skips

Editor Integration

• IDE integration surfaces lint errors and formatting fixes as you type for fast feedback loops
• Set formatOnSave and defaultFormatter to ruff in VS Code settings for auto-format on save
• Enable ruff and mypy plugin in PyCharm to integrate type checking into the editor
• Wrong Python interpreter runs lint against system packages, fix by selecting .venv in status bar
• Pick one type checker between Pylance and mypy to avoid duplicate error highlighting
• Open project root folder not subdirectory so ruff finds pyproject.toml configuration

Linting in CI/CD

• Every pull request runs the same lint checks regardless of local editor setup
• Separate check and format steps give clear messages about failures
• Use ruff format --check to fail instead of auto-fixing code
• uv sync --frozen ensures lockfile integrity before running linters
• Cache .venv, .ruff_cache, .mypy_cache keyed on uv.lock hash for speed
• Lint only changed files with git diff for faster checks on large repos

Linting & Formatting Best Practices

• Use ruff for both lint and format with single config in pyproject.toml for sub-second runs
• Start with E, F, I, UP, B, SIM rules; add S for web apps; ignore E501 for formatter
• Format on save in editor, enforce in CI with required checks for both lint and format
• Pin ruff version in lockfile and pre-commit rev to keep local and CI in sync
• Every noqa and type: ignore needs a comment explaining the suppression
• Add mypy or pyright for type checking since ruff only catches style not logic errors