ExceptionGroup and BaseExceptionGroup

We propose to add two new builtin exception types: BaseExceptionGroup(BaseException) and ExceptionGroup(BaseExceptionGroup, Exception). They are assignable to Exception.__cause__ and Exception.__context__, and they can be raised and handled as any exception with raise ExceptionGroup(...) and try: ... except ExceptionGroup: ... or raise BaseExceptionGroup(...) and try: ... except BaseExceptionGroup: ....

Both have a constructor that takes two positional-only arguments: a message string and a sequence of the nested exceptions, which are exposed in the fields message and exceptions. For example: ExceptionGroup('issues', [ValueError('bad value'), TypeError('bad type')]). The difference between them is that ExceptionGroup can only wrap Exception subclasses while BaseExceptionGroup can wrap any BaseException subclass. The BaseExceptionGroup constructor inspects the nested exceptions and if they are all Exception subclasses, it returns an ExceptionGroup rather than a BaseExceptionGroup. The ExceptionGroup constructor raises a TypeError if any of the nested exceptions is not an Exception instance. In the rest of the document, when we refer to an exception group, we mean either an ExceptionGroup or a BaseExceptionGroup. When it is necessary to make the distinction, we use the class name. For brevity, we will use ExceptionGroup in code examples that are relevant to both.

Since an exception group can be nested, it represents a tree of exceptions, where the leaves are plain exceptions and each internal node represents a time at which the program grouped some unrelated exceptions into a new group and raised them together.

The BaseExceptionGroup.subgroup(condition) method gives us a way to obtain an exception group that has the same metadata (message, cause, context, traceback) as the original group, and the same nested structure of groups, but contains only those exceptions for which the condition is true:

>>> eg = ExceptionGroup(
...     "one",
...     [
...         TypeError(1),
...         ExceptionGroup(
...             "two",
...              [TypeError(2), ValueError(3)]
...         ),
...         ExceptionGroup(
...              "three",
...               [OSError(4)]
...         )
...     ]
... )
>>> import traceback
>>> traceback.print_exception(eg)
  | ExceptionGroup: one (3 sub-exceptions)
  +-+---------------- 1 ----------------
    | TypeError: 1
    +---------------- 2 ----------------
    | ExceptionGroup: two (2 sub-exceptions)
    +-+---------------- 1 ----------------
      | TypeError: 2
      +---------------- 2 ----------------
      | ValueError: 3
      +------------------------------------
    +---------------- 3 ----------------
    | ExceptionGroup: three (1 sub-exception)
    +-+---------------- 1 ----------------
      | OSError: 4
      +------------------------------------

>>> type_errors = eg.subgroup(lambda e: isinstance(e, TypeError))
>>> traceback.print_exception(type_errors)
  | ExceptionGroup: one (2 sub-exceptions)
  +-+---------------- 1 ----------------
    | TypeError: 1
    +---------------- 2 ----------------
    | ExceptionGroup: two (1 sub-exception)
    +-+---------------- 1 ----------------
      | TypeError: 2
      +------------------------------------
>>>

The match condition is also applied to interior nodes (the exception groups), and a match causes the whole subtree rooted at this node to be included in the result.

Empty nested groups are omitted from the result, as in the case of ExceptionGroup("three") in the example above. If none of the exceptions match the condition, subgroup returns None rather than an empty group. The original eg is unchanged by subgroup, but the value returned is not necessarily a full new copy. Leaf exceptions are not copied, nor are exception groups which are fully contained in the result. When it is necessary to partition a group because the condition holds for some, but not all of its contained exceptions, a new ExceptionGroup or BaseExceptionGroup instance is created, while the __cause__, __context__ and __traceback__ fields are copied by reference, so they are shared with the original eg.

If both the subgroup and its complement are needed, the BaseExceptionGroup.split(condition) method can be used:

>>> type_errors, other_errors = eg.split(lambda e: isinstance(e, TypeError))
>>> traceback.print_exception(type_errors)
  | ExceptionGroup: one (2 sub-exceptions)
  +-+---------------- 1 ----------------
    | TypeError: 1
    +---------------- 2 ----------------
    | ExceptionGroup: two (1 sub-exception)
    +-+---------------- 1 ----------------
      | TypeError: 2
      +------------------------------------
