Why must a plain bool @typing.overload stub come after the Literal[True] one?

## Resolution is first-match, in source order A type checker treats the decorated stubs as an ordered list of candidates. For a given call it walks them from the top and selects the first stub whose parameters accept the supplied arguments; that stub's return type becomes the type of the expression. The implementation's own signature is not a candidate — it is checked separately for consistency, but calls never resolve against it. Order is therefore semantic, not cosmetic. Whatever sits above shadows whatever sits below for any call both would accept. ## Why the Literal stubs must be above the bool stub `Literal[True]` and `Literal[False]` describe exactly one value each, and both are subtypes of `bool`: every value they accept, `bool` also accepts. So a `bool` stub is strictly broader, and if it comes first it swallows every call: ```python from typing import Literal, overload @overload def to_payload(rows: list[float], *, csv: bool) -> str | bytes: ... # WRONG: first @overload def to_payload(rows: list[float], *, csv: Literal[True]) -> str: ... # unreachable ``` A call with `csv=True` matches the broad stub, so the call site is typed `str | bytes` and every caller is back to narrowing a union — the exact problem the overloads were written to remove. Reversed, the literal stubs match the literal calls and the broad one only catches what they miss. ## Why the bool fallback stub exists at all It is tempting to delete the broad stub once the two literal ones are in place. Do that, and this stops type-checking: ```python flag = load_flag() # a variable of type bool, not a literal to_payload(rows, csv=flag) # matches neither Literal stub ``` When the flag is only known to be *some* `bool`, no literal stub accepts it, and with no fallback the call is an error. The fallback's job is to accept that case, and its return must be the union of the specific returns — `str | bytes` — because that genuinely is all anyone can know. The ordering rule and the fallback rule are two halves of the same idea: specific first, general last, general returns the union. ## Overlapping stubs with incompatible returns The other ordering hazard is the diagnostic checkers phrase as *overlapping overloads with incompatible return types*. It fires when an earlier stub accepts every call a later stub accepts, but promises an unrelated return type. The subtle instance in Python is numeric: ```python @overload def tag(x: int) -> int: ... @overload def tag(x: bool) -> str: ... # unreachable: bool is a subclass of int ``` `bool` subclasses `int`, so `tag(True)` matches the first stub and is typed `int`, never `str`. The second stub can never be selected, and the declared behaviour for booleans is a lie. Swapping them fixes it: `bool` first, `int` second, and each call gets the type it deserves. The same trap appears with `object` or `Any` parameters near the top of a stub list, with an untyped `*args, **kwargs` catch-all stub written first, and with an optional parameter that makes an earlier stub accept a call an author believed only a later one could take. ## Practical rules - Sort stubs from most specific to most general; never let a catch-all sit above a specific one. - Give the catch-all a return type that is compatible with — usually the union of — everything below it, so the specific stubs remain refinements rather than contradictions. - Remember that `bool` is a subtype of `int`, and `Literal[...]` values are subtypes of their base type; those two facts cause most real overlap warnings. - Do not let ordering carry meaning at runtime. Nothing in this section changes execution: one function object exists, and its body still branches on the flag itself. ## How to say it "Resolution is first-match top-down, so ordering is part of the meaning. `Literal[True]` is narrower than `bool`, so it has to be above it — otherwise the broad stub shadows the specific ones and every caller gets the union back. I still keep the `bool` stub last, returning the union, for callers whose flag is a variable rather than a literal."