Document POP_FINALLY and add tests for 'break' and 'return' in 'final…

…ly' clause.

Doc/library/dis.rst

@@ -668,6 +668,22 @@ iterations of the loop.
    popped values are used to restore the exception state.
 
 
+.. opcode:: POP_FINALLY (preserve_tos)
+
+   Cleans up the value stack and the block stack.  If *preserve_tos* is not
+   ``0`` TOS first is popped from the stack and pushed on the stack after
+   perfoming other stack operations:
+
+   * If TOS is ``NULL`` or an integer (pushed by :opcode:`BEGIN_FINALLY`
+     or :opcode:`CALL_FINALLY`) it is popped from the stack.
+   * If TOS is an exception type (pushed when an exception has been raised)
+     6 values are popped from the stack, the last three popped values are
+     used to restore the exception state.  An exception handler block is
+     removed from the block stack.
+
+   .. versionadded:: 3.7
+
+
 .. opcode:: BEGIN_FINALLY
 
    Pushes ``NULL`` onto the stack for using it in :opcode:`END_FINALLY`.
@@ -687,8 +703,10 @@ iterations of the loop.
    * If TOS is an integer (pushed by :opcode:`CALL_FINALLY`), sets the
      bytecode counter to TOS.  TOS is popped.
    * If TOS is an exception type (pushed when an exception has been raised)
-     re-raise the exception and restore ``sys.exc_info()``. 6 values are
-     popped from the stack.
+     6 values are popped from the stack, the first three popped values are
+     used to re-raise the exception and the last three popped values are used
+     to restore the exception state.  An exception handler block is removed
+     from the block stack.
 
 
 .. opcode:: LOAD_BUILD_CLASS
@@ -735,8 +753,12 @@ iterations of the loop.
    * If SECOND is an integer (pushed by :opcode:`CALL_FINALLY`), sets the
      bytecode counter to TOS.  4 values are popped from the stack.
    * If SECOND is an exception type (pushed when an exception has been raised)
-     re-raise the exception and restore ``sys.exc_info()``. 9 values are
-     popped from the stack.
+     and TOS is true SIXTH, SEVENTH and EIGHTH are used for restoring the
+     exception state.  9 values are popped from the stack. An exception
+     handler block is removed from the block stack.
+   * If SECOND is an exception type and TOS is false THIRD, FOURTH and FIFTH
+     are used for re-raising the exception state and SIXTH, SEVENTH and EIGHTH
+     are used for restoring the exception state.  9 values are popped from the stack. An exception handler block is removed from the block stack.
 
    .. versionchanged:: 3.7
       WITH_CLEANUP_FINISH now includes the functionality of

Doc/whatsnew/3.7.rst

@@ -936,9 +936,9 @@ CPython bytecode changes
 
   Removed opcodes :opcode:`BREAK_LOOP`, :opcode:`CONTINUE_LOOP`,
   :opcode:`SETUP_LOOP` and :opcode:`SETUP_EXCEPT`.  Added new opcodes
-  :opcode:`ROT_FOUR`, :opcode:`BEGIN_FINALLY` and :opcode:`CALL_FINALLY`.
-  Changed the behavior of :opcode:`END_FINALLY`.  :opcode:`WITH_CLEANUP_FINISH`
-  now includes :opcode:`END_FINALLY`.
+  :opcode:`ROT_FOUR`, :opcode:`BEGIN_FINALLY`, :opcode:`CALL_FINALLY` and
+  :opcode:`CALL_FINALLY`.  Changed the behavior of :opcode:`END_FINALLY`.
+  :opcode:`WITH_CLEANUP_FINISH` now includes :opcode:`END_FINALLY`.
 
   (Contributed by Mark Shannon, Antoine Pitrou and Serhiy Storchaka in
   :issue:`17611`.)

Lib/test/test_grammar.py

@@ -805,6 +805,80 @@ def g2(): return 1
         x = g2()
         check_syntax_error(self, "class foo:return 1")
 
+    def test_break_in_finally(self):
+        count = 0
+        while count < 2:
+            count += 1
+            try:
+                pass
+            finally:
+                break
+        self.assertEqual(count, 1)
+
+        count = 0
+        while count < 2:
+            count += 1
+            try:
+                continue
+            finally:
+                break
+        self.assertEqual(count, 1)
+
+        count = 0
+        while count < 2:
+            count += 1
+            try:
+                1/0
+            finally:
+                break
+        self.assertEqual(count, 1)
+
+        for count in [0, 1]:
+            self.assertEqual(count, 0)
+            try:
+                pass
+            finally:
+                break
+        self.assertEqual(count, 0)
+
+        for count in [0, 1]:
+            self.assertEqual(count, 0)
+            try:
+                continue
+            finally:
+                break
+        self.assertEqual(count, 0)
+
+        for count in [0, 1]:
+            self.assertEqual(count, 0)
+            try:
+                1/0
+            finally:
+                break
+        self.assertEqual(count, 0)
+
+    def test_return_in_finally(self):
+        def g1():
+            try:
+                pass
+            finally:
+                return 1
+        self.assertEqual(g1(), 1)
+
+        def g2():
+            try:
+                return 2
+            finally:
+                return 3
+        self.assertEqual(g2(), 3)
+
+        def g3():
+            try:
+                1/0
+            finally:
+                return 4
+        self.assertEqual(g3(), 4)
+
     def test_yield(self):
         # Allowed as standalone statement
         def g(): yield 1

Misc/NEWS.d/next/Core and Builtins/2017-12-24-19-48-59.bpo-17611.P85kWL.rst

@@ -1,8 +1,11 @@
 Simplified the interpreter loop by moving the logic of unrolling the stack
 of blocks into the compiler. The compiler emits now explicit instructions
 for adjusting the stack of values and calling the cleaning up code for
-"break", "continue" and "return".
+:keyword:`break`, :keyword:`continue` and :keyword:`return`.
 
-Removed opcodes BREAK_LOOP, CONTINUE_LOOP, SETUP_LOOP and SETUP_EXCEPT.
-Added new opcodes ROT_FOUR, BEGIN_FINALLY and CALL_FINALLY. Changed the
-behavior of END_FINALLY.  WITH_CLEANUP_FINISH now includes END_FINALLY.
+Removed opcodes :opcode:`BREAK_LOOP`, :opcode:`CONTINUE_LOOP`,
+:opcode:`SETUP_LOOP` and :opcode:`SETUP_EXCEPT`. Added new opcodes
+:opcode:`ROT_FOUR`, :opcode:`BEGIN_FINALLY` and :opcode:`CALL_FINALLY` and
+:opcode:`POP_FINALLY`. Changed the behavior of :opcode:`END_FINALLY`.
+:opcode:`WITH_CLEANUP_FINISH` now includes the functionality of
+:opcode:`END_FINALLY`.