nonobie — Real dev skills, explained like a friend would

What you'll learn

By the end of this chapter you will:

Configure ruff in pyproject.toml with a pragmatic rule set
Distinguish style nits from bug-catching rules (and enable the latter)
Auto-fix violations and format on save
Gate merges on lint + format in CI

The why

Manual style policing in code reviews is expensive and inconsistent.

Teams need fast automated feedback that catches both style drift and bug-prone patterns before merge.

Ruff consolidates linting and formatting into a single fast toolchain, reducing setup complexity and review friction.

Mental model: static checks are guardrails that keep your codebase healthy at scale.

Core concepts: Pragmatic linting and formatting

ruff check and ruff format

bash

ruff check .
ruff check . --fix
ruff format .

check enforces lint rules; format enforces code layout consistency.

Rule buckets and practical selection

toml

[tool.ruff.lint]
select = ["E", "F", "I", "UP", "B", "SIM"]
ignore = ["E501"]

High-value buckets:

F catches many correctness issues,
B catches risky constructs,
UP nudges modern Python usage,
I enforces import ordering.

pyproject configuration strategy

toml

[tool.ruff]
line-length = 100
target-version = "py312"
 
[tool.ruff.format]
quote-style = "double"
 
[tool.ruff.lint.per-file-ignores]
"tests/**" =

Central config keeps editor, local CLI, and CI behavior aligned.

Autofix strategy and safe rollout

bash

ruff check . --fix --unsafe-fixes

Use unsafe fixes carefully in dedicated cleanup PRs, not mixed with feature changes.

Editor integration for fast feedback

json

{
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.ruff": "explicit"
  }
}

Fast local feedback shortens the defect loop dramatically.

Migration from flake8/black/isort

text

Migration sequence:
1) Pin Ruff version
2) Run format-only PR
3) Enable core lint buckets
4) Fix remaining violations
5) Enforce in CI

Split migration into focused PRs to avoid painful review noise.

CI gate design

yaml

- name: Ruff lint
  run: ruff check .
 
- name: Ruff format check
  run: ruff format . --check

Separate lint and format checks improve error readability in pipelines.

Adoption rule

Treat lint policy as a product: start with high-signal rules first, then tighten gradually as team confidence grows.

Rule strategy table

Rule group	Primary value	Risk if ignored
`F` (pyflakes)	correctness	undefined names, dead imports
`B` (bugbear)	bug prevention	subtle runtime pitfalls
`UP` (pyupgrade)	modernization	stale syntax and missed language improvements
`I` (imports)	consistency	merge conflicts and style churn
`SIM` (simplify)	readability	unnecessary complexity

Common mistakes

Mistake	Why it hurts	Better move
`ruff: error: unrecognized arguments`	Version/CLI mismatch	Pin Ruff version and sync docs/CI
`F401 imported but unused` ignored everywhere	Hides dead code and wrong imports	Remove unused imports or narrow exceptions
`E902 IOError` in lint stage	Lint target includes generated or inaccessible files	Scope include/exclude patterns explicitly
Massive mixed formatting + feature PRs	Review noise and merge pain	Run dedicated format/migration PR first
Formatter and linter conflict	Toolchain instability	Use single authoritative Ruff config in pyproject

Production notes

Pin Ruff version in CI for deterministic behavior.
Keep lint configs code-reviewed like application code.
Monitor lint failure trends to detect policy friction hotspots.
Avoid disabling high-signal rules globally without root-cause discussion.

Practice: Prove your Mastery

beginner Challenge

6 min

Ruff bootstrap

Add Ruff config to pyproject.toml and run ruff check . on a sample project.

Input— given data

data

Python project with mixed style issues

Expected Output— your code should produce this

expected

Deterministic lint output

Write your solutionCtrl+Enter to run

Ctrl+Enter

beginner Challenge

7 min

Auto-fix pass

Run ruff check --fix and ruff format, then inspect remaining manual fixes.

Input— given data

data

Project with lint and format drift

Expected Output— your code should produce this

expected

Reduced violation count and clean formatted files

Write your solutionCtrl+Enter to run

Ctrl+Enter

intermediate Challenge

8 min

Per-file ignore policy

Configure test-specific per-file ignores without weakening production code checks.

Input— given data

data

Test files requiring assertion style exceptions

Expected Output— your code should produce this

expected

Scoped ignore behavior only in tests

Write your solutionCtrl+Enter to run

Ctrl+Enter

intermediate Challenge

9 min

Editor-on-save integration

Enable format-on-save and Ruff fix actions, then verify local feedback loop.

Input— given data

data

VS Code settings

Expected Output— your code should produce this

expected

Automatic formatting and fix behavior on save

Write your solutionCtrl+Enter to run

Ctrl+Enter

intermediate Challenge

10 min

CI quality gate

Add lint and format check jobs to CI and simulate one failing and one passing commit.

Input— given data

data

GitHub Actions workflow

Expected Output— your code should produce this

expected

Pipeline blocks on violations and passes after fixes

Write your solutionCtrl+Enter to run

Ctrl+Enter

Interview Questions

Beginner:

"What is the difference between linting and formatting?"

Linting catches code-quality and bug-risk issues, while formatting enforces consistent code layout.
"Why gate linting in CI if developers run it locally?"

CI ensures policy consistency and catches cases where local tooling was skipped or misconfigured.

Senior:

"How would you migrate a large legacy repo to Ruff with minimal disruption?"

Use phased rollout: format-only PR, core high-signal rules, incremental tightening, and explicit ownership.
"How do you decide when to ignore a lint rule versus fixing the code?"

Prefer fixing; allow scoped ignore only when there is clear justification and documented tradeoff.

Summary

Ruff consolidates linting and formatting into a fast, maintainable workflow.
Rule selection should prioritize bug prevention before stylistic strictness.
Editor and CI integration are critical for sustained adoption.
Migration succeeds when done in controlled, review-friendly phases.

Quick recall

text

Need fast quality checks -> ruff check + ruff format
Need high signal -> prioritize F/B/UP/I rule groups
Need low friction adoption -> phased migration strategy
Need consistency -> single pyproject config across local and CI
Need long-term enforcement -> CI gates with pinned tool version

Self-Check Quiz

Q1 / 3

MCQ

What is the practical difference between `ruff check` and `ruff format`?

Chapter 2 — Ruff, Linting & Formatting

The why

Core concepts: Pragmatic linting and formatting

ruff check and ruff format

Rule buckets and practical selection

pyproject configuration strategy

Autofix strategy and safe rollout

Editor integration for fast feedback

Migration from flake8/black/isort

CI gate design

Rule strategy table

Common mistakes

Production notes

Practice: Prove your Mastery

Ruff bootstrap

Auto-fix pass

Per-file ignore policy

Editor-on-save integration

CI quality gate

Interview Questions

Summary

Quick recall

Self-Check Quiz