>>> traceback.print_exception(other_errors)
  | ExceptionGroup: one (2 sub-exceptions)
  +-+---------------- 1 ----------------
    | ExceptionGroup: two (1 sub-exception)
    +-+---------------- 1 ----------------
      | ValueError: 3
      +------------------------------------
    +---------------- 2 ----------------
    | ExceptionGroup: three (1 sub-exception)
    +-+---------------- 1 ----------------
      | OSError: 4
      +------------------------------------
>>>

If a split is trivial (one side is empty), then None is returned for the other side:

>>> other_errors.split(lambda e: isinstance(e, SyntaxError))
(None, ExceptionGroup('one', [
  ExceptionGroup('two', [
    ValueError(3)
  ]),
  ExceptionGroup('three', [
    OSError(4)])]))

Since splitting by exception type is a very common use case, subgroup and split can take an exception type or tuple of exception types and treat it as a shorthand for matching that type: eg.split(T) divides eg into the subgroup of leaf exceptions that match the type T, and the subgroup of those that do not (using the same check as except for a match).

class MyExceptionGroup(ExceptionGroup):
    def __new__(cls, message, excs, errcode):
        obj = super().__new__(cls, message, excs)
        obj.errcode = errcode
        return obj

    def derive(self, excs):
        return MyExceptionGroup(self.message, excs, self.errcode)

>>> eg = MyExceptionGroup("eg", [TypeError(1), ValueError(2)], 42)
>>>
>>> match, rest = eg.split(ValueError)
>>> print(f'match: {match!r}: {match.errcode}')
match: MyExceptionGroup('eg', [ValueError(2)], 42): 42
>>> print(f'rest: {rest!r}: {rest.errcode}')
rest: MyExceptionGroup('eg', [TypeError(1)], 42): 42
>>>

>>> class MyExceptionGroup(BaseExceptionGroup):
...     pass
...
>>> eg = MyExceptionGroup("eg", [ValueError(1), KeyboardInterrupt(2)])
>>> match, rest = eg.split(ValueError)
>>> print(f'match: {match!r}')
match: ExceptionGroup('eg', [ValueError(1)])
>>> print(f'rest: {rest!r}')
rest: BaseExceptionGroup('eg', [KeyboardInterrupt(2)])
>>>

>>> def f(v):
...     try:
...         raise ValueError(v)
...     except ValueError as e:
...         return e
...
>>> try:
...     raise ExceptionGroup("one", [f(1)])
... except ExceptionGroup as e:
...     eg = e
...
>>> raise ExceptionGroup("two", [f(2), eg])
 + Exception Group Traceback (most recent call last):
 |   File "<stdin>", line 1, in <module>
 | ExceptionGroup: two (2 sub-exceptions)
 +-+---------------- 1 ----------------
   | Traceback (most recent call last):
   |   File "<stdin>", line 3, in f
   | ValueError: 2
   +---------------- 2 ----------------
   | Exception Group Traceback (most recent call last):
   |   File "<stdin>", line 2, in <module>
   | ExceptionGroup: one (1 sub-exception)
   +-+---------------- 1 ----------------
     | Traceback (most recent call last):
     |   File "<stdin>", line 3, in f
     | ValueError: 1
     +------------------------------------
>>>

def log_and_ignore_ENOENT(err):
    if isinstance(err, OSError) and err.errno == ENOENT:
        log(err)
        return False
    else:
        return True

try:
    . . .
except ExceptionGroup as eg:
    eg = eg.subgroup(log_and_ignore_ENOENT)
    if eg is not None:
        raise eg

def leaf_generator(exc, tbs=None):
    if tbs is None:
        tbs = []

    tbs.append(exc.__traceback__)
    if isinstance(exc, BaseExceptionGroup):
        for e in exc.exceptions:
            yield from leaf_generator(e, tbs)
    else:
        # exc is a leaf exception and its traceback
        # is the concatenation of the traceback
        # segments in tbs.

        # Note: the list returned (tbs) is reused in each iteration
        # through the generator. Make a copy if your use case holds
        # on to it beyond the current iteration or mutates its contents.

        yield exc, tbs
    tbs.pop()

