When is @typing.overload better than annotating one union return type?

## The problem overloads solve Annotations describe one signature. When a function's return type depends on *which* arguments came in, a single signature can only tell the truth by widening: it returns a union, and it tells every caller the same thing regardless of what that caller passed. ```python def read_row(key: str, *, text: bool) -> str | bytes: ... value = read_row("row-1", text=True) # checker says: str | bytes value.upper() # error: bytes has no upper ``` The author knows `text=True` means `str`. The annotation cannot say so, so every call site pays with a narrowing dance — an `isinstance` check, an `assert`, or a cast — for information that was available at the call. `typing.overload` restores that correlation. Each decorated stub is one *shape* of the callable, and a checker resolves a call against the stubs rather than against the implementation: ```python from typing import Literal, overload @overload def read_row(key: str, *, text: Literal[True]) -> str: ... @overload def read_row(key: str, *, text: Literal[False]) -> bytes: ... def read_row(key: str, *, text: bool) -> str | bytes: raw = key.encode("utf-8") return raw.decode("utf-8") if text else raw ``` Now `read_row("row-1", text=True)` is a `str` at the call site, with no narrowing and no cast. ## The second thing overloads buy: forbidding combinations A union return is about the output; overloads also constrain the *input space*. If a callable accepts `(source: str)` or `(source: bytes, *, encoding: str)` but never `(source: str, *, encoding: str)`, two stubs express exactly that, and the illegal third combination fails to match any of them. A single signature would have to make `encoding` optional for both and hope a comment is read. This is the everyday reason libraries use overloads for flag-shaped parameters, mode strings, and functions whose arity changes meaning — a `Literal` flag keys the shape, and combinations nobody implemented simply do not type-check. ## The contract with the implementation The single undecorated implementation is invisible to callers, but it is not unconstrained. Its parameters must be broad enough to accept everything any stub accepts (typically the union of the stub parameter types, or a plain `bool` where the stubs used `Literal[True]`/`Literal[False]`), and its return type must be compatible with each stub's declared return. A checker verifies that relationship, which is what stops the stubs from promising something the body cannot deliver — though only structurally: it checks that the body *can* return `str`, not that it returns `str` exactly when `text` is true. ## When not to use them Three cases where overloads are the wrong tool: - **A type variable already expresses the relationship.** If the return is just the element type of the argument, `def first[T](values: list[T]) -> T` says it in one signature. Since Python 3.12 that PEP 695 syntax needs no separate `TypeVar` declaration. Overloads here are pure duplication. - **The shapes have nothing in common.** Two unrelated behaviours behind one name is usually two functions with two names, which reads better and produces better errors. - **The combinatorics explode.** Overloads multiply: three flag parameters is eight stubs, kept in sync by hand. Past a handful, take the union return and let callers narrow, or split the API. The diagnostics cost is real too. When an argument is wrong, a checker cannot say "this parameter is wrong" — it says the call matched no variant and often lists them all. Long overload sets make error messages long. ## And the standing caveat Everything above happens in the checker. Overloads dispatch nothing and validate nothing at runtime; the interpreter sees one function whose body must still handle every case it was declared to accept. They buy call-site precision and design documentation, not enforcement. ## How to answer "When the return type is a function of the arguments, or when some argument combinations should be illegal. A union return makes every caller narrow something I already know; overloads move that knowledge into the signature. I pay for it with duplication, so I only do it where the correlation is real, and I reach for a type variable first when the return is simply the argument's own type."