Add new checker and bare-name-capture-pattern message (#10424)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Jacob Walls <[email protected]>
Co-authored-by: Pierre Sassoulas <[email protected]>
Co-authored-by: Marc Mueller <[email protected]>

Author: 5 people

.pre-commit-config.yaml

@@ -28,6 +28,8 @@ repos:
       - id: ruff-check
         name: ruff-doc
         files: doc/data/messages
+        # Please exclude using doc/data/ruff.toml
+        # exclude: ""  # Leave empty
   - repo: https://github.com/Pierre-Sassoulas/copyright_notice_precommit
     rev: 0.1.2
     hooks:

doc/data/messages/b/bare-name-capture-pattern/bad.py

@@ -0,0 +1,13 @@
+red = 0
+green = 1
+blue = 2
+
+
+def func(color):
+    match color:
+        case red:  # [bare-name-capture-pattern]
+            print("I see red!")
+        case green:  # [bare-name-capture-pattern]
+            print("Grass is green")
+        case blue:
+            print("I'm feeling the blues :(")

doc/data/messages/b/bare-name-capture-pattern/good.py

@@ -0,0 +1,17 @@
+from enum import Enum
+
+
+class Color(Enum):
+    RED = 0
+    GREEN = 1
+    BLUE = 2
+
+
+def func(color: Color) -> None:
+    match color:
+        case Color.RED:
+            print("I see red!")
+        case Color.GREEN:
+            print("Grass is green")
+        case Color.BLUE:
+            print("I'm feeling the blues :(")

doc/data/messages/b/bare-name-capture-pattern/related.rst

@@ -0,0 +1 @@
+- `PEP 636 <https://peps.python.org/pep-0636/#matching-against-constants-and-enums>`_

doc/data/ruff.toml

@@ -6,8 +6,9 @@ extend-exclude = [
     "messages/d/duplicate-argument-name/bad.py",
     "messages/s/syntax-error/bad.py",
     # syntax error in newer python versions
+    "messages/b/bare-name-capture-pattern/bad.py",
     "messages/s/star-needs-assignment-target/bad.py",
-    "messages/i/invalid-star-assignment-target/bad.py"
+    "messages/i/invalid-star-assignment-target/bad.py",
 ]
 
 [lint]

doc/user_guide/checkers/features.rst

@@ -676,6 +676,18 @@ Logging checker Messages
   format-interpolation is disabled then you can use str.format.
 
 
+Match Statements checker
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Verbatim name of the checker is ``match_statements``.
+
+Match Statements checker Messages
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+:bare-name-capture-pattern (E1901): *The name capture `case %s` makes the remaining patterns unreachable. Use a dotted name (for example an enum) to fix this.*
+  Emitted when a name capture pattern is used in a match statement and there
+  are case statements below it.
+
+
 Method Args checker
 ~~~~~~~~~~~~~~~~~~~
 

doc/user_guide/messages/messages_overview.rst

@@ -63,6 +63,7 @@ All messages in the error category:
    error/bad-str-strip-call
    error/bad-string-format-type
    error/bad-super-call
+   error/bare-name-capture-pattern
    error/bidirectional-unicode
    error/broken-collections-callable
    error/broken-noreturn

doc/whatsnew/fragments/7128.new_check

@@ -0,0 +1,6 @@
+Add ``match-statements`` checker and the following message:
+``bare-name-capture-pattern``.
+This will emit an error message when a name capture pattern is used in a match statement which would make the remaining patterns unreachable.
+This code is a SyntaxError at runtime.
+
+Closes #7128

pylint/checkers/match_statements_checker.py

@@ -0,0 +1,52 @@
+# Licensed under the GPL: https://www.gnu.org/licenses/old-licenses/gpl-2.0.html
+# For details: https://github.com/pylint-dev/pylint/blob/main/LICENSE
+# Copyright (c) https://github.com/pylint-dev/pylint/blob/main/CONTRIBUTORS.txt
+
+"""Match statement checker for Python code."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from astroid import nodes
+
+from pylint.checkers import BaseChecker
+from pylint.checkers.utils import only_required_for_messages
+from pylint.interfaces import HIGH
+
+if TYPE_CHECKING:
+    from pylint.lint import PyLinter
+
+
+class MatchStatementChecker(BaseChecker):
+    name = "match_statements"
+    msgs = {
+        "E1901": (
+            "The name capture `case %s` makes the remaining patterns unreachable. "
+            "Use a dotted name (for example an enum) to fix this.",
+            "bare-name-capture-pattern",
+            "Emitted when a name capture pattern is used in a match statement "
+            "and there are case statements below it.",
+        )
+    }
+
+    @only_required_for_messages("bare-name-capture-pattern")
+    def visit_match(self, node: nodes.Match) -> None:
+        """Check if a name capture pattern prevents the other cases from being
+        reached.
+        """
+        for idx, case in enumerate(node.cases):
+            match case.pattern:
+                case nodes.MatchAs(pattern=None, name=nodes.AssignName()) if (
+                    idx < len(node.cases) - 1
+                ):
+                    self.add_message(
+                        "bare-name-capture-pattern",
+                        node=case.pattern,
+                        args=case.pattern.name.name,
+                        confidence=HIGH,
+                    )
+
+
+def register(linter: PyLinter) -> None:
+    linter.register_checker(MatchStatementChecker(linter))

tests/functional/b/bare_name_capture_pattern.py

@@ -0,0 +1,17 @@
+"""Functional tests for the ``bare-name-capture-pattern`` message"""
+
+
+a = "a"
+b = "b"
+s = "a"
+
+
+match s:
+    case a:  # [bare-name-capture-pattern]
+        pass
+    case b:  # [bare-name-capture-pattern]
+        pass
+    case "a" as some_name:
+        pass
+    case s:
+        pass