add checker for return/yield in finally

Author: hofrob

doc/data/messages/r/return-or-yield-in-finally/bad/return.py

@@ -0,0 +1,7 @@
+def second_favorite():
+    fruits = ["kiwi", "pineapple"]
+    try:
+        return fruits[1]
+    finally:
+        # because of this `return` statement, this function will always return "kiwi"
+        return fruits[0]  # [return-or-yield-in-finally]

doc/data/messages/r/return-or-yield-in-finally/bad/yield.py

@@ -0,0 +1,11 @@
+def all_favorites():
+    fruits = ["orange", "kiwi", "pineapple"]
+
+    for fruit in fruits:
+        try:
+            yield fruit
+        finally:
+            # this `yield` statement will add `None` after every fruit
+            # list(all_favorites()) will result in:
+            # ["orange", None, "kiwi", None, "pineapple", None]
+            yield  # [return-or-yield-in-finally]

doc/data/messages/r/return-or-yield-in-finally/good/return.py

@@ -0,0 +1,8 @@
+def second_favorite():
+    fruits = ["apple"]
+    try:
+        return fruits[1]
+    except KeyError:
+        ...
+
+    return fruits[0]

doc/data/messages/r/return-or-yield-in-finally/good/yield.py

@@ -0,0 +1,8 @@
+def all_favorites():
+    fruits = ["orange", "kiwi", "pineapple"]
+
+    for fruit in fruits:
+        try:
+            yield fruit
+        finally:
+            ...

doc/data/messages/r/return-or-yield-in-finally/related.rst

@@ -0,0 +1 @@
+- `Python 3 docs 'finally' clause <https://docs.python.org/3/reference/compound_stmts.html#finally-clause>`_

doc/whatsnew/fragments/8260.new_check

@@ -0,0 +1,4 @@
+Add ``return-or-yield-in-finally`` to emit a message if a yield or return statement
+was found in a finally clause.
+
+Closes #8260

pylint/checkers/base/basic_checker.py

@@ -266,6 +266,12 @@ class BasicChecker(_BasicChecker):
             "Used when an exception is created without being assigned, raised or returned "
             "for subsequent use elsewhere.",
         ),
+        "W0134": (
+            "'%s' shadowed by the 'finally' clause.",
+            "return-or-yield-in-finally",
+            "Emitted when a 'return' or 'yield' statement is found in a 'finally' block. "
+            "This will overwrite the return value of a function and should be avoided.",
+        ),
     }
 
     reports = (("RP0101", "Statistics by type", report_by_type_stats),)
@@ -765,6 +771,16 @@ def visit_tryfinally(self, node: nodes.TryFinally) -> None:
         assert self._tryfinallys is not None
         self._tryfinallys.append(node)
 
+        for final_node in node.finalbody:
+            for return_node in final_node.nodes_of_class(nodes.Return):
+                self.add_message(
+                    "return-or-yield-in-finally", node=return_node, args=("return",)
+                )
+            for yield_node in final_node.nodes_of_class(nodes.Yield):
+                self.add_message(
+                    "return-or-yield-in-finally", node=yield_node, args=("yield",)
+                )
+
     def leave_tryfinally(self, _: nodes.TryFinally) -> None:
         """Update try...finally flag."""
         assert self._tryfinallys is not None

tests/functional/l/lost_exception.py

@@ -1,4 +1,4 @@
-# pylint: disable=missing-docstring, using-constant-test,cell-var-from-loop
+# pylint: disable=missing-docstring, using-constant-test,cell-var-from-loop,return-or-yield-in-finally
 
 def insidious_break_and_return():
     for i in range(0, -5, -1):

tests/functional/r/return_or_yield_in_finally.py

@@ -0,0 +1,41 @@
+# pylint: disable=missing-docstring,too-few-public-methods,useless-return,lost-exception
+
+def second_favorite():
+    fruits = ["apple"]
+    try:
+        return fruits[1]
+    finally:
+        return fruits[0]  # [return-or-yield-in-finally]
+
+
+def all_favorites():
+    fruits = ["orange", "kiwi", "pineapple"]
+
+    for fruit in fruits:
+        try:
+            yield fruit
+        finally:
+            yield  # [return-or-yield-in-finally]
+
+
+def more_favorites():
+    fruits = ["orange", "kiwi", "pineapple"]
+
+    for fruit in fruits:
+        try:
+            yield fruit
+        finally:
+            if len(fruit) > 7:
+                yield "too many fruits"  # [return-or-yield-in-finally]
+
+
+def even_more_favorites():
+    fruits = ["orange", "kiwi", "pineapple"]
+
+    for fruit in fruits:
+        try:
+            yield fruit
+        finally:
+            if len(fruit) > 7:
+                for fruit_name in fruits:
+                    yield f"please remove {fruit_name}"  # [return-or-yield-in-finally]

tests/functional/r/return_or_yield_in_finally.txt

@@ -0,0 +1,4 @@
+return-or-yield-in-finally:8:8:8:24:second_favorite:'return' shadowed by the 'finally' clause.:UNDEFINED
+return-or-yield-in-finally:18:12:18:17:all_favorites:'yield' shadowed by the 'finally' clause.:UNDEFINED
+return-or-yield-in-finally:29:16:29:39:more_favorites:'yield' shadowed by the 'finally' clause.:UNDEFINED
+return-or-yield-in-finally:41:20:41:55:even_more_favorites:'yield' shadowed by the 'finally' clause.:UNDEFINED

tests/functional/u/used/used_before_assignment_488.py

@@ -1,4 +1,4 @@
-# pylint: disable=missing-docstring
+# pylint: disable=missing-docstring,return-or-yield-in-finally
 def func():
     """Test that a variable defined in a finally clause does not trigger a false positive"""
     try: