Add flag to raise error if match statement does not match exaustively

docs/source/command_line.rst

@@ -799,6 +799,7 @@ of the above sections.
         x = 'a string'
         x.trim()  # error: "str" has no attribute "trim"  [attr-defined]
 
+
 .. _configuring-error-messages:
 
 Configuring error messages

docs/source/error_code_list2.rst

@@ -612,3 +612,51 @@ Example:
     # mypy: disallow-any-explicit
     from typing import Any
     x: Any = 1  # Error: Explicit "Any" type annotation  [explicit-any]
+
+
+.. _code-exhaustive-match:
+
+Check that match statements match exhaustively [match-exhaustive]
+-----------------------------------------------------------------------
+
+If enabled with :option:`--enable-error-code exhaustive-match <mypy --enable-error-code>`,
+mypy generates an error if a match statement does not match all possible cases/types.
+
+
+Example:
+
+.. code-block:: python
+
+        import enum
+
+
+        class Color(enum.Enum):
+            RED = 1
+            BLUE = 2
+
+        val: Color = Color.RED
+
+        # without --enable-error-code exhaustive-match
+        match val:
+            case Color.RED:
+                print("red")
+
+        # Also no issues without --enable-error-code exhaustive-match, but this is exhaustive
+        match val:
+            case Color.RED:
+                print("red")
+            case _:
+                print("other")
+
+        # with --enable-error-code exhaustive-match
+        # error: Cases within match statement do not exhaustively handle all values: "Literal[Color.BLUE]". If not intended to handle all cases, use `case _: pass`
+        match val:
+            case Color.RED:
+                print("red")
+
+        # no error with --enable-error-code exhaustive-match since all cases are handled
+        match val:
+            case Color.RED:
+                print("red")
+            case _:
+                print("other")

docs/source/literal_types.rst

@@ -468,6 +468,10 @@ If we forget to handle one of the cases, mypy will generate an error:
       assert_never(direction)  # E: Argument 1 to "assert_never" has incompatible type "Direction"; expected "NoReturn"
 
 Exhaustiveness checking is also supported for match statements (Python 3.10 and later).
+For match statements specifically, inexhaustive matches can be caught
+without needing to use ``assert_never`` by using
+:option:`--enable-error-code exhaustive-match <mypy --enable-error-code>`.
+
 
 Extra Enum checks
 *****************

mypy/checker.py

@@ -5452,6 +5452,7 @@ def visit_match_stmt(self, s: MatchStmt) -> None:
             inferred_types = self.infer_variable_types_from_type_maps(type_maps)
 
             # The second pass narrows down the types and type checks bodies.
+            unmatched_types: TypeMap = None
             for p, g, b in zip(s.patterns, s.guards, s.bodies):
                 current_subject_type = self.expr_checker.narrow_type_from_binder(
                     named_subject, subject_type
@@ -5508,6 +5509,11 @@ def visit_match_stmt(self, s: MatchStmt) -> None:
                     else:
                         self.accept(b)
                 self.push_type_map(else_map, from_assignment=False)
+                unmatched_types = else_map
+
+            if unmatched_types is not None:
+                for typ in set(unmatched_types.values()):
+                    self.msg.match_statement_inexhaustive_match(typ, s)
 
             # This is needed due to a quirk in frame_context. Without it types will stay narrowed
             # after the match.

mypy/errorcodes.py

@@ -264,6 +264,12 @@ def __hash__(self) -> int:
     "General",
     default_enabled=False,
 )
+EXHAUSTIVE_MATCH: Final = ErrorCode(
+    "exhaustive-match",
+    "Reject match statements that are not exhaustive",
+    "General",
+    default_enabled=False,
+)
 
 # Syntax errors are often blocking.
 SYNTAX: Final[ErrorCode] = ErrorCode("syntax", "Report syntax errors", "General")

mypy/messages.py

@@ -2486,6 +2486,14 @@ def type_parameters_should_be_declared(self, undeclared: list[str], context: Con
             code=codes.VALID_TYPE,
         )
 
