How do type hints work in Python and what do they buy you?

Python uses gradual typing. You can annotate some functions and leave others dynamic, and the checker infers what it can. Annotations are evaluated as expressions unless postponed, which matters for forward references and import cycles.

from typing import Protocol

class Notifier(Protocol):
    def send(self, message: str) -> None: ...

def alert(notifier: Notifier, message: str) -> bool:
    notifier.send(message)
    return True

class EmailNotifier:
    def send(self, message: str) -> None:
        print("email:", message)

alert(EmailNotifier(), "disk full")

The vocabulary

• Use list[str] and dict[str, int] on modern Python instead of typing.List
• Use X | None for optional values instead of Optional[X] in new code
• TypeVar expresses a relationship between input and output types
• Protocol describes a structural interface without a base class

Hints are not validation. A function annotated to take int happily accepts a string at runtime, and frameworks that claim runtime enforcement generate checks themselves. The value is catching mistakes before deployment and making interfaces self-documenting for editors and reviewers.