Code Formatting — black & isort

• Distinguish a formatter from a linter.
• Auto-format with black (or ruff format).
• Order imports with isort (or ruff's I rules).
• Use --check mode to enforce formatting in CI.

LINTER     (ruff, pylint)  finds problems → you decide how to fix
FORMATTER  (black, isort)  rewrites layout automatically → no decisions

# before black:
x = {'a':1,    'b':2}
def f( a,b ):return a+b

# after black — one canonical style, no arguments:
x = {"a": 1, "b": 2}


def f(a, b):
    return a + b

black — the layout formatter

pip install black

black .              # reformat everything in place
black myfile.py      # one file
black --check .      # don't change anything; exit non-zero if NOT formatted
black --diff .       # show what WOULD change

--check is what CI uses: it doesn't edit, it just fails the build if any file isn't already black-formatted.

isort — order the imports

# before isort:
import os
from myapp import thing
import sys
from collections import OrderedDict

# after isort — grouped: stdlib, third-party, local; alphabetised:
import os
import sys
from collections import OrderedDict

from myapp import thing

pip install isort
isort .
isort --check-only .   # CI mode

Or just use ruff for both

ruff format .        # black-compatible formatter, built into ruff
ruff check --select I --fix .   # sort imports (replaces isort)

# many teams now use ONLY ruff: it lints, formats, and sorts imports.

Configure once

# pyproject.toml
[tool.black]
line-length = 100

[tool.isort]
profile = "black"      # make isort agree with black's style

profile = "black" matters — it stops isort and black fighting each other over import formatting.

Format on save (editor)

Configure your editor to run black/ruff-format on every save. Then formatting is invisible — you write messy, save, and it's clean. (VS Code: set the formatter + "format on save".)

# messy.py — before (inconsistent everywhere)
import sys,os
from   myapp import   (a,b,c)
def calc(x,y,z=10):
    result=x*y+z
    data={'key1':'value1','key2':'value2','key3':'value3','key4':'value4'}
    return result,data

$ ruff check --select I --fix .   # sort imports
$ ruff format .                   # reformat layout
2 files reformatted

# messy.py — after (one canonical style)
import os
import sys

from myapp import a, b, c


def calc(x, y, z=10):
    result = x * y + z
    data = {
        "key1": "value1",
        "key2": "value2",
        "key3": "value3",
        "key4": "value4",
    }
    return result, data

Read the diff

Imports sorted and grouped, spaces normalised, the long dict broken across lines, double quotes everywhere — and you made zero decisions. Run this on every save and every file in the repo looks the same forever. The payoff is huge in code review: diffs show only real changes, never whitespace noise.

A formatter rewrites layout automatically (no decisions); a linter finds problems (you decide). black/ruff format handle layout, isort/ruff's I rules order imports. Use --check mode in CI. Format on save so it's invisible. Result: consistent code, clean diffs, no whitespace bikeshedding. Next: type checking with mypy.