Type hints
A type hint is a note in your code that says what kind of value belongs where, such as n: int or -> int. Step through a five-line file, hints.py, to see what Python does with hints (it stores them and never checks them), why double("ha") quietly returns 'haha', and how a type checker, mypy, reads the same file without running it and flags the bug on line 5.
5 quick questions
Pick an answer to see why. Your score saves with your progress.
01In def area(w: float, h: float) -> float: what does -> float say?
-> after the parameter list is the return hint: the function is meant to give back a float. Nothing converts or checks the result at run time.
02double is defined as def double(n: int) -> int: return n * 2. What does python run for print(double("ha"))?
Python does not enforce hints. n becomes "ha" and "ha" * 2 repeats the string, so it prints haha with no error.
03Where does Python keep the hints of a function named double?
Python stores them in the function's __annotations__ dictionary, here {'n': int, 'return': int}. Tools can read them; the interpreter does not act on them.
04What does a type checker such as mypy do with hints.py?
mypy is a separate tool. It analyses the code without running it and reports mismatches, such as passing a str where n: int asks for an int. It does not change or block your program.
05Which hint says a variable holds either an int or None (Python 3.10 and later)?
The | operator builds a union type: int | None means an int or None. Older code writes Optional[int] from the typing module.
Glossary
- Type
- The kind of a value, such as int (whole number), str (text) or list. It decides what you can do with the value.
- Type hint (annotation)
- A note in the code that says which type a parameter, return value or variable should have, written n: int or -> int.
- __annotations__
- The dictionary where Python keeps a function's hints, for example {'n': int, 'return': int}.
- Run time
- While the program is running. Python does not check hints at run time.
- Type checker
- A separate tool, such as mypy, that reads code without running it and reports values that do not match their hints.
- mypy
- A widely used Python type checker, installed with pip and run as mypy file.py.
- Union (int | None)
- A hint that allows any one of several types; int | None means an int or None.
Notes and sources
- The typing documentation says it plainly: the Python runtime does not enforce function and variable type annotations. Tools such as type checkers, IDEs and linters use them.
- The dictionary holds the class int itself, shown as <class 'int'>; the figure writes int. Since Python 3.14 annotations are evaluated lazily, when you first read them, but __annotations__ gives the same dictionary.
- mypy prints each message on one long line; the terminal in the figure wraps it, and an indented row continues the row above.
- mypy is one type checker among several (pyright and others work the same way). It is installed with pip, not shipped with Python.
- list[int] works from Python 3.9 and int | None from Python 3.10; older code writes List[int] and Optional[int] from the typing module.
- Python library: typing (support for type hints)
- Python tutorial: Function annotations
- Python reference: Function definitions (annotations, __annotations__)
- Python reference: Annotated assignment statements
- Python HOWTO: Annotations best practices
- Python library: Union type (X | Y)
- PEP 484: Type hints
- PEP 526: Syntax for variable annotations
- mypy documentation: Running mypy
- mypy documentation: Error codes (arg-type)
Quiz Unlocks after the last step.