+    def match_statement_inexhaustive_match(self, typ: Type, context: Context) -> None:
+        type_str = format_type(typ, self.options)
+        msg = (
+            f"Cases within match statement do not exhaustively handle all values: {type_str}."
+            " If not intended to handle all cases, use `case _: pass`"
+        )
+        self.fail(msg, context, code=codes.EXHAUSTIVE_MATCH)
+
 
 def quote_type_string(type_string: str) -> str:
     """Quotes a type representation for use in messages."""

test-data/unit/check-python310.test

@@ -2638,3 +2638,142 @@ def f2() -> None:
                 return
     reveal_type(y) # N: Revealed type is "builtins.str"
 [builtins fixtures/list.pyi]
+
+[case testExhaustiveMatchNoFlag]
+
+a: int = 5
+match a:
+    case 1:
+        pass
+    case _:
+        pass
+
+b: str = "hello"
+match b:
+    case "bye":
+        pass
+    case _:
+        pass
+
+[case testNonExhaustiveMatchNoFlag]
+
+a: int = 5
+match a:
+    case 1:
+        pass
+
+b: str = "hello"
+match b:
+    case "bye":
+        pass
+
+
+[case testExhaustiveMatchWithFlag]
+# flags: --enable-error-code exhaustive-match
+
+a: int = 5
+match a:
+    case 1:
+        pass
+    case _:
+        pass
+
+b: str = "hello"
+match b:
+    case "bye":
+        pass
+    case _:
+        pass
+
+[case testNonExhaustiveMatchWithFlag]
+# flags: --enable-error-code exhaustive-match
+
+a: int = 5
+match a: # E: Cases within match statement do not exhaustively handle all values: "int". If not intended to handle all cases, use `case _: pass`
+    case 1:
+        pass
+
+b: str = "hello"
+match b: # E: Cases within match statement do not exhaustively handle all values: "str". If not intended to handle all cases, use `case _: pass`
+    case "bye":
+        pass
+
+[case testNonExhaustiveMatchEnumWithFlag]
+# flags: --enable-error-code exhaustive-match
+
+import enum
+
+class Color(enum.Enum):
+    RED = 1
+    BLUE = 2
+    GREEN = 3
+
+val: Color = Color.RED
+
+match val: # E: Cases within match statement do not exhaustively handle all values: "Literal[Color.GREEN]". If not intended to handle all cases, use `case _: pass`
+    case Color.RED:
+        a = "red"
+    case Color.BLUE:
+        a= "blue"
+
+[builtins fixtures/enum.pyi]
+
+
+[case testExhaustiveMatchEnumWithFlag]
+# flags: --enable-error-code exhaustive-match
+
+import enum
+
+class Color(enum.Enum):
+    RED = 1
+    BLUE = 2
+
+val: Color = Color.RED
+
+match val:
+    case Color.RED:
+        a = "red"
+    case Color.BLUE:
+        a= "blue"
+
+[builtins fixtures/enum.pyi]
+
+[case testNonExhaustiveMatchEnumMultipleMissingMatchesWithFlag]
+# flags: --enable-error-code exhaustive-match
+
+import enum
+
+class Color(enum.Enum):
+    RED = 1
+    BLUE = 2
+    GREEN = 3
+
+val: Color = Color.RED
+
+match val: # E: Cases within match statement do not exhaustively handle all values: "Literal[Color.BLUE, Color.GREEN]". If not intended to handle all cases, use `case _: pass`
+    case Color.RED:
+        a = "red"
+
+
+[builtins fixtures/enum.pyi]
+
+[case testExhaustiveMatchEnumFallbackWithFlag]
+# flags: --enable-error-code exhaustive-match
+
+import enum
+
+class Color(enum.Enum):
+    RED = 1
+    BLUE = 2
+    GREEN = 3
+
+val: Color = Color.RED
+
+match val:
+    case Color.RED:
+        a = "red"
+    case _:
+        a = "other"
+
+
+[builtins fixtures/enum.pyi]