Mercurial > repos > rliterman > csp2

comparison CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/lib/python3.8/site-packages/exceptiongroup-1.2.2.dist-info/METADATA @ 68:5028fdace37b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 16:23:26 -0400
parents
children
comparison
equal deleted inserted replaced
67:0e9998148a16 68:5028fdace37b
1 Metadata-Version: 2.1
2 Name: exceptiongroup
3 Version: 1.2.2
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