Type Hints in Python

In the Python for Beginners series your functions have always said what they do by doing it; Chapter 20 of this 24-chapter course teaches them to say it out loud. A signature like def add(a: int) -> int states the contract in the code itself, and this chapter covers the annotation syntax, the essential typing names, why the interpreter ignores all of it at runtime, and how a checker like mypy catches mistakes before your users do.

Annotating functions, variables and returns

Annotations are expressions: after a colon for parameters and variables, after -> for the return value. They are optional everywhere and enforced nowhere, but they turn your code into documentation that editors, IDEs and checkers can act on:

def add(a: int, b: int) -> int:
    return a + b

total: int = add(2, 3)
names: list[str] = ["Ada", "Grace"]
print(total, names[0])

Expected output: 5 Ada

The same idea applies to module-level constants, dataclass fields (see chapter 17) and attributes assigned later in a class body. Annotate the boundaries — public functions and the data structures that cross them — rather than every local variable.

None, unions and built-in generics

A function that may return nothing is annotated str | None, the modern spelling. The older Optional[str] from typing means exactly the same thing and still appears in older code and library stubs. Since Python 3.9 the built-ins are generic too: list[int], dict[str, int], set[str] and tuple[int, ...] (a tuple of any length whose items are integers):

from typing import Optional

def find_user(user_id: int) -> str | None:
    users = {1: "Ada"}
    return users.get(user_id)

def find_user_legacy(user_id: int) -> Optional[str]:
    return find_user(user_id)

def last(items: tuple[int, ...]) -> int:
    return items[-1]

scores: dict[str, list[float]] = {"ada": [90.0]}
print(find_user(1), find_user(99))
print(find_user_legacy(99), last((4, 5, 6)))
print(scores["ada"][0])

Expected output:

Ada None
None 6
90.0

The typing toolbox

Eight names cover almost every day-to-day need:

Four of them in one file — note that Literal fits a signature as mode: Mode = "read", and Any deliberately switches checking off:

from typing import Any, Literal, TypedDict, TypeVar

Mode = Literal["read", "write"]
T = TypeVar("T")

class UserDict(TypedDict):
    id: int
    name: str

def first(items: list[T]) -> T | None:
    return items[0] if items else None

user: UserDict = {"id": 1, "name": "Ada"}
payload: Any = user
print(first([1, 2]), user["name"], payload["name"])

Expected output: 1 Ada Ada

Hints are not checked at runtime

The interpreter stores annotations and then shrugs — nothing validates them. The call below runs happily and returns a string from an int-typed function, because hints live in __annotations__ and nowhere else:

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

print(double("ha"))
print(double.__annotations__)

Expected output:

haha
{'x': <class 'int'>, 'return': <class 'int'>}

That is not a flaw in your code — it is the design. The runtime stays flexible; enforcement belongs to a checker. Keep tests for behaviour (chapter 21) and hints for shapes.

Catching mistakes with mypy

mypy reads your hints and reports mismatches without running the program; pyright (the engine behind VS Code’s Pylance) does the same job. Install with python3 -m pip install mypy, then point it at a file. This one has a deliberate mistake on the last line:

def average(numbers: list[int]) -> float:
    return sum(numbers) / len(numbers)


total = average([1, 2, 3])
print(f"average = {total}")
print(average("not a list"))

Expected output: running python3 -m mypy bad_average.py:

bad_average.py:7: error: Argument 1 to "average" has incompatible type "str"; expected "list[int]"  [arg-type]
Found 1 error in 1 file (checked 1 source file)

Run the same file with python3 instead and it prints average = 2.0, then crashes with TypeError: unsupported operand type(s) for +: 'int' and 'str' deep inside average. The checker points at the bad call; the runtime points at the consequences. Fix the call and mypy answers Success: no issues found in 1 source file — and it exits with status 1 while errors remain, which is what makes it a clean CI gate. Run it across a whole project with python3 -m mypy .; pyright is invoked the same way as pyright file.py.

Common mistakes

• Annotating the obvious and skipping the edges — labelling every local adds noise, while leaving public function signatures bare gives a checker nothing to work with. Signatures first.
• Reaching for Any to silence a complaint — Any disables checking for everything downstream of it; prefer object, a union, or a TypeVar.
• Treating hints as runtime validation — a wrong call may still run and corrupt data, as double("ha") proved. Hints need a checker to mean anything.
• Mixing spellings in one file — Optional[X] and X | None are identical, but alternating between them reads like two authors; pick X | None in new code.
• Checking only one file — mypy is quiet about unimported modules by default, so run python3 -m mypy . over the project or errors hide in the files you forgot.

Practice checklist

1. Annotate three functions from an old script and run mypy; fix everything it reports.
2. Rewrite every Optional[X] you wrote as X | None and confirm mypy stays silent.
3. Define a TypedDict for a JSON payload you normally treat as an untyped dict.
4. Prove the runtime does not enforce hints: call a function with the wrong type and watch it run.
5. Run python3 -m mypy . across a small project and note which errors surprise you most.

What's next?

Your intentions are now written down — but nothing yet proves the code behaves. Next you build the safety net: Testing with pytest shows how tests are named, grouped and run so refactors stop being frightening.