PKG-INFO (6636B)
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 <alex.gronholm@nextday.fi> 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