#1795 Implement PEP 765: disallow return/break/continue in finally blocks (#1798)

Summary:
For #1795

  This implements [PEP 765](https://peps.python.org/pep-0765/) which disallows `return`, `break`, and `continue` statements that directly exit a `finally` block. Starting in Python
  3.14, these statements emit a `SyntaxWarning` because they can silently mask exceptions.

  ## The Issue

  When a `return`, `break`, or `continue` statement exits a `finally` block, any exception being propagated is silently discarded:

  ```python
  def f():
      try:
          raise ValueError("important error")
      finally:
          return 42  # Silences the ValueError!

  for x in range(10):
      try:
          raise ValueError()
      finally:
          break  # Silences the ValueError!
```
  However, these statements are valid when inside a nested function or nested loop within the finally block:
```python
  def f():
      try:
          pass
      finally:
          def inner():
              return 42  # OK: exits inner function, not finally

          for x in range(5):
              break  # OK: exits inner loop, not finally
```
  The Fix

  I made several changes to detect these violations during the binding phase:

    - Added InvalidReturnInFinally error kind in crates/pyrefly_config/src/error_kind.rs with Warn severity (matching Python's SyntaxWarning)
    - Added finally_depth tracking in pyrefly/lib/binding/scope.rs:
    - Added finally_depth: usize field to Scope struct
    - This resets to 0 when entering a new function scope, so nested functions are correctly allowed
    - Added enter_finally(), exit_finally(), and in_finally() methods to Scopes
    - Added in_finally flag on loops in pyrefly/lib/binding/scope.rs:
    - Added in_finally: bool field to Loop struct
    - Records whether a loop was started inside a finally block
    - Added loop_protects_from_finally_exit() method to check if break/continue targets a nested loop
    - Added checks for return/break/continue in pyrefly/lib/binding/stmt.rs:
    - Check in record_return() for return statements
    - Check in Stmt::Break and Stmt::Continue handlers
    - All checks are gated to Python 3.14+ via self.sys_info.version().at_least(3, 14)
    - Added documentation in website/docs/error-kinds.mdx for invalid-return-in-finally

Pull Request resolved: #1798

Test Plan:
| Test                                     | Description                    |
  |------------------------------------------|--------------------------------|
  | test_pep765_return_in_finally            | return in finally → warning    |
  | test_pep765_break_in_finally             | break in finally → warning     |
  | test_pep765_continue_in_finally          | continue in finally → warning  |
  | test_pep765_return_in_nested_function_ok | return in nested function → OK |
  | test_pep765_break_in_nested_loop_ok      | break in nested loop → OK      |
  | test_pep765_continue_in_nested_loop_ok   | continue in nested loop → OK   |
  | test_pep765_return_python313_no_error    | no warning on Python 3.13      |

  Verification:

  Run PEP 765 tests
  cargo test test_pep765
  Result: 7 passed

  Run all flow_branching tests
  cargo test flow_branching
  Result: 86 passed

  Run all tests
  cargo test
  Result: 3057 passed

  Fixes #1795

Reviewed By: grievejia

Differential Revision: D88746329

Pulled By: yangdanny97

fbshipit-source-id: f4690916e33e5fda99db83b5a61fae963e6c8328

Author: jackulau

pyrefly/lib/binding/scope.rs

@@ -886,13 +886,16 @@ pub enum LoopExit {
 struct Loop {
     base: Flow,
     exits: Vec<(LoopExit, Flow)>,
+    /// For PEP 765: The depth of finally-blocks that this loop was created in
+    finally_depth: usize,
 }
 
 impl Loop {
-    pub fn new(base: Flow) -> Self {
+    pub fn new(base: Flow, finally_depth: usize) -> Self {
         Self {
             base,
             exits: Default::default(),
+            finally_depth,
         }
     }
 }
@@ -956,6 +959,8 @@ pub struct Scope {
     imports: SmallMap<Name, ImportUsage>,
     /// Tracking variables in the current scope (module, function, and method scopes)
     variables: SmallMap<Name, VariableUsage>,
+    /// Depth of finally blocks we're in. Resets in new function scopes (PEP 765).
+    finally_depth: usize,
 }
 
 impl Scope {
@@ -970,6 +975,7 @@ impl Scope {
             forks: Default::default(),
             imports: SmallMap::new(),
             variables: SmallMap::new(),
+            finally_depth: 0,
         }
     }
 
@@ -1139,6 +1145,34 @@ impl Scopes {
             .any(|scope| matches!(scope.kind, ScopeKind::Function(_) | ScopeKind::Method(_)))
     }
 
+    /// Enter a finally block (PEP 765).
+    pub fn enter_finally(&mut self) {
+        self.current_mut().finally_depth += 1;
+    }
+
+    /// Exit a finally block (PEP 765).
+    pub fn exit_finally(&mut self) {
+        self.current_mut().finally_depth -= 1;
+    }
+
+    /// Check if we're in a finally block at the current scope level.
+    /// This resets when entering a new function scope, so nested functions are OK.
+    pub fn in_finally(&self) -> bool {
+        self.current().finally_depth > 0
+    }
+
+    pub fn finally_depth(&self) -> usize {
+        self.current().finally_depth
+    }
+
+    /// Check if we're inside a loop that was started inside the inner-most finally block
+    pub fn loop_protects_from_finally_exit(&self) -> bool {
+        self.current()
+            .loops
+            .last()
+            .is_some_and(|l| l.finally_depth == self.current().finally_depth)
+    }
+
     /// Are we currently in a class body. If so, return the keys for the class and its metadata.
     pub fn current_class_and_metadata_keys(
         &self,
@@ -2630,12 +2664,16 @@ impl<'a> BindingsBuilder<'a> {
     /// Names in `loop_header_targets` will not get phi keys - this is used for loop
     /// variables that are unconditionally reassigned in `for` loop headers
     pub fn setup_loop(&mut self, range: TextRange, loop_header_targets: &SmallSet<Name>) {
+        let finally_depth = self.scopes.finally_depth();
         let base = mem::take(&mut self.scopes.current_mut().flow);
         // To account for possible assignments to existing names in a loop, we
         // speculatively insert phi keys upfront.
         self.scopes.current_mut().flow =
             self.insert_phi_keys(base.clone(), range, loop_header_targets);
-        self.scopes.current_mut().loops.push(Loop::new(base));
+        self.scopes
+            .current_mut()
+            .loops
+            .push(Loop::new(base, finally_depth));
     }
 
     pub fn teardown_loop(

pyrefly/lib/binding/stmt.rs

@@ -272,6 +272,14 @@ impl<'a> BindingsBuilder<'a> {
     /// If this is the top level, report a type error about the invalid return
     /// and also create a binding to ensure we type check the expression.
     fn record_return(&mut self, mut x: StmtReturn) {
+        // PEP 765: Disallow return in finally block (Python 3.14+)
+        if self.sys_info.version().at_least(3, 14) && self.scopes.in_finally() {
+            self.error(
+                x.range(),
+                ErrorInfo::Kind(ErrorKind::InvalidSyntax),
+                "`return` in a `finally` block will silence exceptions".to_owned(),
+            );
+        }
         let mut ret = self.declare_current_idx(Key::ReturnExplicit(x.range()));
         self.ensure_expr_opt(x.value.as_deref_mut(), ret.usage());
         if let Err((ret, oops_top_level)) = self.scopes.record_or_reject_return(ret, x) {
@@ -864,7 +872,9 @@ impl<'a> BindingsBuilder<'a> {
                 }
 
                 self.finish_exhaustive_fork();
+                self.scopes.enter_finally();
                 self.stmts(x.finalbody, parent);
+                self.scopes.exit_finally();
             }
             Stmt::Assert(x) => {
                 self.assert(x.range(), *x.test, x.msg.map(|m| *m));
@@ -984,10 +994,32 @@ impl<'a> BindingsBuilder<'a> {
                 }
             }
             Stmt::Pass(_) => { /* no-op */ }
-            Stmt::Break(_) => {
+            Stmt::Break(x) => {
+                // PEP 765: Disallow break in finally block if not inside a nested loop
+                if self.sys_info.version().at_least(3, 14)
+                    && self.scopes.in_finally()
+                    && !self.scopes.loop_protects_from_finally_exit()
+                {
+                    self.error(
+                        x.range,
+                        ErrorInfo::Kind(ErrorKind::InvalidSyntax),
+                        "`break` in a `finally` block will silence exceptions".to_owned(),
+                    );
+                }
                 self.add_loop_exitpoint(LoopExit::Break);
             }
-            Stmt::Continue(_) => {
+            Stmt::Continue(x) => {
+                // PEP 765: Disallow continue in finally block if not inside a nested loop
+                if self.sys_info.version().at_least(3, 14)
+                    && self.scopes.in_finally()
+                    && !self.scopes.loop_protects_from_finally_exit()
+                {
+                    self.error(
+                        x.range,
+                        ErrorInfo::Kind(ErrorKind::InvalidSyntax),
+                        "`continue` in a `finally` block will silence exceptions".to_owned(),
+                    );
+                }
                 self.add_loop_exitpoint(LoopExit::Continue);
             }
             Stmt::IpyEscapeCommand(x) => {

pyrefly/lib/test/flow_branching.rs

@@ -5,6 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+use pyrefly_python::sys_info::PythonVersion;
+
 use crate::test::util::TestEnv;
 use crate::testcase;
 
@@ -1321,3 +1323,82 @@ def test_keyword_pattern_not_special(x: float) -> None:
             assert_type(r, float)
 "#,
 );
+
+testcase!(
+    test_pep765_break_continue_return_in_finally_3_14,
+    TestEnv::new_with_version(PythonVersion {
+        major: 3,
+        minor: 14,
+        micro: 0,
+    }),
+    r#"
+def test():
+    try:
+        pass
+    finally:
+        return # E: in a `finally` block
+
+for _ in []:
+    try:
+        pass
+    finally:
+        break # E: in a `finally` block
+for _ in []:
+    try:
+        pass
+    finally:
+        continue # E: in a `finally` block
+
+try:
+    pass
+finally:
+    def f():
+        return 42 # OK
+
+try:
+    pass
+finally:
+    def f():
+        try:
+            pass
+        finally:
+            return 42 # E: in a `finally` block
+
+try:
+    pass
+finally:
+    for _ in []:
+        try:
+            pass
+        finally:
+            break # E: in a `finally` block
+    "#,
+);
+
+testcase!(
+    test_pep765_break_continue_return_in_finally_3_13,
+    TestEnv::new_with_version(PythonVersion {
+        major: 3,
+        minor: 13,
+        micro: 0,
+    }),
+    r#"
+# For now, we won't emit a PEP765 syntax error for 3.13 and below
+def test():
+    try:
+        pass
+    finally:
+        return
+
+for _ in []:
+    try:
+        pass
+    finally:
+        break
+for _ in []:
+    try:
+        pass
+    finally:
+        continue
+    "#,
+);