Style, Linting and Type Hints 🎨

PEP 8, the shared agreement

PEP 8 is Python's official style guide, written in 2001 and followed almost universally. Its value is not that its choices are objectively best; it is that everybody made the same choices, so you can read anyone's code without adjusting.

Stop arguing: let a tool do it

# before
def  calc( a,b ):
    result=a+b
    if result>10 :
        return  "big"
    else :
        return "small"

print(calc(5,6))

big

Run a formatter over that and it becomes:

def calc(a, b):
    result = a + b
    if result > 10:
        return "big"
    else:
        return "small"


print(calc(5, 6))

big

# the two options, either is fine
pip install black && black .

pip install ruff && ruff format .

Both reformat your entire project in under a second and have almost no configuration on purpose. black calls itself "the uncompromising formatter" and its central insight is that the fastest way to end a style argument is to remove the choice. ruff does the same job (and linting too) and is written in Rust, which is why it is fast enough to run on every keystroke.

Linting: the tool that reads your code critically

A formatter fixes how code looks. A linter points out things that look like mistakes: unused imports, variables assigned but never used, shadowed built-ins, comparisons that are always true.

$ ruff check .

app.py:1:8: F401 [*] `os` imported but unused
app.py:12:5: F841 Local variable `total` is assigned to but never used
app.py:20:1: E741 Ambiguous variable name: `l`
app.py:34:12: SIM108 Use ternary operator instead of if-else block

Found 4 errors.
[*] 1 fixable with the `--fix` option.

Nearly all of those are real bugs in embryo. An unused import means you deleted the code that needed it; an assigned-but-unused variable very often means you typed the name slightly differently on the line that uses it.

Type hints

def greet(name: str, times: int = 1) -> str:
    """Greet someone, possibly repeatedly."""
    return " ".join([f"Hello, {name}!"] * times)


print(greet("Guybrush"))
print(greet("Elaine", 2))
print(greet.__annotations__)

Hello, Guybrush!
Hello, Elaine! Hello, Elaine!
{'name': <class 'str'>, 'times': <class 'int'>, 'return': <class 'str'>}

So why bother? Three excellent reasons:

• Your editor gets smarter. Autocomplete knows what methods exist, and it underlines name.uppr() before you run anything.
• A checker can prove things. mypy reads your whole project and finds type errors without running it. On a large codebase this catches real bugs in code paths nobody has exercised yet.
• They are the best documentation there is, because they cannot drift out of date silently the way a comment can.

The notation you need

def process(
    names: list[str],
    scores: dict[str, int],
    limit: int | None = None,
    tags: tuple[str, ...] = (),
) -> list[tuple[str, int]]:
    """Pair names with scores, optionally limited."""
    pairs = [(n, scores.get(n, 0)) for n in names]
    return pairs[:limit] if limit else pairs


print(process(["Guybrush", "Elaine"], {"Guybrush": 95}, limit=1))

[('Guybrush', 95)]

What mypy catches

def total_price(items: list[float]) -> float:
    return sum(items)


# mypy reports: Argument 1 has incompatible type "list[str]";
#               expected "list[float]"
result = total_price(["12.50", "3.99"])

$ mypy shop.py
shop.py:7: error: Argument 1 to "total_price" has incompatible type
    "list[str]"; expected "list[float]"  [arg-type]
Found 1 error in 1 file (checked 1 source file)

That program runs without hints and produces '12.503.99', a string, which then breaks something else three functions away. mypy found it in a second without running anything.

How much of this to adopt

One config file

# pyproject.toml
[project]
name = "crew-manager"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = ["requests>=2.31"]

[tool.ruff]
line-length = 88

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

[tool.mypy]
python_version = "3.13"
warn_unused_ignores = true

[tool.pytest.ini_options]
testpaths = ["tests"]

pyproject.toml is the modern single home for project configuration: packaging, formatting, linting, type checking and testing all in one file. Lesson 50 uses it to publish a package.

import os, sys
def CalcTotal( Items ):
    Total=0
    for i in Items :
        Total=Total+i
    if Total>100 :
        return Total*0.9
    else :
        return Total
print(CalcTotal([50,60]))

def calculate_total(items: list[float]) -> float:
    """Sum the items, applying a 10 percent discount over 100."""
    total = sum(items)
    if total > 100:
        return total * 0.9
    return total


print(calculate_total([50, 60]))

99.0

def find_best(scores, minimum=0):
    best_name = None
    best_score = minimum
    for name, score in scores.items():
        if score > best_score:
            best_name, best_score = name, score
    return best_name, best_score

def find_best(
    scores: dict[str, int],
    minimum: int = 0,
) -> tuple[str | None, int]:
    """Return the highest scorer above minimum, or (None, minimum)."""
    best_name: str | None = None
    best_score = minimum
    for name, score in scores.items():
        if score > best_score:
            best_name, best_score = name, score
    return best_name, best_score


print(find_best({"Guybrush": 95, "Otis": 42}))
print(find_best({"Otis": 42}, minimum=50))

('Guybrush', 95)
(None, 50)

python3 -m venv .venv && source .venv/bin/activate
pip install ruff mypy pytest

ruff format .          # reformat everything
ruff check . --fix     # fix what can be fixed automatically
mypy .                 # type check
pytest                 # run the tests

# and the one command that does all of it before you commit
ruff format . && ruff check . && mypy . && pytest