>>> import traceback
>>>
>>> def g(v):
...     try:
...         raise ValueError(v)
...     except Exception as e:
...         return e
...
>>> def f():
...     raise ExceptionGroup("eg", [g(1), g(2)])
...
>>> try:
...     f()
... except BaseException as e:
...     eg = e
...
>>> for (i, (exc, tbs)) in enumerate(leaf_generator(eg)):
...     print(f"\n=== Exception #{i+1}:")
...     traceback.print_exception(exc)
...     print(f"The complete traceback for Exception #{i+1}:")
...     for tb in tbs:
...         traceback.print_tb(tb)
...

=== Exception #1:
Traceback (most recent call last):
  File "<stdin>", line 3, in g
ValueError: 1
The complete traceback for Exception #1
  File "<stdin>", line 2, in <module>
  File "<stdin>", line 2, in f
  File "<stdin>", line 3, in g

=== Exception #2:
Traceback (most recent call last):
  File "<stdin>", line 3, in g
ValueError: 2
The complete traceback for Exception #2:
  File "<stdin>", line 2, in <module>
  File "<stdin>", line 2, in f
  File "<stdin>", line 3, in g
>>>

except*

We are proposing to introduce a new variant of the try..except syntax to simplify working with exception groups. The * symbol indicates that multiple exceptions can be handled by each except* clause:

try:
    ...
except* SpamError:
    ...
except* FooError as e:
    ...
except* (BarError, BazError) as e:
    ...

In a traditional try-except statement there is only one exception to handle, so the body of at most one except clause executes; the first one that matches the exception. With the new syntax, an except* clause can match a subgroup of the exception group that was raised, while the remaining part is matched by following except* clauses. In other words, a single exception group can cause several except* clauses to execute, but each such clause executes at most once (for all matching exceptions from the group) and each exception is either handled by exactly one clause (the first one that matches its type) or is reraised at the end. The manner in which each exception is handled by a try-except* block is independent of any other exceptions in the group.

For example, suppose that the body of the try block above raises eg = ExceptionGroup('msg', [FooError(1), FooError(2), BazError()]). The except* clauses are evaluated in order by calling split on the unhandled exception group, which is initially equal to eg and then shrinks as exceptions are matched and extracted from it. In the first except* clause, unhandled.split(SpamError) returns (None, unhandled) so the body of this block is not executed and unhandled is unchanged. For the second block, unhandled.split(FooError) returns a non-trivial split (match, rest) with match = ExceptionGroup('msg', [FooError(1), FooError(2)]) and rest = ExceptionGroup('msg', [BazError()]). The body of this except* block is executed, with the value of e and sys.exc_info() set to match. Then, unhandled is set to rest. Finally, the third block matches the remaining exception so it is executed with e and sys.exc_info() set to ExceptionGroup('msg', [BazError()]).

Exceptions are matched using a subclass check. For example:

try:
    low_level_os_operation()
except* OSError as eg:
    for e in eg.exceptions:
        print(type(e).__name__)

could output:

BlockingIOError
ConnectionRefusedError
OSError
InterruptedError
BlockingIOError

The order of except* clauses is significant just like with the regular try..except:

>>> try:
...     raise ExceptionGroup("problem", [BlockingIOError()])
... except* OSError as e:   # Would catch the error
...     print(repr(e))
... except* BlockingIOError: # Would never run
...     print('never')
...
ExceptionGroup('problem', [BlockingIOError()])

>>> try:
...     raise ExceptionGroup(
...         "eg",
...         [
...             ValueError('a'),
...             TypeError('b'),
...             ExceptionGroup(
...                 "nested",
...                 [TypeError('c'), KeyError('d')])
...         ]
...     )
... except* TypeError as e1:
...     print(f'e1 = {e1!r}')
... except* Exception as e2:
...     print(f'e2 = {e2!r}')
...
e1 = ExceptionGroup('eg', [TypeError('b'), ExceptionGroup('nested', [TypeError('c')])])
e2 = ExceptionGroup('eg', [ValueError('a'), ExceptionGroup('nested', [KeyError('d')])])
>>>

