Textbook of Python

Also known as: type annotation, PEP 484

A type hint (or type annotation) is a syntactic annotation that specifies the expected type of a variable, function parameter, or return value. Introduced in PEP 484 (Python 3.5), type hints are written using the colon syntax for variables and parameters (x: int = 5, def f(name: str) -> bool:) and are stored in the function's __annotations__ dictionary. They are completely ignored by the Python runtime — they are metadata for tools and humans.

Type hints are checked by external static analysis tools, primarily mypy (the reference type checker, developed by Jukka Lehtosalo and Guido van Rossum) and pyright (Microsoft's faster alternative, used in Pylance for VS Code). These tools analyse your code without running it and report type errors — passing a string where an int was expected, accessing a method that might not exist on a union type, returning the wrong type.

The typing module provides the building blocks for complex type annotations: Optional[X] (equivalent to X | None since 3.10), Union[X, Y], List[int], Dict[str, int], Tuple[int, ...], Callable[[int], str], TypeVar, Generic, Protocol, and Literal. Python's type hint system is gradual — you can add type hints incrementally without converting your entire codebase. This pragmatic approach has driven widespread adoption across the Python ecosystem.