Linting, formatting and type checking

Python runs code that is badly formatted, imports things it never uses, and passes a string where a number belongs, as long as the faulty line is never reached. Three kinds of tool catch these problems without running the program: a linter reports likely mistakes, a formatter rewrites layout into one agreed style, and a type checker compares your annotations with how values are actually used.

ruff check: finding mistakes

ruff is a linter and a formatter in a single tool. Install it into your project’s environment or as a command of its own:

In a venv, install it with pip:

$ python -m pip install ruff

In a uv project, add it to the development group instead:

$ uv add --dev ruff

Use whichever matches your setup. Here is a file that runs correctly and still has problems:

import os
import sys
import json

def  average(numbers):
    total=0
    for n in numbers :
        total+=n
    unused = len(numbers)
    return total/len(numbers)

print( average([3,4,5]) )

Run the linter with three rule families selected. E is pycodestyle errors, F is the checks that Pyflakes pioneered (unused names, undefined names), and I checks import order. The concise output format prints one line per finding:

$ ruff check --select E,F,I --output-format concise messy.py
messy.py:1:1: I001 [*] Import block is un-sorted or un-formatted
messy.py:1:8: F401 [*] `os` imported but unused
messy.py:2:8: F401 [*] `sys` imported but unused
messy.py:3:8: F401 [*] `json` imported but unused
messy.py:9:5: F841 Local variable `unused` is assigned to but never used
Found 5 errors.
[*] 4 fixable with the `--fix` option (1 hidden fix can be enabled with the `--unsafe-fixes` option).

Each line gives the file, line and column, a rule code, and a message. The code is how you look a rule up, silence it, or turn it on everywhere. The [*] marks findings that ruff knows how to repair.

--fix applies the safe repairs:

$ ruff check --select E,F,I --fix --output-format concise messy.py
messy.py:6:5: F841 Local variable `unused` is assigned to but never used
Found 4 errors (3 fixed, 1 remaining).
No fixes available (1 hidden fix can be enabled with the `--unsafe-fixes` option).

The three unused imports are gone, and the remaining one needs you. Deleting unused = len(numbers) is mechanical, but ruff holds back because removing an assignment can remove a call with side effects, and only you know whether it matters here. Ruff calls such repairs unsafe. Edit that line yourself.

The exact wording and layout of ruff’s output can change between releases, so treat the examples as the shape of the thing. The rule codes are stable.

ruff format: one style, no arguments

A formatter is not about correctness. It ends arguments about spaces and line breaks by applying one style to everything. Ask what it would change first, using --diff:

$ ruff format --diff messy.py
--- messy.py
+++ messy.py
@@ -2,11 +2,13 @@
 import sys
 import json

-def  average(numbers):
-    total=0
-    for n in numbers :
-        total+=n
+
+def average(numbers):
+    total = 0
+    for n in numbers:
+        total += n
     unused = len(numbers)
-    return total/len(numbers)
+    return total / len(numbers)
+

-print( average([3,4,5]) )
+print(average([3, 4, 5]))

Then run ruff format messy.py to apply it. ruff format --check changes nothing and reports whether any file would change, with a non-zero exit status if so. That is the form to use in automated checks. After the fixes and formatting, the file reads as expected:

def average(numbers):
    total = 0
    for n in numbers:
        total += n
    return total / len(numbers)


print(average([3, 4, 5]))

4.0

The linter and formatter overlap in spirit and are separate commands. Use both. black is another widely used formatter, and projects that already use it are fine.

Configuring it in pyproject.toml

Typing --select E,F,I every time is tiresome. Put the choice where the whole team and the editor see it, in the [tool.ruff] tables of the pyproject.toml from the previous lessons:

[tool.ruff]
line-length = 100

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

line-length applies to the formatter and to the line-length rule. select chooses rule families by code prefix. ignore removes individual rules from the selection, here E501, the “line too long” check, because the formatter already manages line length. Once this is in place, a bare ruff check and ruff format do the right thing from anywhere inside the project.

A good habit is to run both before every commit:

$ ruff check && ruff format --check

Type checking, briefly

Annotations from the type hints lesson do nothing at run time. A type checker is a separate program that reads them and reports conflicts. The most established is mypy; pyright is another. Newer checkers such as ty and pyrefly also exist, and all of them work on the same annotations.

This program runs without error and prints sensible-looking output, but two of its calls break the promises in its own annotations:

def find_age(ages: dict[str, int], name: str) -> int | None:
    return ages.get(name)


def double(n: int) -> int:
    return n * 2


ages = {"ana": 31, "ben": 27}

print(double(find_age(ages, "ana")))
print(double("ab"))

62
abab

Running the checker:

$ mypy typed.py
typed.py:11: error: Argument 1 to "double" has incompatible type "int | None"; expected "int"  [arg-type]
typed.py:12: error: Argument 1 to "double" has incompatible type "str"; expected "int"  [arg-type]
Found 2 errors in 1 file (checked 1 source file)

The first message is the useful one. find_age can return None when the name is missing. Today "ana" exists, so the program works, but with "zoe" it would crash inside double. Nobody tested that path, and the checker found it. The second is a quieter bug: "ab" * 2 is valid Python, so the program printed abab instead of failing.

Both are fixed by handling the None and passing an int:

def find_age(ages: dict[str, int], name: str) -> int | None:
    return ages.get(name)


def double(n: int) -> int:
    return n * 2


ages = {"ana": 31, "ben": 27}

age = find_age(ages, "ana")
if age is not None:
    print(double(age))
print(double(21))

62
42

$ mypy typed_fixed.py
Success: no issues found in 1 source file

By default mypy skips the body of any function that has no annotations at all, so unannotated code gets no checking. Annotate the signatures, and the checker has something to compare. Type checking is optional in Python and works best when applied gradually, a module at a time. The advanced track returns to typing in depth.

messy.py:1:1: I001 [*] Import block is un-sorted or un-formatted
messy.py:1:8: F401 [*] `os` imported but unused
messy.py:2:8: F401 [*] `sys` imported but unused
messy.py:3:8: F401 [*] `json` imported but unused
messy.py:10:5: F841 Local variable `unused` is assigned to but never used
Found 5 errors.

4.0
None

def average(numbers):
    return sum(numbers) / len(numbers)


print(average([3, 4, 5]))
print(average([]))

def average(numbers: list[float]) -> float | None:
    if not numbers:
        return None
    return sum(numbers) / len(numbers)


result = average([3, 4, 5])
if result is not None:
    print(result)
print(average([]))

All checks passed!
2 files already formatted

[dependency-groups]
dev = ["pytest", "ruff"]

[tool.ruff.lint]
select = ["E", "F", "I"]

$ uv add --dev ruff
$ uv run ruff check
$ uv run ruff format --check

Summary

• ruff check finds likely mistakes and reports rule codes; --fix applies the safe repairs, and unsafe ones are left for you. ruff format applies one layout, and --check or --diff previews it.
• Select rules and line length in [tool.ruff] in pyproject.toml, so the command line stays short and everyone gets the same result.
• A type checker such as mypy compares your annotations with how values are used, and catches cases like the unhandled None that tests missed.
• Going further: the advanced lesson Typing fundamentals teaches the annotations a type checker reads.