| 1 |
Metadata-Version: 2.1 |
| 2 |
Name: exceptiongroup |
| 3 |
Version: 1.2.1 |
| 4 |
Summary: Backport of PEP 654 (exception groups) |
| 5 |
Author-email: Alex Grönholm <[email protected]> |
| 6 |
Requires-Python: >=3.7 |
| 7 |
Description-Content-Type: text/x-rst |
| 8 |
Classifier: Development Status :: 5 - Production/Stable |
| 9 |
Classifier: Intended Audience :: Developers |
| 10 |
Classifier: License :: OSI Approved :: MIT License |
| 11 |
Classifier: Programming Language :: Python |
| 12 |
Classifier: Programming Language :: Python :: 3 :: Only |
| 13 |
Classifier: Typing :: Typed |
| 14 |
Requires-Dist: pytest >= 6 ; extra == "test" |
| 15 |
Project-URL: Changelog, https://github.com/agronholm/exceptiongroup/blob/main/CHANGES.rst |
| 16 |
Project-URL: Issue Tracker, https://github.com/agronholm/exceptiongroup/issues |
| 17 |
Project-URL: Source code, https://github.com/agronholm/exceptiongroup |
| 18 |
Provides-Extra: test |
| 19 |
|
| 20 |
.. image:: https://github.com/agronholm/exceptiongroup/actions/workflows/test.yml/badge.svg |
| 21 |
:target: https://github.com/agronholm/exceptiongroup/actions/workflows/test.yml |
| 22 |
:alt: Build Status |
| 23 |
.. image:: https://coveralls.io/repos/github/agronholm/exceptiongroup/badge.svg?branch=main |
| 24 |
:target: https://coveralls.io/github/agronholm/exceptiongroup?branch=main |
| 25 |
:alt: Code Coverage |
| 26 |
|
| 27 |
This is a backport of the ``BaseExceptionGroup`` and ``ExceptionGroup`` classes from |
| 28 |
Python 3.11. |
| 29 |
|
| 30 |
It contains the following: |
| 31 |
|
| 32 |
* The ``exceptiongroup.BaseExceptionGroup`` and ``exceptiongroup.ExceptionGroup`` |
| 33 |
classes |
| 34 |
* A utility function (``exceptiongroup.catch()``) for catching exceptions possibly |
| 35 |
nested in an exception group |
| 36 |
* Patches to the ``TracebackException`` class that properly formats exception groups |
| 37 |
(installed on import) |
| 38 |
* An exception hook that handles formatting of exception groups through |
| 39 |
``TracebackException`` (installed on import) |
| 40 |
* Special versions of some of the functions from the ``traceback`` module, modified to |
| 41 |
correctly handle exception groups even when monkey patching is disabled, or blocked by |
| 42 |
another custom exception hook: |
| 43 |
|
| 44 |
* ``traceback.format_exception()`` |
| 45 |
* ``traceback.format_exception_only()`` |
| 46 |
* ``traceback.print_exception()`` |
| 47 |
* ``traceback.print_exc()`` |
| 48 |
* A backported version of ``contextlib.suppress()`` from Python 3.12.1 which also |
| 49 |
handles suppressing exceptions inside exception groups |
| 50 |
|
| 51 |
If this package is imported on Python 3.11 or later, the built-in implementations of the |
| 52 |
exception group classes are used instead, ``TracebackException`` is not monkey patched |
| 53 |
and the exception hook won't be installed. |
| 54 |
|
| 55 |
See the `standard library documentation`_ for more information on exception groups. |
| 56 |
|
| 57 |
.. _standard library documentation: https://docs.python.org/3/library/exceptions.html |
| 58 |
|
| 59 |
Catching exceptions |
| 60 |
=================== |
| 61 |
|
| 62 |
Due to the lack of the ``except*`` syntax introduced by `PEP 654`_ in earlier Python |
| 63 |
versions, you need to use ``exceptiongroup.catch()`` to catch exceptions that are |
| 64 |
potentially nested inside an exception group. This function returns a context manager |
| 65 |
that calls the given handler for any exceptions matching the sole argument. |
| 66 |
|
| 67 |
The argument to ``catch()`` must be a dict (or any ``Mapping``) where each key is either |
| 68 |
an exception class or an iterable of exception classes. Each value must be a callable |
| 69 |
that takes a single positional argument. The handler will be called at most once, with |
| 70 |
an exception group as an argument which will contain all the exceptions that are any |
| 71 |
of the given types, or their subclasses. The exception group may contain nested groups |
| 72 |
containing more matching exceptions. |
| 73 |
|
| 74 |
Thus, the following Python 3.11+ code: |
| 75 |
|
| 76 |
.. code-block:: python |
| 77 |
|
| 78 |
try: |
| 79 |
... |
| 80 |
except* (ValueError, KeyError) as excgroup: |
| 81 |
for exc in excgroup.exceptions: |
| 82 |
print('Caught exception:', type(exc)) |
| 83 |
except* RuntimeError: |
| 84 |
print('Caught runtime error') |
| 85 |
|
| 86 |
would be written with this backport like this: |
| 87 |
|
| 88 |
.. code-block:: python |
| 89 |
|
| 90 |
from exceptiongroup import BaseExceptionGroup, catch |
| 91 |
|
| 92 |
def value_key_err_handler(excgroup: BaseExceptionGroup) -> None: |
| 93 |
for exc in excgroup.exceptions: |
| 94 |
print('Caught exception:', type(exc)) |
| 95 |
|
| 96 |
def runtime_err_handler(exc: BaseExceptionGroup) -> None: |
| 97 |
print('Caught runtime error') |
| 98 |
|
| 99 |
with catch({ |
| 100 |
(ValueError, KeyError): value_key_err_handler, |
| 101 |
RuntimeError: runtime_err_handler |
| 102 |
}): |
| 103 |
... |
| 104 |
|
| 105 |
**NOTE**: Just like with ``except*``, you cannot handle ``BaseExceptionGroup`` or |
| 106 |
``ExceptionGroup`` with ``catch()``. |
| 107 |
|
| 108 |
Suppressing exceptions |
| 109 |
====================== |
| 110 |
|
| 111 |
This library contains a backport of the ``contextlib.suppress()`` context manager from |
| 112 |
Python 3.12.1. It allows you to selectively ignore certain exceptions, even when they're |
| 113 |
inside exception groups: |
| 114 |
|
| 115 |
.. code-block:: python |
| 116 |
|
| 117 |
from exceptiongroup import suppress |
| 118 |
|
| 119 |
with suppress(RuntimeError): |
| 120 |
raise ExceptionGroup("", [RuntimeError("boo")]) |
| 121 |
|
| 122 |
Notes on monkey patching |
| 123 |
======================== |
| 124 |
|
| 125 |
To make exception groups render properly when an unhandled exception group is being |
| 126 |
printed out, this package does two things when it is imported on any Python version |
| 127 |
earlier than 3.11: |
| 128 |
|
| 129 |
#. The ``traceback.TracebackException`` class is monkey patched to store extra |
| 130 |
information about exception groups (in ``__init__()``) and properly format them (in |
| 131 |
``format()``) |
| 132 |
#. An exception hook is installed at ``sys.excepthook``, provided that no other hook is |
| 133 |
already present. This hook causes the exception to be formatted using |
| 134 |
``traceback.TracebackException`` rather than the built-in rendered. |
| 135 |
|
| 136 |
If ``sys.exceptionhook`` is found to be set to something else than the default when |
| 137 |
``exceptiongroup`` is imported, no monkeypatching is done at all. |
| 138 |
|
| 139 |
To prevent the exception hook and patches from being installed, set the environment |
| 140 |
variable ``EXCEPTIONGROUP_NO_PATCH`` to ``1``. |
| 141 |
|
| 142 |
Formatting exception groups |
| 143 |
--------------------------- |
| 144 |
|
| 145 |
Normally, the monkey patching applied by this library on import will cause exception |
| 146 |
groups to be printed properly in tracebacks. But in cases when the monkey patching is |
| 147 |
blocked by a third party exception hook, or monkey patching is explicitly disabled, |
| 148 |
you can still manually format exceptions using the special versions of the ``traceback`` |
| 149 |
functions, like ``format_exception()``, listed at the top of this page. They work just |
| 150 |
like their counterparts in the ``traceback`` module, except that they use a separately |
| 151 |
patched subclass of ``TracebackException`` to perform the rendering. |
| 152 |
|
| 153 |
Particularly in cases where a library installs its own exception hook, it is recommended |
| 154 |
to use these special versions to do the actual formatting of exceptions/tracebacks. |
| 155 |
|
| 156 |
.. _PEP 654: https://www.python.org/dev/peps/pep-0654/ |
| 157 |
|