>>> try:
...     try:
...         raise ExceptionGroup(
...             "msg", [
...                  ValueError('a'), TypeError('b'),
...                  TypeError('c'), KeyError('e')
...             ]
...         )
...     except* ValueError as e:
...         print(f'got some ValueErrors: {e!r}')
...     except* TypeError as e:
...         print(f'got some TypeErrors: {e!r}')
... except ExceptionGroup as e:
...     print(f'propagated: {e!r}')
...
got some ValueErrors: ExceptionGroup('msg', [ValueError('a')])
got some TypeErrors: ExceptionGroup('msg', [TypeError('b'), TypeError('c')])
propagated: ExceptionGroup('msg', [KeyError('e')])
>>>

>>> try:
...     raise BlockingIOError
... except* OSError as e:
...     print(repr(e))
...
ExceptionGroup('', [BlockingIOError()])

>>> try:
...     try:
...         raise ValueError(12)
...     except* TypeError as e:
...         print('never')
... except ValueError as e:
...     print(f'caught ValueError: {e!r}')
...
caught ValueError: ValueError(12)
>>>

def foo():                           | def foo():
    try:                             |     try:
        1 / 0                        |         1 / 0
    except ZeroDivisionError as e:   |     except ZeroDivisionError:
        raise e                      |         raise
                                     |
foo()                                | foo()
                                     |
Traceback (most recent call last):   | Traceback (most recent call last):
  File "/Users/guido/a.py", line 7   |   File "/Users/guido/b.py", line 7
   foo()                             |     foo()
  File "/Users/guido/a.py", line 5   |   File "/Users/guido/b.py", line 3
   raise e                           |     1/0
  File "/Users/guido/a.py", line 3   | ZeroDivisionError: division by zero
   1/0                               |
ZeroDivisionError: division by zero  |

>>> try:
...     try:
...         raise ExceptionGroup(
...             "eg",
...             [
...                 ValueError(1),
...                 TypeError(2),
...                 OSError(3),
...                 ExceptionGroup(
...                     "nested",
...                     [OSError(4), TypeError(5), ValueError(6)])
...             ]
...         )
...     except* ValueError as e:
...         print(f'*ValueError: {e!r}')
...         raise
...     except* OSError as e:
...         print(f'*OSError: {e!r}')
... except ExceptionGroup as e:
...     print(repr(e))
...
*ValueError: ExceptionGroup('eg', [ValueError(1), ExceptionGroup('nested', [ValueError(6)])])
*OSError: ExceptionGroup('eg', [OSError(3), ExceptionGroup('nested', [OSError(4)])])
ExceptionGroup('eg', [ValueError(1), TypeError(2), ExceptionGroup('nested', [TypeError(5), ValueError(6)])])
>>>

>>> try:
...     raise ExceptionGroup(
...         "eg",
...         [
...             ValueError(1),
...             TypeError(2),
...             OSError(3),
...             ExceptionGroup(
...                 "nested",
...                 [OSError(4), TypeError(5), ValueError(6)])
...         ]
...     )
... except* ValueError as e:
...     print(f'*ValueError: {e!r}')
...     raise e
... except* OSError as e:
...     print(f'*OSError: {e!r}')
...     raise
...
*ValueError: ExceptionGroup('eg', [ValueError(1), ExceptionGroup('nested', [ValueError(6)])])
*OSError: ExceptionGroup('eg', [OSError(3), ExceptionGroup('nested', [OSError(4)])])
  | ExceptionGroup:  (2 sub-exceptions)
  +-+---------------- 1 ----------------
    | Exception Group Traceback (most recent call last):
    |   File "<stdin>", line 15, in <module>
    |   File "<stdin>", line 2, in <module>
    | ExceptionGroup: eg (2 sub-exceptions)
    +-+---------------- 1 ----------------
      | ValueError: 1
      +---------------- 2 ----------------
      | ExceptionGroup: nested (1 sub-exception)
      +-+---------------- 1 ----------------
        | ValueError: 6
        +------------------------------------
    +---------------- 2 ----------------
    | Exception Group Traceback (most recent call last):
    |   File "<stdin>", line 2, in <module>
    | ExceptionGroup: eg (3 sub-exceptions)
    +-+---------------- 1 ----------------
      | TypeError: 2
      +---------------- 2 ----------------
      | OSError: 3
      +---------------- 3 ----------------
      | ExceptionGroup: nested (2 sub-exceptions)
      +-+---------------- 1 ----------------
        | OSError: 4
        +---------------- 2 ----------------
        | TypeError: 5
        +------------------------------------
