Python Type Hints

Satellite · Functions

Type Hints

PEP 484 introduced optional typing to Python. Learn the basics so your functions communicate intent clearly and static analyzers can help.

Annotate functionsUse typing helpers

Functions

from typing import Optional, Sequence

def find_user(user_id: str, users: Sequence[dict]) -> Optional[dict]:
    ...

• Parameters and return values use colon and arrow syntax.
• Use Optional[T] (or T | None in Python 3.10+) to represent nullable returns.

Typing module essentials

Helper	Purpose
List[T], dict[str, int]	Generic collections
Union[A, B] or `A	B`
Literal[...]	Exact value constraints
TypedDict, NamedTuple, Protocol	Structured types
Callable[[ArgTypes], ReturnType]	Function signatures

Tooling

• Run mypy, pyright, or ruff check --select=ANN to verify annotations.
• Use typing.TYPE_CHECKING to guard import-heavy type-only dependencies.

Next up in your learning path

Return values

Pair type hints with documented returns.

Companion

Dataclasses & OOP

Annotate attributes for dataclasses and classes.

Advanced

Argument kinds

Combine typing with positional/keyword rules.

Reference