What Are Type Hints in Python?

Type hints are notes that you attach to the parameters and the return value of a function. Since Python 3.9 you can use the built-in container types directly as subscripts, and since Python 3.10 you can write a union with the pipe operator, so most of the typing module is no longer needed for everyday code.

def summarise(items: list[int], *, scale: float = 1.0) -> tuple[int, float]:
    total = sum(items)
    return total, total * scale


print(summarise([1, 2, 3]))      # (6, 6.0)
print(summarise.__annotations__)

The annotations dictionary reads items: list[int], scale: float and return: tuple[int, float]. Notice that the keyword-only marker is a plain asterisk with no annotation, and that is completely normal.

Two details are worth pointing out. The annotations are stored on the function object, so they are available while the program is running, and you can read them directly or resolve any string annotations with typing.get_type_hints. And because the annotations are evaluated when the def statement runs, an annotation that refers to a name which does not exist yet raises a NameError at definition time. That is the reason why from __future__ import annotations exists, because it postpones the evaluation and turns every annotation into a plain string.

Here is the rest of the syntax you should be able to recognise. Optional[int] is now written as int | None. A fixed sequence of one type is Sequence[str]. A callable is Callable[[int, str], bool]. And a class that can be either of two unrelated types is written as a union. If you see old code that uses List and Dict from the typing module, then it was written before Python 3.9.

Type hints are documentation for tools, and they are not contracts that the interpreter enforces. If you call a function with the wrong type, the code simply runs.

import typing


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


result = double('hello')   # no type error is raised
print(result)              # hellohello
print(typing.get_type_hints(double))

Because a string has no __mul__ method for an integer, the multiplication operator repeats the string instead, and the function returns hellohello without any complaint. The interpreter never looks at the annotation.

A static type checker such as mypy or pyright does look at it. It reads the annotations, it builds a model of the program, and it reports the mismatches before the code ever runs. In this example it would point out that the argument "hello" is a string where an integer was declared, and that the return type of value * 2 may not be an integer.

The runtime side is not completely empty, though. typing.get_type_hints resolves the annotations into real objects and raises a NameError if an annotation names something that cannot be imported, which catches typos in forward references. Dataclasses and pydantic models also read the annotations at run time in order to build their behaviour, and tools such as FastAPI use them to validate incoming requests and to generate documentation.

So the honest way to describe this is that type hints do not change what Python executes. They change what a tool is able to prove about the program before it executes. That is why a project can adopt them gradually, one file at a time, without changing any behaviour.

Because Python is dynamically typed by design, and the contract of the language is that the interpreter checks what it can while the program runs and leaves the rest to discipline and to tooling. Making annotations mandatory would have broken every existing program on the day they shipped, so the design settled on gradual typing. Hints are advisory, and a codebase can be typed one module at a time.

They cost almost nothing at run time because they are metadata and not instructions. The def statement evaluates the annotation expressions once, when the function is defined, and then it stores the results on the function object. The interpreter does not look at them again on every call. If even that small cost matters to you, then from __future__ import annotations makes the annotations lazy, so they are stored as strings and are never evaluated unless something asks for them. That is how a forward reference to a class that is defined later in the same file works at all.

The benefit is static analysis. A checker such as mypy or pyright reads the annotations and it can prove things that the interpreter never would. It can show that a function always returns a list of strings, that an optional attribute is checked before it is used, and that the key and the value of a dictionary have the types that the code assumes. It can also catch the most common runtime errors before they are deployed.

The techniques that make this practical are worth naming. Generics with TypeVar express that a function returns the same type that it was given. Protocol expresses a structural interface without any inheritance. TypedDict describes a dictionary with a fixed shape. The final point to make in an interview is that type hints are the most valuable thing that Python borrows from statically typed languages, and they work because they are optional, because they can be added little by little, and because they are erased before the program runs.