Exhaustiveness checks for patten matching

[hcarty]

Is your feature request related to a problem? Please describe.

I would like to be able to be able to enable an error when a match does not cover all cases.

Describe the solution you'd like

I would like an option to generate an error when a match statement is not exhaustive. For example, this match statement would error with such an option enabled because the int case is not handled.

IntOrStr = int | str

def handle(x : IntOrStr) -> None:
    match x:
        case str(s):
            print(f"Handled {s}")

[erictraut]

Structural pattern matching has many use cases that don't involve exhaustive checks, so I don't think it makes sense to assume that every use of a match statement will cover all cases.

The same is true for if/elif/else chains. In that case, the recommended approach when you want to validate exhaustive checks is to use an assert_never function like this:

from typing import NoReturn

def assert_never(x: NoReturn) -> NoReturn:
    assert False, "Unhandled type: {}".format(type(x).__name__)

IntOrStr = int | str

def handle(x: IntOrStr) -> None:
    if isinstance(x, str):
        print(f"Handled {x}")
    else:
        assert_never(x)  # Error: "int" is incompatible with "NoReturn"

This works because NoReturn is effectively the same as an empty union (or a Never type). By convention, it is treated by Python type checkers as being compatible with only itself. If you attempt to pass any other type to it, the type checker will emit an error.

If you want a static type checker enforce exhaustiveness within a match statement, I recommend using the same approach:

def handle_not_exhaustive(x : IntOrStr) -> None:
    match x:
        case str(s):
            print(f"Handled {s}")

        case _:
            assert_never(x)  # Error: "int" is incompatible with "NoReturn"

def handle_exhaustive(x: IntOrStr) -> None:
    match x:
        case str(s):
            print(f"Handled {s}")

        case int(s):
            print(f"Handled {s}")

        case _:
            assert_never(x)  # No error

[hcarty]

If you want a static type checker enforce exhaustiveness within a match statement, I recommend using the same approach

That's fair. The issue I have with that approach is that it requires users to remember to add a catch-all case to every match. Stylistically I'd prefer to maintain code where non-exhaustive matches are made explicit and exhaustiveness is expected by default. That way, for example, I can't forget to update a match when the matched value evolves to include new cases.

[erictraut]

Yeah, as I said, there are many legitimate uses for match statements that don't involve exhaustiveness, so there needs to be some way for a developer to say "I want to enforce exhaustiveness in this case". This seems like a straightforward way to do so.

[hcarty]

Where is match useful in place of if in that case? If there is no way to have implicit exhaustiveness checks for match statements then I'm curious to know where they help versus using if with the same pattern.

[erictraut]

Match statements provide a different (more concise) syntax that some developers prefer over if/elif/else statements. You can generally use them interchangeably and for the same purposes.

[hcarty]

Thanks - and thank you generally for your prompt responses to issues and feature requests on here. It's very appreciated!

[rouge8]

PEP 622 seems to suggest that type checkers should enforce exhaustiveness checks with pattern matching: https://www.python.org/dev/peps/pep-0622/#exhaustiveness-checks. Are there no plans for pyright to support this beyond the assert_never() pattern?

[erictraut]

Pyright does provide the type narrowing support required for enforcing exhaustiveness checks, but you need to specify whether exhaustiveness is what you intend. There are many legitimate uses of match that do not involve exhaustive pattern matching, so it wouldn't be appropriate to assume that exhaustive matching is intended in every case.

There are a few ways to specify that exhaustive matching is intended. The first example in PEP 622 that you linked to is already covered by the return type check in pyright.

In other cases (such as in the second example), you can use the assert_never() pattern.

[TomasPuverle]

I made a counter-argument in the same thread: python/mypy#12010 (comment)

(Btw, I love PyRight - thank you! ❤️ )

[erictraut]

There seems to be sufficient interest in enforcing exhaustive matching, so I've added a new diagnostic check ("reportMatchNotExhaustive") that emits a diagnostic in cases where exhaustion cannot be proven through static analysis. The check is off by default with "basic" type checking mode but on by default with "strict" typing checking.

This will be included in the next release of pyright.

[hcarty]

Thank you @erictraut!

[TomasPuverle]

Thank you!

[erictraut]

This is included in pyright 1.1.215, which I just published. It will also be included in the next release of pylance.

[TomasPuverle]

Hi @erictraut , I wanted to follow up and thank you for implementing this. I use the 3.10 match statements on a daily basis and the exhaustiveness support has been a real pleasure to work with.

[dogweather]

reportMatchNotExhaustive is incredible, thank you!

[Hubro]

Is it possible to enable this check for individual match statements?

If not, would it be useful to add? Something like:

# pyright: exhaustive-match
match foo:
    ...

For those that don't want to enable this check globally, this seems much nicer than using assert_never(foo), since you have to define that function yourself and import it when needed.

[johnthagen]

For those that don't want to enable this check globally, this seems much nicer than using assert_never(foo), since you have to define that function yourself and import it when needed.

FYI, assert_never() is included in Python 3.11 and also in recent typing-extension package releases. So in those cases you can avoid having to define it yourself.

from typing_extensions import assert_never

[dogweather]

I wrote up my positive experience with this check and made a repo with some demo cases to play with:

• https://dogweather.dev/2022/10/03/i-discovered-that-python-now-can-do-true-match-exhaustiveness-checking/
• https://github.com/dogweather/python-exhaustiveness-checking