Python Type Hints Complete Guide: Write Self-Documenting, Bug-Free Code

from typing import Optional

# Python 3.9+ built-in generics (preferred)
def get_user(user_id: int) -> dict[str, str] | None:
    pass

# Python 3.8 compatible
from typing import Dict, List, Optional, Tuple
def process(items: List[str], config: Dict[str, int]) -> Optional[str]:
    pass

# Function types
from typing import Callable
def apply(fn: Callable[[int, int], int], a: int, b: int) -> int:
    return fn(a, b)

from typing import Optional, Union, Literal

# Optional[T] == T | None
def find_user(email: str) -> Optional[dict]:  # Can return None
    pass

# Union: multiple types
def parse(value: Union[str, int, bytes]) -> str:
    if isinstance(value, bytes):
        return value.decode()
    return str(value)

# Literal: specific values only
Status = Literal['pending', 'active', 'inactive']
def set_status(user_id: int, status: Status) -> None:
    pass
# set_status(1, 'deleted')  # mypy error: not a valid Status

from typing import TypedDict, Protocol, runtime_checkable

# TypedDict: typed dictionary structure
class UserRecord(TypedDict):
    id: int
    name: str
    email: str
    is_active: bool

def get_user(user_id: int) -> UserRecord:  # Returns must match structure
    return {'id': 1, 'name': 'Alice', 'email': 'alice@example.com', 'is_active': True}

# Protocol: structural typing (duck typing with types)
@runtime_checkable
class Serializable(Protocol):
    def to_dict(self) -> dict: ...
    def to_json(self) -> str: ...

# Any class with these methods satisfies Serializable — no inheritance needed
class User:
    def to_dict(self): return {'id': self.id}
    def to_json(self): return json.dumps(self.to_dict())

def serialize(obj: Serializable) -> str: return obj.to_json()

# mypy.ini or pyproject.toml
[mypy]
strict = true
# Enables: --disallow-untyped-defs, --disallow-any-generics,
#          --no-implicit-optional, --warn-return-any, and more

# Run in CI:
mypy src/ --strict

# Common fixes for strict mode:
# 1. Add return type to every function
# 2. Replace Dict with dict[str, Any]
# 3. Handle Optional returns before using value
# 4. Add TypeVar for generic functions