>>>

>>> try:
...     raise ExceptionGroup("one", [ValueError('a'), TypeError('b')])
... except* ValueError:
...     raise ExceptionGroup("two", [KeyError('x'), KeyError('y')])
...
  | ExceptionGroup:  (2 sub-exceptions)
  +-+---------------- 1 ----------------
    | Exception Group Traceback (most recent call last):
    |   File "<stdin>", line 2, in <module>
    | ExceptionGroup: one (1 sub-exception)
    +-+---------------- 1 ----------------
      | ValueError: a
      +------------------------------------
    |
    | During handling of the above exception, another exception occurred:
    |
    | Exception Group Traceback (most recent call last):
    |   File "<stdin>", line 4, in <module>
    | ExceptionGroup: two (2 sub-exceptions)
    +-+---------------- 1 ----------------
      | KeyError: 'x'
      +---------------- 2 ----------------
      | KeyError: 'y'
      +------------------------------------
    +---------------- 2 ----------------
    | Exception Group Traceback (most recent call last):
    |   File "<stdin>", line 2, in <module>
    | ExceptionGroup: one (1 sub-exception)
    +-+---------------- 1 ----------------
      | TypeError: b
      +------------------------------------
>>>

>>> try:
...     raise TypeError('bad type')
... except* TypeError as e:
...     raise ValueError('bad value') from e
...
  | ExceptionGroup:  (1 sub-exception)
  +-+---------------- 1 ----------------
    | Traceback (most recent call last):
    |   File "<stdin>", line 2, in <module>
    | TypeError: bad type
    +------------------------------------

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "<stdin>", line 4, in <module>
ValueError: bad value
>>>

>>> try:
...     raise TypeError(1)
... except* TypeError:
...     raise ValueError(2) from None  # <- not caught in the next clause
... except* ValueError:
...     print('never')
...
Traceback (most recent call last):
  File "<stdin>", line 4, in <module>
ValueError: 2
>>>

>>> try:
...     raise ExceptionGroup("eg", [ValueError('a')])
... except* ValueError:
...     raise KeyError('x')
...
  | ExceptionGroup:  (1 sub-exception)
  +-+---------------- 1 ----------------
    | Exception Group Traceback (most recent call last):
    |   File "<stdin>", line 2, in <module>
    | ExceptionGroup: eg (1 sub-exception)
    +-+---------------- 1 ----------------
      | ValueError: a
      +------------------------------------
    |
    | During handling of the above exception, another exception occurred:
    |
    | Traceback (most recent call last):
    |   File "<stdin>", line 4, in <module>
    | KeyError: 'x'
    +------------------------------------
>>>
>>> try:
...     raise ExceptionGroup("eg", [ValueError('a'), TypeError('b')])
... except* ValueError:
...     raise KeyError('x')
...
  | ExceptionGroup:  (2 sub-exceptions)
  +-+---------------- 1 ----------------
    | Exception Group Traceback (most recent call last):
    |   File "<stdin>", line 2, in <module>
    | ExceptionGroup: eg (1 sub-exception)
    +-+---------------- 1 ----------------
      | ValueError: a
      +------------------------------------
    |
    | During handling of the above exception, another exception occurred:
    |
    | Traceback (most recent call last):
    |   File "<stdin>", line 4, in <module>
    | KeyError: 'x'
    +---------------- 2 ----------------
    | Exception Group Traceback (most recent call last):
    |   File "<stdin>", line 2, in <module>
    | ExceptionGroup: eg (1 sub-exception)
    +-+---------------- 1 ----------------
      | TypeError: b
      +------------------------------------
>>>

try:
    low_level_os_operation()
except* OSError as errors:
    exc = errors.subgroup(lambda e: e.errno != errno.EPIPE)
    if exc is not None:
        raise exc from None

>>> eg = ExceptionGroup("eg", [TypeError(12)])
>>> eg.foo = 'foo'
>>> try:
...     raise eg
... except* TypeError as e:
...     e.foo = 'bar'
... #   ^----------- ``e`` is an ephemeral object that might get
>>> #                      destroyed after the ``except*`` clause.
>>> eg.foo
'foo'

