add docs

Author: iritkatriel

Doc/reference/compound_stmts.rst

@@ -420,7 +420,7 @@ is executed.  If there is a saved exception it is re-raised at the end of the
 :keyword:`!finally` clause.  If the :keyword:`!finally` clause raises another
 exception, the saved exception is set as the context of the new exception.
 If the :keyword:`!finally` clause executes a :keyword:`return`, :keyword:`break`
-or :keyword:`continue` statement, the saved exception is discarded::
+or :keyword:`continue` statement, the saved exception is discarded.
 
    >>> def f():
    ...     try:
@@ -461,6 +461,11 @@ always be the last one executed::
    Prior to Python 3.8, a :keyword:`continue` statement was illegal in the
    :keyword:`!finally` clause due to a problem with the implementation.
 
+.. versionchanged:: 3.14
+   The compiler emits a :exc:`SyntaxWarning` when a :keyword:`return`,
+   :keyword:`break` or :keyword:`continue` appears in a :keyword:`!finally`
+   block (see :pep:`765`).
+
 
 .. _with:
 .. _as:

Doc/tutorial/errors.rst

@@ -417,7 +417,9 @@ points discuss more complex cases when an exception occurs:
 
 * If the :keyword:`!finally` clause executes a :keyword:`break`,
   :keyword:`continue` or :keyword:`return` statement, exceptions are not
-  re-raised.
+  re-raised. This can be confusing and is therefore discouraged. From
+  version 3.14 the compiler emits a :exc:`SyntaxWarning` for it
+  (see :pep:`765`).
 
 * If the :keyword:`!try` statement reaches a :keyword:`break`,
   :keyword:`continue` or :keyword:`return` statement, the
@@ -429,7 +431,9 @@ points discuss more complex cases when an exception occurs:
   statement, the returned value will be the one from the
   :keyword:`!finally` clause's :keyword:`!return` statement, not the
   value from the :keyword:`!try` clause's :keyword:`!return`
-  statement.
+  statement. This can be confusing and is therefore discouraged. From
+  version 3.14 the compiler emits a :exc:`SyntaxWarning` for it
+  (see :pep:`765`).
 
 For example::
 

Doc/whatsnew/3.14.rst

@@ -68,6 +68,7 @@ Summary -- release highlights
 * :ref:`PEP 741: Python Configuration C API <whatsnew314-pep741>`
 * :ref:`PEP 761: Discontinuation of PGP signatures <whatsnew314-pep761>`
 * :ref:`A new type of interpreter  <whatsnew314-tail-call>`
+* :ref:`PEP 765: Disallow return/break/continue that exit a finally block <whatsnew314-pep765>`
 
 
 New features
@@ -305,6 +306,15 @@ Other language changes
   The testbed can also be used to run the test suite of projects other than
   CPython itself. (Contributed by Russell Keith-Magee in :gh:`127592`.)
 
+.. _whatsnew314-pep765:
+
+PEP 765: Disallow return/break/continue that exit a finally block
+-----------------------------------------------------------------
+
+The compiler emits a ``SyntaxWarning`` when a ``return``, ``break`` or
+``continue`` statements appears where it exits a ``finally`` block.
+This change in is specified in :pep:`765`.
+
 New modules
 ===========
 

Misc/NEWS.d/next/Core_and_Builtins/2025-02-13-19-07-54.gh-issue-130080.IoJpuy.rst

@@ -0,0 +1 @@
+Implement PEP 765: Disallow return/break/continue that exit a finally block.