Type hints and typing

Type hints, introduced in PEP 484, are annotations that declare the expected types of variables, parameters, and return values. They are not enforced at runtime by default; they are checked by external tools like mypy, pyright, and ruff. Type hints improve code clarity, IDE support, and refactoring safety.

Use the colon syntax for variables and parameters, and the arrow syntax for return types. Built-in generic types like list, dict, and tuple support subscript notation directly since Python 3.9, so you can write list of int instead of importing List from typing.

The typing module provides types and constructs for type hints, including Optional, Union, Any, Callable, TypeVar, Generic, Protocol, Literal, Final, ClassVar, NewType, and TypedDict. Many of its features have moved into built-ins over the years, but typing remains the source for advanced types.

Optional of T is shorthand for Union of T and None, meaning the value can be of type T or None. Since Python 3.10, the pipe syntax replaces both: T pipe None for Optional, T pipe U for Union. The pipe form is now preferred in modern code.

Any is a special type that disables type checking for a value. A value of type Any can be assigned to anything and anything can be assigned to it. It is an escape hatch for code that is dynamic or for migrating untyped code. Overusing Any defeats the purpose of type hints.

A TypeVar is a type variable used to write generic functions and classes. It allows you to express that two parameters or a parameter and return value have the same type without committing to a specific one. Generics enable type-safe containers and higher-order functions.

A Protocol, defined in typing, enables structural subtyping or static duck typing. A class is considered a subtype of a Protocol if it implements the required methods and attributes, without explicitly inheriting from it. This combines the flexibility of duck typing with static type checking.

TypedDict lets you describe a dictionary with a fixed set of string keys and specific value types for each. It is useful for typing JSON-like data without converting to a class. Type checkers verify that you only access declared keys with the correct value types.

A Literal type restricts a value to specific constants. For example, Literal of red, green, blue means the value must be exactly one of those strings. It is useful for typing flags, enums, and discriminated unions where the set of allowed values is small and known.

Type hints are stored as strings or as actual type objects in dunder annotations on functions and classes. By default they are not enforced at runtime. Libraries like Pydantic and dataclasses can use dunder annotations to perform runtime validation or to generate behavior, blurring the line between hints and types.

Mypy is a static type checker for Python developed by the original author of PEP 484. It analyzes annotated code and reports type errors before runtime. Alternatives include pyright from Microsoft, used by Pylance and increasingly considered the fastest, and pyre from Meta. As of 2026, pyright and ty are the dominant fast type checkers.

PEP 695, accepted for Python 3.12, introduces a new dedicated syntax for declaring type aliases, generic functions, and generic classes. Instead of TypeVar declarations, you can write a generic function using bracket notation directly after the name. This is cleaner and more Pythonic than the older typing-based approach. ---