try:
    ...
except ValueError:
    pass
except* CancelledError:  # <- SyntaxError:
    pass                 #    combining ``except`` and ``except*``
                         #    is prohibited

try:
    ...
except ExceptionGroup:  # <- This works
    pass

try:
    ...
except* ExceptionGroup:  # <- Runtime error
    pass

try:
    ...
except* (TypeError, ExceptionGroup):  # <- Runtime error
    pass

try:
    ...
except*:   # <- SyntaxError
    pass

Make Exception Groups Iterable

We considered making exception groups iterable, so that list(eg) would produce a flattened list of the leaf exceptions contained in the group. We decided that this would not be a sound API, because the metadata (cause, context and traceback) of the individual exceptions in a group is incomplete and this could create problems.

Furthermore, as we explained in the Handling Exception Groups section, we find it unlikely that iteration over leaf exceptions will have many use cases. We did, however, provide there the code for a traversal algorithm that correctly constructs each leaf exceptions’ metadata. If it does turn out to be useful in practice, we can in the future add that utility to the standard library or even make exception groups iterable.

Make ExceptionGroup Extend BaseException

We considered making ExceptionGroup subclass only BaseException, and not Exception. The rationale of this was that we expect exception groups to be used in a deliberate manner where they are needed, and raised only by APIs that are specifically designed and documented to do so. In this context, an ExceptionGroup escaping from an API that is not intended to raise one is a bug, and we wanted to give it “fatal error” status so that except Exception will not inadvertently swallow it. This would have been consistent with the way except T: does not catch exception groups that contain T for all other types, and would help contain ExceptionGroups to the parts of the program in which they are supposed to appear. However, it was clear from the public discussion that T=Exception is a special case, and there are developers who feel strongly that except Exception: should catch “almost everything”, including exception groups. This is why we decided to make ExceptionGroup a subclass of Exception.

Make it Impossible to Wrap BaseExceptions in an Exception Group

A consequence of the decision to make ExceptionGroup extend Exception is that ExceptionGroup should not wrap BaseExceptions like KeyboardInterrupt, as they are not currently caught by except Exception:. We considered the option of simply making it impossible to wrap BaseExceptions, but eventually decided to make it possible through the BaseExceptionGroup type, which extends BaseException rather than Exception. Making this possible adds flexibility to the language and leaves it for the programmer to weigh the benefit of wrapping BaseExceptions rather than propagating them in their naked form while discarding any other exceptions.

Traceback Representation

We considered options for adapting the traceback data structure to represent trees, but it became apparent that a traceback tree is not meaningful once separated from the exceptions it refers to. While a simple-path traceback can be attached to any exception by a with_traceback() call, it is hard to imagine a case where it makes sense to assign a traceback tree to an exception group. Furthermore, a useful display of the traceback includes information about the nested exceptions. For these reasons we decided that it is best to leave the traceback mechanism as it is and modify the traceback display code.

Extend except to Handle Exception Groups

We considered extending the semantics of except to handle exception groups, instead of introducing except*. There were two backwards compatibility concerns with this. The first is the type of the caught exception. Consider this example:

try:
    . . .
except OSError as err:
    if err.errno != ENOENT:
        raise

If the value assigned to err is an exception group containing all of the OSErrors that were raised, then the attribute access err.errno no longer works. So we would need to execute the body of the except clause multiple times, once for each exception in the group. However, this too is a potentially breaking change because at the moment we write except clauses with the knowledge that they are only executed once. If there is a non-idempotent operation there, such as releasing a resource, the repetition could be harmful.

The idea of making except iterate over the leaf exceptions of an exception group is at the heart of an alternative proposal to this PEP by Nathaniel J. Smith, and the discussion about that proposal further elaborates on the pitfalls of changing except semantics in a mature language like Python, as well as deviating from the semantics that parallel constructs have in other languages.

