How do type hints work in Python?

Q: How do type hints work in Python?

**Target Audience:** Python developers who have seen `def f(x: int) -> str:` and want to know what it really does, from the interpreter and from a type checker. **Difficulty:** Medium **Python version:** Runtime behaviour checked on CPython 3.11.17 and 3.13, and in the page runner (Pyodide 0.25.1, CPython 3.11.3). Type-checker output is from mypy 2.3.1 (with `--python-version 3.11`) and pyright 1.1.414. > **How to read this doc:** Every idea is explained in plain language first, then tagged with `📌 Interview term:` so you also learn the exact words an interviewer expects. All output shown was produced by actually running the code; the **Verified** section quotes it in full. ## 1. Why This Even Matters — A Story First You are moving house. You write "KITCHEN — glasses" on a box. The movers do not open the box to check; they carry it wherever they like, and if someone packed shoes in it, nothing stops them. But your friend with the floor plan reads every label *before the truck leave

The problem

Question presented to candidate: "Walk me through type hints in Python. If I annotate a parameter as int and pass a string, what happens? Then what are the hints actually for, and who reads them?"

What a strong answer should cover:

Hints are annotations: expressions attached to parameters, return values and variables; CPython stores them in __annotations__ and never enforces them at runtime
Static type checkers (mypy, pyright) read them without running the code and report mismatches; IDEs use them for completion; this is gradual typing, where unannotated code is treated as Any
Core vocabulary: list[int], dict[str, int], X | None (same as Optional[X]), Callable, Any, Literal, plus TypeVar for generics and Protocol for structural typing
When annotations are evaluated: eagerly at def time up to 3.13, as strings with from __future__ import annotations, lazily by default from 3.14 (PEP 649); typing.get_type_hints() resolves forward references
Some libraries do read hints at runtime: dataclasses builds fields from them, Pydantic and FastAPI validate data with them

Code / implementation expected: Optional — annotate a function, pass a wrong type to show nothing happens at runtime, then show what a checker reports or what __annotations__ holds.

typing

Try it yourself

Sketch your approach before you read the solution. That is what the interview tests.

Stuck? Get a hint.

A short nudge toward the approach. It will not give the answer away.

Solution

Target Audience: Python developers who have seen def f(x: int) -> str: and want to know what it really does, from the interpreter and from a type checker. Difficulty: Medium Python version: Runtime behaviour checked on CPython 3.11.17 and 3.13, and in the page runner (Pyodide 0.25.1, CPython 3.11.3). Type-checker output is from mypy 2.3.1 (with --python-version 3.11) and pyright 1.1.414.

How to read this doc: Every idea is explained in plain language first, then tagged with 📌 Interview term: so you also learn the exact words an interviewer expects. All output shown was produced by actually running the code; the Verified section quotes it in full.

1. Why This Even Matters — A Story First

You are moving house. You write "KITCHEN — glasses" on a box. The movers do not open the box to check; they carry it wherever they like, and if someone packed shoes in i

The solution is hidden so you can try first

12 min read · 11 sections

Run the code

Edit the code and run it here. Each console line with an expected value becomes a test.

PythonHints are stored, not enforced: __annotations__, forward references, evaluation time

Practice

PythonHint objects at runtime: unions, Annotated, dataclasses, a tiny checker, string annotations