bpo-45292: [PEP-654] add except* (GH-29581)

3 files changed, 59 insertions, 0 deletions

diff --git a/Doc/library/ast.rst b/Doc/library/ast.rst
index e29b5e8..6486ed4 100644
--- a/Doc/library/ast.rst
+++ b/Doc/library/ast.rst
@@ -1167,6 +1167,37 @@ Control flow
             type_ignores=[])
 
 
+.. class:: TryStar(body, handlers, orelse, finalbody)
+
+   ``try`` blocks which are followed by ``except*`` clauses. The attributes are the
+   same as for :class:`Try` but the :class:`ExceptHandler` nodes in ``handlers``
+   are interpreted as ``except*`` blocks rather then ``except``.
+
+   .. doctest::
+
+        >>> print(ast.dump(ast.parse("""
+        ... try:
+        ...    ...
+        ... except* Exception:
+        ...    ...
+        ... """), indent=4))
+        Module(
+            body=[
+                TryStar(
+                    body=[
+                        Expr(
+                            value=Constant(value=Ellipsis))],
+                    handlers=[
+                        ExceptHandler(
+                            type=Name(id='Exception', ctx=Load()),
+                            body=[
+                                Expr(
+                                    value=Constant(value=Ellipsis))])],
+                    orelse=[],
+                    finalbody=[])],
+            type_ignores=[])
+
+
 .. class:: ExceptHandler(type, name, body)
 
    A single ``except`` clause. ``type`` is the exception type it will match,
diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst
index 9665e8d..7ac5a9b 100644
--- a/Doc/library/dis.rst
+++ b/Doc/library/dis.rst
@@ -872,8 +872,10 @@ All of the following opcodes use their arguments.
 
    .. versionadded:: 3.1
 
+
 .. opcode:: JUMP_IF_NOT_EXC_MATCH (target)
 
+   Performs exception matching for ``except``.
    Tests whether the second value on the stack is an exception matching TOS,
    and jumps if it is not. Pops one value from the stack.
 
@@ -883,6 +885,30 @@ All of the following opcodes use their arguments.
       This opcode no longer pops the active exception.
 
 
+.. opcode:: JUMP_IF_NOT_EG_MATCH (target)
+
+   Performs exception matching for ``except*``. Applies ``split(TOS)`` on
+   the exception group representing TOS1. Jumps if no match is found.
+
+   Pops one item from the stack. If a match was found, pops the 3 items representing
+   the exception and pushes the 3 items representing the non-matching part of
+   the exception group, followed by the 3 items representing the matching part.
+   In other words, in case of a match it pops 4 items and pushes 6.
+
+   .. versionadded:: 3.11
+
+
+.. opcode:: PREP_RERAISE_STAR
+
+   Combines the raised and reraised exceptions list from TOS, into an exception
+   group to propagate from a try-except* block. Uses the original exception
+   group from TOS1 to reconstruct the structure of reraised exceptions. Pops
+   two items from the stack and pushes a triplet representing the exception to
+   reraise or three ``None`` if there isn't one.
+
+   .. versionadded:: 3.11
+
+
 .. opcode:: JUMP_IF_TRUE_OR_POP (target)
 
    If TOS is true, sets the bytecode counter to *target* and leaves TOS on the
diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst
index 8d1f4eb..793075c 100644
--- a/Doc/whatsnew/3.11.rst
+++ b/Doc/whatsnew/3.11.rst
@@ -65,6 +65,8 @@ Summary -- Release highlights
 
 .. PEP-sized items next.
 
+PEP-654: Exception Groups and ``except*``.
+(Contributed by Irit Katriel in :issue:`45292`.)
 
 New Features
 ============