Package: exceptiongroup
This is a backport of theBaseExceptionGroupandExceptionGroupclasses from
Python 3.11.It contains the following:Theexceptiongroup.BaseExceptionGroupandexceptiongroup.ExceptionGroupclassesA utility function (exceptiongroup.catch()) for catching exceptions possibly
nested in an exception groupPatches to theTracebackExceptionclass that properly formats exception groups
(installed on import)An exception hook that handles formatting of exception groups throughTracebackException(installed on import)Special versions of some of the functions from thetracebackmodule, modified to
correctly handle exception groups even when monkey patching is disabled, or blocked by
another custom exception hook:traceback.format_exception()traceback.format_exception_only()traceback.print_exception()traceback.print_exc()A backported version ofcontextlib.suppress()from Python 3.12.1 which also
handles suppressing exceptions inside exception groupsIf this package is imported on Python 3.11 or later, the built-in implementations of the
exception group classes are used instead,TracebackExceptionis not monkey patched
and the exception hook won’t be installed.See thestandard library documentationfor more information on exception groups.Catching exceptionsDue to the lack of theexcept*syntax introduced byPEP 654in earlier Python
versions, you need to useexceptiongroup.catch()to catch exceptions that are
potentially nested inside an exception group. This function returns a context manager
that calls the given handler for any exceptions matching the sole argument.The argument tocatch()must be a dict (or anyMapping) where each key is either
an exception class or an iterable of exception classes. Each value must be a callable
that takes a single positional argument. The handler will be called at most once, with
an exception group as an argument which will contain all the exceptions that are any
of the given types, or their subclasses. The exception group may contain nested groups
containing more matching exceptions.Thus, the following Python 3.11+ code:try:...except*(ValueError,KeyError)asexcgroup:forexcinexcgroup.exceptions:print('Caught exception:',type(exc))except*RuntimeError:print('Caught runtime error')would be written with this backport like this:fromexceptiongroupimportExceptionGroup,catchdefvalue_key_err_handler(excgroup:ExceptionGroup)->None:forexcinexcgroup.exceptions:print('Caught exception:',type(exc))defruntime_err_handler(exc:ExceptionGroup)->None:print('Caught runtime error')withcatch({(ValueError,KeyError):value_key_err_handler,RuntimeError:runtime_err_handler}):...NOTE: Just like withexcept*, you cannot handleBaseExceptionGrouporExceptionGroupwithcatch().Suppressing exceptionsThis library contains a backport of thecontextlib.suppress()context manager from
Python 3.12.1. It allows you to selectively ignore certain exceptions, even when they’re
inside exception groups:from exceptiongroup import suppress

with suppress(RuntimeError):
    raise ExceptionGroup("", [RuntimeError("boo")])Notes on monkey patchingTo make exception groups render properly when an unhandled exception group is being
printed out, this package does two things when it is imported on any Python version
earlier than 3.11:Thetraceback.TracebackExceptionclass is monkey patched to store extra
information about exception groups (in__init__()) and properly format them (informat())An exception hook is installed atsys.excepthook, provided that no other hook is
already present. This hook causes the exception to be formatted usingtraceback.TracebackExceptionrather than the built-in rendered.Ifsys.exceptionhookis found to be set to something else than the default whenexceptiongroupis imported, no monkeypatching is done at all.To prevent the exception hook and patches from being installed, set the environment
variableEXCEPTIONGROUP_NO_PATCHto1.Formatting exception groupsNormally, the monkey patching applied by this library on import will cause exception
groups to be printed properly in tracebacks. But in cases when the monkey patching is
blocked by a third party exception hook, or monkey patching is explicitly disabled,
you can still manually format exceptions using the special versions of thetracebackfunctions, likeformat_exception(), listed at the top of this page. They work just
like their counterparts in thetracebackmodule, except that they use a separately
patched subclass ofTracebackExceptionto perform the rendering.Particularly in cases where a library installs its own exception hook, it is recommended
to use these special versions to do the actual formatting of exceptions/tracebacks.