How does typing.assert_never turn a missed Enum member into a type error?

**The problem it solves.** Dispatch over a closed set of variants — an `enum.Enum` of severities, a `Literal` union of codec names, a set of message classes — is everywhere. The failure mode is not the code you write today; it is the member somebody adds in six months, whose new value silently falls into a `else: pass` or a `case _:` default in three of the eleven places that dispatch on it. Exhaustiveness checking converts that from a production surprise into a type-check failure at the moment the member is added. **How it works: narrowing to the bottom type.** `typing.Never` is the bottom type: no value has it. Narrowing produces it naturally. If a value declared as an enum is compared against each member in turn, then in the final `else` the checker has subtracted every member and is left with nothing — `Never`. The same happens in a `match` statement whose `case` patterns cover every member and whose final `case _:` is therefore unreachable. `typing.assert_never(value)` is declared to take an argument of type `Never`, so the call type-checks *only* when the checker agrees the branch is unreachable. Add a member, the branch becomes reachable with that member's type, the argument no longer matches, and you get an error naming the offending type — which is precisely the list of dispatches you must update. ```python import enum from typing import assert_never class Severity(enum.Enum): INFO = "info" WARN = "warn" ERROR = "error" def sink(level: Severity) -> str: match level: case Severity.INFO: return "stdout" case Severity.WARN: return "stderr" case Severity.ERROR: return "pager" case _: assert_never(level) ``` **Runtime behaviour.** `assert_never` is a real function, not a compile-time marker, and reaching it raises `AssertionError` including a repr of the argument. That is not redundant with the static check: values cross into a typed program from JSON, environment variables and databases, and a checker only ever verified the *declared* type. If an ingest stage decodes a severity string it has not seen — the kind of drift that shows up alongside an encoding mismatch, when an upstream producer changes format — the dispatch fails loudly at the boundary instead of quietly routing the record nowhere. Unlike an `assert` statement, this guard is a function call and survives running the interpreter with `-O`. **Where it applies.** Enum members, `Literal` unions of strings or ints, and unions of classes narrowed by `isinstance` all work, as long as the checker can see the declared type precisely. It cannot help if the value has been widened to `str` or `object` on the way in, if the enum gains members dynamically, or if you compare with `==` against something the checker cannot tie back to the literal set. In those cases the fix is upstream: parse once into the enum, then dispatch on the enum. **The weaker alternatives.** A declared non-optional return type gives partial exhaustiveness for free: if a function annotated `-> str` has an unhandled path that falls off the end returning `None`, that is an error. But it only works for functions that return a value, the error message points at the function rather than the missed variant, and it does nothing for statement dispatch that performs side effects. `raise AssertionError(f"unhandled {level!r}")` gives the same runtime safety and zero static safety. `assert_never` gives both, in one line. **Practical use.** Put it in the default branch of every dispatch that must be revisited when the variant set grows, and treat any checker error naming it as a to-do list rather than a nuisance. On 3.10 and earlier the helper does not exist in the standard library; a one-line local shim taking a `Never` parameter and raising behaves identically, and checkers recognise the pattern. **Why a dispatch table is not equivalent.** Replacing the branches with a mapping — `SINKS: dict[Severity, str]` and a lookup — reads well, but it gives up the check entirely: a dict literal missing a member is a perfectly well-typed dict, and the miss surfaces at runtime as a `KeyError` on whichever record happens to carry the new severity. If you prefer the table form, get exhaustiveness back by building it from the enum and asserting the sizes match at import time, or keep the `match` form for the dispatches that matter most. The general rule is that exhaustiveness checking is a property of *branching* code, so it costs a branch to have it. **Cost and placement.** The pattern is close to free: one extra branch and one call that never executes in a correct program. What it is not is a substitute for validation at the edge. In an ingest pipeline the right shape is a single parsing step that turns an incoming string into an enum member, raising on anything unknown, followed by internal dispatches that all end in this guard. Then the static check protects developers extending the variant set, and the parser protects the process from data that never respected the type in the first place.