[Python-checkins] (no subject)

[Stéphane Wirtel]

To: python-checkins at python.org
Subject: Improve clarity of try-return-finally-return (GH-15677) (GH-15981)
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: quoted-printable
MIME-Version: 1.0

https://github.com/python/cpython/commit/c0acc0e53e6724c8162f797b94934d53c643=
23d6
commit: c0acc0e53e6724c8162f797b94934d53c64323d6
branch: 3.8
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.co=
m>
committer: St=C3=A9phane Wirtel <stephane at wirtel.be>
date: 2019-09-11T19:42:21+02:00
summary:

Improve clarity of try-return-finally-return (GH-15677) (GH-15981)

Clarify execution in try-return-finally-return case.
(cherry picked from commit 0cc27417f2cd399c432d7dda9aeca1d81af76936)

Co-authored-by: toonarmycaptain <toonarmycaptain at hotmail.com>

files:
M Doc/tutorial/errors.rst
M Misc/ACKS

diff --git a/Doc/tutorial/errors.rst b/Doc/tutorial/errors.rst
index 4e287bbd8d29..0ddf0cc0042d 100644
--- a/Doc/tutorial/errors.rst
+++ b/Doc/tutorial/errors.rst
@@ -341,15 +341,28 @@ example::
      File "<stdin>", line 2, in <module>
    KeyboardInterrupt
=20
-A *finally clause* is always executed before leaving the :keyword:`try`
-statement, whether an exception has occurred or not. When an exception has
-occurred in the :keyword:`!try` clause and has not been handled by an
-:keyword:`except` clause (or it has occurred in an :keyword:`!except` or
-:keyword:`!else` clause), it is re-raised after the :keyword:`finally` claus=
e has
-been executed.  The :keyword:`!finally` clause is also executed "on the way =
out"
-when any other clause of the :keyword:`!try` statement is left via a
-:keyword:`break`, :keyword:`continue` or :keyword:`return` statement.  A more
-complicated example::
+If a :keyword:`finally` clause is present, the :keyword:`finally` clause wil=
l execute as the last task before the :keyword:`try` statement completes. The=
 :keyword:`finally` clause runs whether or not the :keyword:`try` statement p=
roduces an exception. The following points discuss more complex cases when an=
 exception occurs:
+
+* If an exception occurs during execution of the :keyword:`!try` clause, the=
 exception may be handled by an :keyword:`except` clause. In all cases, the e=
xception is re-raised after the :keyword:`!finally` clause has been executed.
+
+* An exception could occur during execution of an :keyword:`!except` or :key=
word:`!else` clause. Again, the exception is re-raised after the :keyword:`!f=
inally` clause has been executed.
+
+* If the :keyword:`!try` statement reaches a :keyword:`break`, :keyword:`con=
tinue` or :keyword:`return` statement, the :keyword:`finally` clause will exe=
cute just prior to the :keyword:`break`, :keyword:`continue` or :keyword:`ret=
urn` statement's execution.
+
+* If a :keyword:`finally` clause includes a :keyword:`return` statement, the=
 :keyword:`finally` clause's :keyword:`return` statement will execute before,=
 and instead of, the :keyword:`return` statement in a :keyword:`try` clause.
+
+For example::
+
+   >>> def bool_return(): -> bool:
+   ...     try:
+   ...         return True
+   ...     finally:
+   ...         return False
+   ...
+   >>> bool_return()
+   False
+
+A more complicated example::
=20
    >>> def divide(x, y):
    ...     try:
diff --git a/Misc/ACKS b/Misc/ACKS
index adc15c94cd31..406009c4e201 100644
--- a/Misc/ACKS
+++ b/Misc/ACKS
@@ -58,6 +58,7 @@ Jon Anglin
 Michele Angrisano
 Ankur Ankan
 Heidi Annexstad
+David Antonini
 Ramchandra Apte
 =C3=89ric Araujo
 Alexandru Ardelean