ADR-0033: Warn about a match that leaves members of its subject unmatched¶
Status¶
Accepted
Date¶
2026-11-15
Context¶
ADR-0017 decided that TyPy warns where CPython 3.12 to 3.15 give a
SyntaxWarning while compiling, and nowhere else, so that style checks
stay with linters. CST-07 asks for one warning CPython never gives: a
match whose cases miss part of the subject's type.
TyPy knows each variable's type when it compiles, and a union, an
optional or a bool has a fixed set of members. A match over such a
subject is often written to handle each member, as an if chain over
isinstance tests would be, and a case forgotten there is a mistake the
type of the subject shows. Pyright reports it under
reportMatchNotExhaustive, and mypy under its optional exhaustive-match
error code, so Python developers who use a type checker already see it.
The same analysis decides whether a match can end without any case
running. A function that returns a value from every case of a complete
match must not be refused with E0405 for reaching its end.
Options considered¶
- Warn where CPython warns, and about a
matchthat leaves members of its subject's type unmatched. One warning beyond CPython's, about the types TyPy checks, and none about style. - Warn only when the project asks, through
typy.tomlor a flag. The default would keep ADR-0017 exactly, at the cost of an option and its tests, and the mistake would go unreported for most programs. - No warning. Keep ADR-0017, and use the analysis only for E0405. CST-07 would be rejected.
Decision¶
TyPy will use option 1, and this record supersedes ADR-0017, whose rules otherwise stand.
- W0401 is a
matchwhose subject's type has two or more members, where some member is matched by no case without a guard. The members are each member of a union,Noneof an optional, andTrueandFalseof abool. The warning names the members left, and its help offerscase _:for the rest. - A case covers a member when its pattern matches every value of it: a
capture or
_;None,TrueorFalsefor the member of that value; a class pattern whose sub-patterns are captures or_, for a member every value of which is an instance of the class;[*rest]for a list or tuple, and captures for a tuple of their number;{}or{**rest}for a dict; and anasor|pattern through its parts. A case with a guard covers nothing, since the guard may be false. - A
matchwhose cases cover every member cannot end without running a case, so a function that returns from each case does not reach its end. - A
matchwhose checking reported an error gets no warning, so one cause gives one diagnostic. - A subject of one member, such as
intorstr, never gets the warning: its values cannot be listed, andcase _:is the only way to cover them.
Consequences¶
- A forgotten case of a union is reported where it is written, as a type
checker reports it, and
--deny-warningsmakes it an error. - A program that is clean under
python -W errormay get W0401; this is the one warning that is not CPython's. - The analysis reads patterns without their values, so a set of cases
that covers a member only together, such as
case []:andcase [x, *rest]:for a list, is not seen as complete. Such amatchneedscase _:to end a function that returns a value. - Further warnings of TyPy's own need a record of their own, as this one did.
Related requirements¶
CST-06, CST-07, DIA-07, DIA-08, TYP-01, ADR-0017.