Document callable contracts
Annotate function inputs and outputs so callers and analysis tools can understand the intended interface.
Python · Module
typing
The typing module provides standard constructs for annotating Python code with type information. Type hints guide third-party tools such as type checkers, IDEs, and linters, but Python does not enforce them at runtime.
- Since
- 3.5
How it works
Import typing constructs to express richer annotations for functions, variables, collections, and structured dictionaries. These annotations support type checkers, IDEs, and linters, but Python itself does not enforce them during execution.
Syntax
import typing
from typing import TypeAlias, TypeVar
# annotations use typing constructs
name: str
def function(value: int) -> str: ...Key points
- typing contains standard constructs for expressing type information in Python code.
- Annotations are useful to static-analysis and development tools even though the interpreter does not enforce them.
- The module evolves as Python adds new type-system capabilities.
- Use the referenced type-system specification for authoritative rules beyond individual API descriptions.
Common mistakes
- Annotations alone do not validate values or prevent incompatible calls at runtime; use a type checker or explicit runtime validation when enforcement is required.
Example: TypedDict for dictionary-shaped data
from typing import TypedDict
class User(TypedDict):
name: str
age: int
def describe(user: User) -> str:
return f"{user['name']} is {user['age']}"
print(describe({'name': 'Ada', 'age': 36}))TypedDict describes the expected keys and value types for dictionary-shaped data; static type checkers can validate calls while Python executes the ordinary dictionary.
When to use it
Model collection contents
Describe nested collections and generic values with precise element or key/value types.
Type structured mappings
Specify the expected shape of dictionary-based records without replacing ordinary dictionaries.
Express advanced interfaces
Add metadata or protocols that help tools reason about APIs and structural behavior.
Interview questions
QWhat is the purpose of the typing module?
The typing module supplies standard vocabulary for type hints, including generic and specialized forms. Python retains the annotations, while third-party tools such as type checkers, IDEs, and linters can analyze them.
Follow-up: How would you enforce an annotation at runtime? Use explicit validation or a library designed for runtime validation; typing annotations by themselves do not perform that enforcement.
QWhat does TypedDict provide?
TypedDict describes a dictionary type with an expected set of keys, associating each key with a consistent value type. At runtime, instances remain ordinary dict objects, so the constraints are primarily for static analysis.
Follow-up: What runtime behavior should code rely on? Treat the value as a normal dictionary and perform any required key or value checks explicitly.
QWhen was typing introduced, and where is the type system specified?
The module was added in Python 3.5 and has since gained additional type-hinting constructs. The current documentation also points to the canonical Python type-system specification for the up-to-date rules.
Follow-up: Where should a type-system rule be verified? Consult the official type-system specification referenced by the module documentation rather than assuming every checker-specific behavior is universal.
Related
AnyAnnotatedCallableGenericLiteralProtocolTypeAliasTypeTypedDict