@overload - when Union is not enough

Question

Accepted Answer

The problem with 'def f(x: int | str) -> int | str' is that the type checker loses the correlation between input and output. If you call f(42), mypy sees the return as 'int | str' - it doesn't know that an int input guarantees an int output. Every caller then has to do runtime narrowing (isinstance checks or type: ignore) to use the result without errors. @overload lets you declare multiple signatures: one for int -> int, one for str -> str. The real implementation (without @overload) is where the actual code lives and is hidden from type checkers; it can use Union internally. With @overload in place, mypy sees f(42) as int and f('hello') as str - no narrowing needed at the call site. Use @overload when the return type depends specifically on the argument type in a way TypeVar can't express (TypeVar would work if the output type equals the input type exactly, but @overload handles asymmetric cases like 'int input -> str output'). This pattern comes up frequently in pandas-style APIs where method chaining depends on knowing the exact return type.