Add `[disallow-non-exhaustive-match]` check · Issue #13597 · python/mypy · GitHub

Feature

Add a new check, [disallow-non-exhaustive-match], that enforces at type check time that no match statements implicitly fall through their bottom.

I would prefer if this check were on-by-default, or at least enabled when strict = true, but if this is controversial to the mypy team, off-by-default would be acceptable.

Pitch

The (superseded) PEP 622 has a great discussion on the motivation for this feature with several examples.

For brevity, below we list a very simple example demonstrating the kinds of correctness checks that motivate this feature request.

Consider we have the following code:

from enum import Enum, auto

class Color(Enum):
    Red = auto()
    Green = auto()

def print_color(color: Color) -> None:
    match color:
        case Color.Red:
            print("red")
        case Color.Green:
            print("green")

Now, consider in the future another Color variant is added:

from enum import Enum, auto

class Color(Enum):
    Red = auto()
    Green = auto()
    Blue = auto()

def print_color(color: Color) -> None:
    match color:
        case Color.Red:
            print("red")
        case Color.Green:
            print("green")

Oops! We forgot to add another case to print_color's match, Color.Blue is not handled, and this bug slips though into runtime.

Even if mypy is configured in strict mode, this bug isn't caught (because Python's default behavior is to allow match fall through).

[tool.mypy]
strict = true

$ mypy main.py
Success: no issues found in 1 source file

So how does a programmer defend against this bug? Currently, the best solution is to sprinkle assert_never clauses into every match.

from enum import Enum, auto

from typing_extensions import assert_never


class Color(Enum):
    Red = auto()
    Green = auto()
    Blue = auto()


def print_color(color: Color) -> None:
    match color:
        case Color.Red:
            print("red")
        case Color.Green:
            print("green")
        case _ as unreachable:
            assert_never(unreachable)

This will catch the error:

$ mypy main.py
main.py:19: error: Argument 1 to "assert_never" has incompatible type "Literal[Color.Blue]"; expected "NoReturn"

This boilerplate requires the programmer to:

If running on Python <3.11, add typing_extensions to their dependencies
For each module they are using match, import assert_never
For each match statement, add the case _ clause

This hurts the ergonomics of trying to pervasively enforce this kind of correctness.

This also requires the programmer not to forget to add this boilerplate to every match clause, which can be error prone, especially for large projects wanting to guarantee correctness.

If using coverage, the boilerplate increases further as there will be no reasonable way to add tests to cover the extra unreachable cases. An extra # pragma: no cover comment must be added to every unreachable case:

def print_color(color: Color) -> None:
    match color:
        case Color.Red:
            print("red")
        case Color.Green:
            print("green")
        case _ as unreachable:  # pragma: no cover
            assert_never(unreachable)

Other Languages

Other languages with pattern matching, such as Rust, enforce exhaustive pattern matching, and it has been observed to have a positive effect on program correctness.

I actually would prefer this to be on by default. The superseding PEP 634 says:

For cases such as sealed classes and enums, where the patterns are all known to be members of a discrete set, static checkers can warn about missing patterns.

In addition, there are already so many flags and I think this is a case where it is reasonable to diverge from runtime.

Note that mypy will already complain about code like the following, so this shouldn't be a hard check to add:

from enum import Enum, auto

class Color(Enum):
    Red = auto()
    Green = auto()
    Blue = auto()

def print_color(color: Color) -> int:
    match color:
        case Color.Red:
            return 4
        case Color.Green:
            return 5

Take a look at #12267 if you're interested in implementing this.

For what it's worth:

pyright chose not to enforce exhaustiveness by default, but has an opt-in strict check for it: Exhaustiveness checks for patten matching microsoft/pyright#2569 (comment)
Guido was also hesitant about enforcing exhaustiveness by default, but mentioned he could see value in having this per-module (and mypy master now supports per-module error codes): Support for python 3.10 match statement #10191 (comment)

I would certainly accept a disabled-by-default error code for this to mypy. I don't have enough experience with the match statement or sense of how it's used in the ecosystem to have an opinion on enabled-by-default or not.