Another option that came up in the public discussion was to add except*, but also make except treat ExceptionGroups as a special case. except would then do something along the lines of extracting one exception of matching type from the group in order to handle it (while discarding all the other exceptions in the group). The motivation behind these suggestions was to make the adoption of exception groups safer, in that except T catches Ts that are wrapped in exception groups. We decided that such an approach adds considerable complexity to the semantics of the language without making it more powerful. Even if it would make the adoption of exception groups slightly easier (which is not at all obvious), these are not the semantics we would like to have in the long term.

A New except Alternative

We considered introducing a new keyword (such as catch) which can be used to handle both naked exceptions and exception groups. Its semantics would be the same as those of except* when catching an exception group, but it would not wrap a naked exception to create an exception group. This would have been part of a long term plan to replace except by catch, but we decided that deprecating except in favour of an enhanced keyword would be too confusing for users at this time, so it is more appropriate to introduce the except* syntax for exception groups while except continues to be used for simple exceptions.

Applying an except* Clause on One Exception at a Time

We explained above that it is unsafe to execute an except clause in existing code more than once, because the code may not be idempotent. We considered doing this in the new except* clauses, where the backwards compatibility considerations do not exist. The idea is to always execute an except* clause on a single exception, possibly executing the same clause multiple times when it matches multiple exceptions. We decided instead to execute each except* clause at most once, giving it an exception group that contains all matching exceptions. The reason for this decision was the observation that when a program needs to know the particular context of an exception it is handling, the exception is handled before it is grouped and raised together with other exceptions.

For example, KeyError is an exception that typically relates to a certain operation. Any recovery code would be local to the place where the error occurred, and would use the traditional except:

try:
    dct[key]
except KeyError:
    # handle the exception

It is unlikely that asyncio users would want to do something like this:

try:
    async with asyncio.TaskGroup() as g:
        g.create_task(task1); g.create_task(task2)
except* KeyError:
    # handling KeyError here is meaningless, there's
    # no context to do anything with it but to log it.

When a program handles a collection of exceptions that were aggregated into an exception group, it would not typically attempt to recover from any particular failed operation, but will rather use the types of the errors to determine how they should impact the program’s control flow or what logging or cleanup is required. This decision is likely to be the same whether the group contains a single or multiple instances of something like a KeyboardInterrupt or asyncio.CancelledError. Therefore, it is more convenient to handle all exceptions matching an except* at once. If it does turn out to be necessary, the handler can inpect the exception group and process the individual exceptions in it.

Not Matching Naked Exceptions in except*

We considered the option of making except* T match only exception groups that contain Ts, but not naked Ts. To see why we thought this would not be a desirable feature, return to the distinction in the previous paragraph between operation errors and control flow exceptions. If we don’t know whether we should expect naked exceptions or exception groups from the body of a try block, then we’re not in the position of handling operation errors. Rather, we are likely calling a fairly generic function and will be handling errors to make control flow decisions. We are likely to do the same thing whether we catch a naked exception of type T or an exception group with one or more Ts. Therefore, the burden of having to explicitly handle both is not likely to have semantic benefit.

If it does turn out to be necessary to make the distinction, it is always possible to nest in the try-except* clause an additional try-except clause which intercepts and handles a naked exception before the except* clause has a chance to wrap it in an exception group. In this case the overhead of specifying both is not additional burden - we really do need to write a separate code block to handle each case:

try:
    try:
        ...
    except SomeError:
        # handle the naked exception
except* SomeError:
    # handle the exception group

Allow mixing except: and except*: in the same try

This option was rejected because it adds complexity without adding useful semantics. Presumably the intention would be that an except T: block handles only naked exceptions of type T, while except* T: handles T in exception groups. We already discussed above why this is unlikely to be useful in practice, and if it is needed then the nested try-except block can be used instead to achieve the same result.

try* instead of except*

Since either all or none of the clauses of a try construct are except*, we considered changing the syntax of the try instead of all the except* clauses. We rejected this because it would be less obvious. The fact that we are handling exception groups of T rather than only naked Ts should be specified in the same place where we state T.

Alternative syntax options

Alternatives to the except* syntax were evaluated in a discussion on python-dev, and it was suggested to use except group. Upon careful evaluation this was rejected because the following would be ambiguous, as it is currently valid syntax where group is interpreted as a callable. The same is true for any valid identifier.

try:
   ...
except group (T1, T2):
   ...