↑ All examplesPython docs reference

Journey

Types

This journey maps Python's runtime object model to optional static annotations so learners know what types can and cannot promise.

In this journey

  • Keep runtime and static analysis separate.
  • Describe realistic data shapes.
  • Scale annotations for reusable libraries.

Keep runtime and static analysis separate.

The first lesson is that annotations describe expectations for tools while ordinary Python objects still run the program.

RUNTIMEvaluerunsSTATIC TOOLSx: intchecks
Runtime values run the program; static tools inspect separate annotations and report before execution.
  • Type Hints

    Use this example to document expected types and feed type checkers.

  • Protocols

    Use this example to describe required behavior by structural shape.

  • Enums

    Use this example to name a fixed set of symbolic values.

  • Runtime Type Checks

    Use this example to show `type()`, `isinstance()`, and `issubclass()` without turning Python into Java.

Describe realistic data shapes.

Typed Python becomes useful when annotations explain optional values, unions, callables, and JSON-like records.

datafieldsTypedDictvariantUnionabsenceOptional
Real data contracts combine fields, variants, and expected absence instead of one scalar type.
  • Union and Optional Types

    Use this example to show `X | Y` and `None`-aware APIs.

  • Type Aliases

    Use this example to name complex types with `type` statements or aliases.

  • TypedDict

    Use this example to type dictionary records that come from JSON.

  • Literal and Final

    Use this example to express constrained values and names that should not be rebound.

  • Callable Types

    Use this example to type functions that are passed as arguments.

Scale annotations for reusable libraries.

Advanced typing exists to preserve information across reusable functions, containers, and decorators.

callerLIBRARY APITPoverloadstyped result
Reusable APIs carry caller contracts through the library boundary with generics, parameters, and overloads.
  • Generics and TypeVar

    Use this example to write reusable typed containers and functions.

  • ParamSpec

    Use this example to preserve callable signatures through decorators.

  • Overloads

    Use this example to describe APIs whose return type depends on the input shape.

  • Casts and Any

    Use this example to show escape hatches and their tradeoffs.

  • NewType

    Use this example to create distinct static identities for runtime-compatible values.