(Btw, a little off topic, but if you have open source code that makes interesting use of typing features, pattern matching, or has surfaced mypy usability issues for you previously, let me know, and I can add it to https://github.com/hauntsaninja/mypy_primer )

I actually would prefer this to be on by default.

@ethanhs I would too. I clarified the initial post to express this. I originally posted off-by-default to try to avoid controversy if the mypy team feels we shouldn't diverge from the runtime behavior. But I agree with everything you said above.

Add a new async iterable select() function

I was also surprised that even in --strict mode mypy does not warn about this issue, my use case was processing a commands set so along the lines of

class A:
    pass

class B:
    pass

Things = Union[A, B]

def foo(v: Things) -> None:
    match v:
        case A():
            # do thing

and the entire point of the union was the assumption that match would perform exhaustiveness checking, and would tell me if I forgot to process new commands. Sadly it's not to be.

Other languages with pattern matching, such as Rust, enforce exhaustive pattern matching

OCaml and Swift as well, Haskell -- or at least ghc -- stands out for not having exhaustive checking by default, and IIRC it's because the type system is sufficiently complex that it's a hard problem in that specific language, as well as the relevant GHC code being pretty old and crufty and not having a real champion / owner.

TypeScript also is equipped to evaluate its [key in <type>] construction exhaustively, I believe by default.

The following shows a Property '[E_Color.Blue]' is missing in type '{ red: string; green: string; }' but required in type '{ red: string; green: string; blue: string; }' error in one of my projects:

export enum E_Color {
  Red = 'red',
  Green = 'green',
  Blue = 'blue',
}

export const colorsUpper: {[key in E_Color]: string} = {  // <-- Error
  [E_Color.Red]: 'RED',
  [E_Color.Green]: 'GREEN',
}

I was pretty shocked to discover that this behavior isn't implemented. This error message is also not great:

class Animal(enum.Enum):
    DOG = "Dog"
    CAT = "Cat"

    def __bool__(self) -> bool:
        match self:
            case Animal.DOG:
                return True

error: Missing return statement  [return]
        def __bool__(self) -> bool:
        ^

OCaml and Swift as well, Haskell -- or at least ghc -- stands out for not having exhaustive checking by default, and IIRC it's because the type system is sufficiently complex that it's a hard problem in that specific language, as well as the relevant GHC code being pretty old and crufty and not having a real champion / owner.

Swift doesn't seem to be on this list. In Swift you'll always need a default: block (identical to case _: in Python) if you're not covering all the cases. What's not enabled by default is the enforcement of @unknown default:, i.e. always requiring a fallback for non-frozen enums in case a new case is added afterwards.

Swift doesn't seem to be on this list. In Swift you'll always need a default: block (identical to case _: in Python) if you're not covering all the cases.

... did you misread my comment? That's what exhaustive matching is, you must cover all cases (whether individually or via a fallback clause -- default: in swift). Which is exactly what's requested of mypy.

OCaml and Swift as well, Haskell -- or at least ghc -- stands out for not having exhaustive checking by default,

😮 OCaml, check by default the exhaustiveness and many other properties in patterns, and Haskell check exhaustiveness with -Wall.

EDIT: Ok @xmo-odoo sorry I misread your comment for OCaml, the first comma (instead of a point) made me think that OCaml, Swift and Haskell where in the same boat.

This is now implemented as the exhaustive-match error, disabled by default. Hopefully we can enable it by default in strict modes but that's for another day.

For copy-pasting purposes: --enable-error-code exhaustive-match

https://mypy.readthedocs.io/en/latest/error_code_list2.html#check-that-match-statements-match-exhaustively-match-exhaustive

Thanks to Don-Burns in #19144

For copy-pasting purposes to pyproject.toml:

[tool.mypy]
enable_error_code = ["exhaustive-match"]

Also, @hauntsaninja, is there a typo in the docs, or is the error code inconsistent with the CLI flag?

https://mypy.readthedocs.io/en/latest/error_code_list2.html#check-that-match-statements-match-exhaustively-match-exhaustive

The title says match-exhaustive but the examples use exhaustive-match.

The title says match-exhaustive but the examples use exhaustive-match.

Yeah, that looks like a typo. Feel free to send a PR!

@brianschubert

Fix exhaustive-match error code in title #19276

Fix `exhaustive-match` error code in title (#19276)

Add `[disallow-non-exhaustive-match]` check · Issue #13597 · python/mypy · GitHub

Repository navigation

Add [disallow-non-exhaustive-match] check #13597

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Add `[disallow-non-exhaustive-match]` check · Issue #13597 · python/mypy · GitHub

Repository navigation

Add [disallow-non-exhaustive-match] check #13597

Description

Activity

emmatyping commented on Sep 4, 2022

hauntsaninja commented on Sep 4, 2022

hauntsaninja commented on Sep 4, 2022

johnthagen commented on Sep 4, 2022

xmo-odoo commented on Oct 16, 2023

bskinn commented on Dec 23, 2023

9999years commented on Mar 26, 2024

stevapple commented on Jun 19, 2024

xmo-odoo commented on Jun 19, 2024

bobot commented on Aug 6, 2024

A5rocks commented on Jun 11, 2025

hauntsaninja commented on Jun 11, 2025

johnthagen commented on Jun 11, 2025

brianschubert commented on Jun 11, 2025

johnthagen commented on Jun 11, 2025

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions