CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="color-scheme" content="light dark"> <title>PEP 678 – Enriching Exceptions with Notes | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0678/"> <link rel="stylesheet" href="../_static/style.css" type="text/css"> <link rel="stylesheet" href="../_static/mq.css" type="text/css"> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light"> <link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark"> <link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss"> <meta property="og:title" content='PEP 678 – Enriching Exceptions with Notes | peps.python.org'> <meta property="og:description" content="Exception objects are typically initialized with a message that describes the error which has occurred. Because further information may be available when the exception is caught and re-raised, or included in an ExceptionGroup, this PEP proposes to add ..."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0678/"> <meta property="og:site_name" content="Python Enhancement Proposals (PEPs)"> <meta property="og:image" content="https://peps.python.org/_static/og-image.png"> <meta property="og:image:alt" content="Python PEPs"> <meta property="og:image:width" content="200"> <meta property="og:image:height" content="200"> <meta name="description" content="Exception objects are typically initialized with a message that describes the error which has occurred. Because further information may be available when the exception is caught and re-raised, or included in an ExceptionGroup, this PEP proposes to add ..."> <meta name="theme-color" content="#3776ab"> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all"> <title>Following system colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="9"></circle> <path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path> </svg> </symbol> <symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all"> <title>Selected dark colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <path stroke="none" d="M0 0h24v24H0z" fill="none"></path> <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path> </svg> </symbol> <symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all"> <title>Selected light colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="5"></circle> <line x1="12" y1="1" x2="12" y2="3"></line> <line x1="12" y1="21" x2="12" y2="23"></line> <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> <line x1="1" y1="12" x2="3" y2="12"></line> <line x1="21" y1="12" x2="23" y2="12"></line> <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> </svg> </symbol> </svg> <script> document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto" </script> <section id="pep-page-section"> <header> <h1>Python Enhancement Proposals</h1> <ul class="breadcrumbs"> <li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li> <li><a href="../pep-0000/">PEP Index</a> » </li> <li>PEP 678</li> </ul> <button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())"> <svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg> Toggle light / dark / auto colour theme </button> </header> <article> <section id="pep-content"> <h1 class="page-title">PEP 678 – Enriching Exceptions with Notes</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author:</dt> <dd class="field-odd">Zac Hatfield-Dodds <zac at zhd.dev></dd> <dt class="field-even">Sponsor:</dt> <dd class="field-even">Irit Katriel</dd> <dt class="field-odd">Discussions-To:</dt> <dd class="field-odd"><a class="reference external" href="https://discuss.python.org/t/pep-678-enriching-exceptions-with-notes/13374">Discourse thread</a></dd> <dt class="field-even">Status:</dt> <dd class="field-even"><abbr title="Accepted and implementation complete, or no longer active">Final</abbr></dd> <dt class="field-odd">Type:</dt> <dd class="field-odd"><abbr title="Normative PEP with a new feature for Python, implementation change for CPython or interoperability standard for the ecosystem">Standards Track</abbr></dd> <dt class="field-even">Requires:</dt> <dd class="field-even"><a class="reference external" href="../pep-0654/">654</a></dd> <dt class="field-odd">Created:</dt> <dd class="field-odd">20-Dec-2021</dd> <dt class="field-even">Python-Version:</dt> <dd class="field-even">3.11</dd> <dt class="field-odd">Post-History:</dt> <dd class="field-odd"><a class="reference external" href="https://discuss.python.org/t/pep-678-enriching-exceptions-with-notes/13374" title="Discourse thread">27-Jan-2022</a></dd> <dt class="field-even">Resolution:</dt> <dd class="field-even"><a class="reference external" href="https://discuss.python.org/t/pep-678-enriching-exceptions-with-notes/13374/100">Discourse message</a></dd> </dl> <hr class="docutils" /> <section id="contents"> <details><summary>Table of Contents</summary><ul class="simple"> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#motivation">Motivation</a><ul> <li><a class="reference internal" href="#example-usage">Example usage</a></li> <li><a class="reference internal" href="#non-goals">Non-goals</a></li> </ul> </li> <li><a class="reference internal" href="#specification">Specification</a></li> <li><a class="reference internal" href="#backwards-compatibility">Backwards Compatibility</a></li> <li><a class="reference internal" href="#how-to-teach-this">How to Teach This</a></li> <li><a class="reference internal" href="#reference-implementation">Reference Implementation</a></li> <li><a class="reference internal" href="#rejected-ideas">Rejected Ideas</a><ul> <li><a class="reference internal" href="#use-print-or-logging-etc">Use <code class="docutils literal notranslate">print()</code> (or <code class="docutils literal notranslate">logging</code>, etc.)</a></li> <li><a class="reference internal" href="#raise-wrapper-explanation-from-err"><code class="docutils literal notranslate">raise Wrapper(explanation) from err</code></a></li> <li><a class="reference internal" href="#an-assignable-note-attribute">An assignable <code class="docutils literal notranslate">__note__</code> attribute</a></li> <li><a class="reference internal" href="#subclass-exception-and-add-note-support-downstream">Subclass Exception and add note support downstream</a></li> <li><a class="reference internal" href="#don-t-attach-notes-to-exceptions-just-store-them-in-exceptiongroups">Don’t attach notes to <code class="docutils literal notranslate">Exception</code>s, just store them in <code class="docutils literal notranslate">ExceptionGroup</code>s</a></li> <li><a class="reference internal" href="#add-a-helper-function-contextlib-add-exc-note">Add a helper function <code class="docutils literal notranslate">contextlib.add_exc_note()</code></a></li> <li><a class="reference internal" href="#augment-the-raise-statement">Augment the <code class="docutils literal notranslate">raise</code> statement</a></li> </ul> </li> <li><a class="reference internal" href="#acknowledgements">Acknowledgements</a></li> <li><a class="reference internal" href="#references">References</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> </details></section> <div class="pep-banner canonical-doc sticky-banner admonition important"> Important This PEP is a historical document. The up-to-date, canonical documentation can now be found at <a class="reference external" href="https://docs.python.org/3/library/exceptions.html#BaseException.add_note" title="(in Python v3.13)"><code class="docutils literal notranslate">BaseException.add_note()</code></a> and <a class="reference external" href="https://docs.python.org/3/library/exceptions.html#BaseException.__notes__" title="(in Python v3.13)"><code class="docutils literal notranslate">BaseException.__notes__</code></a>. × See <a class="reference external" href="https://docs.python.org/3/tutorial/errors.html#tut-exception-notes" title="(in Python v3.13)">Enriching Exceptions with Notes</a> for a user-focused tutorial. See <a class="pep reference internal" href="../pep-0001/" title="PEP 1 – PEP Purpose and Guidelines">PEP 1</a> for how to propose changes. </div> <section id="abstract"> <h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2> Exception objects are typically initialized with a message that describes the error which has occurred. Because further information may be available when the exception is caught and re-raised, or included in an <code class="docutils literal notranslate">ExceptionGroup</code>, this PEP proposes to add <code class="docutils literal notranslate">BaseException.add_note(note)</code>, a <code class="docutils literal notranslate">.__notes__</code> attribute holding a list of notes so added, and to update the builtin traceback formatting code to include notes in the formatted traceback following the exception string. This is particularly useful in relation to <a class="pep reference internal" href="../pep-0654/" title="PEP 654 – Exception Groups and except*">PEP 654</a> <code class="docutils literal notranslate">ExceptionGroup</code>s, which make previous workarounds ineffective or confusing. Use cases have been identified in the standard library, Hypothesis and <code class="docutils literal notranslate">cattrs</code> packages, and common code patterns with retries. </section> <section id="motivation"> <h2><a class="toc-backref" href="#motivation" role="doc-backlink">Motivation</a></h2> When an exception is created in order to be raised, it is usually initialized with information that describes the error that has occurred. There are cases where it is useful to add information after the exception was caught. For example, <ul class="simple"> <li>testing libraries may wish to show the values involved in a failing assertion, or the steps to reproduce a failure (e.g. <code class="docutils literal notranslate">pytest</code> and <code class="docutils literal notranslate">hypothesis</code>; example below).</li> <li>code which retries an operation on error may wish to associate an iteration, timestamp, or other explanation with each of several errors - especially if re-raising them in an <code class="docutils literal notranslate">ExceptionGroup</code>.</li> <li>programming environments for novices can provide more detailed descriptions of various errors, and tips for resolving them.</li> </ul> Existing approaches must pass this additional information around while keeping it in sync with the state of raised, and potentially caught or chained, exceptions. This is already error-prone, and made more difficult by <a class="pep reference internal" href="../pep-0654/" title="PEP 654 – Exception Groups and except*">PEP 654</a> <code class="docutils literal notranslate">ExceptionGroup</code>s, so the time is right for a built-in solution. We therefore propose to add: <ul class="simple"> <li>a new method <code class="docutils literal notranslate">BaseException.add_note(note: str)</code>,</li> <li><code class="docutils literal notranslate">BaseException.__notes__</code>, a list of note strings added using <code class="docutils literal notranslate">.add_note()</code>, and</li> <li>support in the builtin traceback formatting code such that notes are displayed in the formatted traceback following the exception string.</li> </ul> <section id="example-usage"> <h3><a class="toc-backref" href="#example-usage" role="doc-backlink">Example usage</a></h3> <div class="highlight-default notranslate"><div class="highlight"><pre>>>> try: ... raise TypeError('bad type') ... except Exception as e: ... e.add_note('Add some information') ... raise ... Traceback (most recent call last): File "<stdin>", line 2, in <module> TypeError: bad type Add some information >>> </pre></div> </div> When collecting exceptions into an exception group, we may want to add context information for the individual errors. In the following example with <a class="reference external" href="https://github.com/HypothesisWorks/hypothesis/pull/3191">Hypothesis’ proposed support for ExceptionGroup</a>, each exception includes a note of the minimal failing example: <div class="highlight-default notranslate"><div class="highlight"><pre>from hypothesis import given, strategies as st, target @given(st.integers()) def test(x): assert x < 0 assert x > 0 + Exception Group Traceback (most recent call last): | File "test.py", line 4, in test | def test(x): | | File "hypothesis/core.py", line 1202, in wrapped_test | raise the_error_hypothesis_found | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ExceptionGroup: Hypothesis found 2 distinct failures. +-+---------------- 1 ---------------- | Traceback (most recent call last): | File "test.py", line 6, in test | assert x > 0 | ^^^^^^^^^^^^ | AssertionError: assert -1 > 0 | | Falsifying example: test( | x=-1, | ) +---------------- 2 ---------------- | Traceback (most recent call last): | File "test.py", line 5, in test | assert x < 0 | ^^^^^^^^^^^^ | AssertionError: assert 0 < 0 | | Falsifying example: test( | x=0, | ) +------------------------------------ </pre></div> </div> </section> <section id="non-goals"> <h3><a class="toc-backref" href="#non-goals" role="doc-backlink">Non-goals</a></h3> Tracking multiple notes as a list, rather than by concatenating strings when notes are added, is intended to maintain the distinction between the individual notes. This might be required in specialized use cases, such as translation of the notes by packages like <code class="docutils literal notranslate">friendly-traceback</code>. However, <code class="docutils literal notranslate">__notes__</code> is not intended to carry structured data. If your note is for use by a program rather than display to a human, <a class="reference external" href="https://discuss.python.org/t/accepting-pep-654-exception-groups-and-except/10813/26">we recommend</a> instead (or additionally) choosing a convention for an attribute, e.g. <code class="docutils literal notranslate">err._parse_errors = ...</code> on the error or <code class="docutils literal notranslate">ExceptionGroup</code>. As a rule of thumb, we suggest that you should prefer <a class="reference external" href="https://docs.python.org/3/tutorial/errors.html#exception-chaining">exception chaining</a> when the error is going to be re-raised or handled as an individual error, and prefer <code class="docutils literal notranslate">.add_note()</code> when you want to avoid changing the exception type or are collecting multiple exception objects to handle together. <a class="footnote-reference brackets" href="#id4" id="id1">[1]</a> </section> </section> <section id="specification"> <h2><a class="toc-backref" href="#specification" role="doc-backlink">Specification</a></h2> <code class="docutils literal notranslate">BaseException</code> gains a new method <code class="docutils literal notranslate">.add_note(note: str)</code>. If <code class="docutils literal notranslate">note</code> is a string, <code class="docutils literal notranslate">.add_note(note)</code> appends it to the <code class="docutils literal notranslate">__notes__</code> list, creating the attribute if it does not already exist. If <code class="docutils literal notranslate">note</code> is not a string, <code class="docutils literal notranslate">.add_note()</code> raises <code class="docutils literal notranslate">TypeError</code>. Libraries may clear existing notes by modifying or deleting the <code class="docutils literal notranslate">__notes__</code> list, if it has been created, including clearing all notes with <code class="docutils literal notranslate">del err.__notes__</code>. This allows full control over the attached notes, without overly complicating the API or adding multiple names to <code class="docutils literal notranslate">BaseException.__dict__</code>. When an exception is displayed by the interpreter’s builtin traceback-rendering code, its notes (if there are any) appear immediately after the exception message, in the order in which they were added, with each note starting on a new line. If <code class="docutils literal notranslate">__notes__</code> has been created, <code class="docutils literal notranslate">BaseExceptionGroup.subgroup</code> and <code class="docutils literal notranslate">BaseExceptionGroup.split</code> create a new list for each new instance, containing the same contents as the original exception group’s <code class="docutils literal notranslate">__notes__</code>. We do not specify the expected behaviour when users have assigned a non-list value to <code class="docutils literal notranslate">__notes__</code>, or a list which contains non-string elements. Implementations might choose to emit warnings, discard or ignore bad values, convert them to strings, raise an exception, or do something else entirely. </section> <section id="backwards-compatibility"> <h2><a class="toc-backref" href="#backwards-compatibility" role="doc-backlink">Backwards Compatibility</a></h2> System-defined or “dunder” names (following the pattern <code class="docutils literal notranslate">__*__</code>) are part of the language specification, with <a class="reference external" href="https://docs.python.org/3/reference/lexical_analysis.html#reserved-classes-of-identifiers">unassigned names reserved for future use and subject to breakage without warning</a>. We are also unaware of any code which would be broken by adding <code class="docutils literal notranslate">__notes__</code>. We were also unable to find any code which would be broken by the addition of <code class="docutils literal notranslate">BaseException.add_note()</code>: while searching Google and <a class="reference external" href="https://grep.app/search?q=.add_note%28&filter[lang][0]=Python">GitHub finds several definitions</a> of an <code class="docutils literal notranslate">.add_note()</code> method, none of them are on a subclass of <code class="docutils literal notranslate">BaseException</code>. </section> <section id="how-to-teach-this"> <h2><a class="toc-backref" href="#how-to-teach-this" role="doc-backlink">How to Teach This</a></h2> The <code class="docutils literal notranslate">add_note()</code> method and <code class="docutils literal notranslate">__notes__</code> attribute will be documented as part of the language standard, and explained as part of <a class="reference external" href="https://github.com/python/cpython/pull/30441">the “Errors and Exceptions” tutorial</a>. </section> <section id="reference-implementation"> <h2><a class="toc-backref" href="#reference-implementation" role="doc-backlink">Reference Implementation</a></h2> Following discussions related to <a class="pep reference internal" href="../pep-0654/" title="PEP 654 – Exception Groups and except*">PEP 654</a> <a class="footnote-reference brackets" href="#id5" id="id2">[2]</a>, an early version of this proposal was <a class="reference external" href="https://github.com/python/cpython/pull/29880">implemented in</a> and released in CPython 3.11.0a3, with a mutable string-or-none <code class="docutils literal notranslate">__note__</code> attribute. <a class="reference external" href="https://github.com/python/cpython/pull/31317">CPython PR #31317</a> implements <code class="docutils literal notranslate">.add_note()</code> and <code class="docutils literal notranslate">__notes__</code>. </section> <section id="rejected-ideas"> <h2><a class="toc-backref" href="#rejected-ideas" role="doc-backlink">Rejected Ideas</a></h2> <section id="use-print-or-logging-etc"> <h3><a class="toc-backref" href="#use-print-or-logging-etc" role="doc-backlink">Use <code class="docutils literal notranslate">print()</code> (or <code class="docutils literal notranslate">logging</code>, etc.)</a></h3> Reporting explanatory or contextual information about an error by printing or logging has historically been an acceptable workaround. However, we dislike the way this separates the content from the exception object it refers to - which can lead to “orphan” reports if the error was caught and handled later, or merely significant difficulties working out which explanation corresponds to which error. The new <code class="docutils literal notranslate">ExceptionGroup</code> type intensifies these existing challenges. Keeping the <code class="docutils literal notranslate">__notes__</code> attached to the exception object, in the same way as the <code class="docutils literal notranslate">__traceback__</code> attribute, eliminates these problems. </section> <section id="raise-wrapper-explanation-from-err"> <h3><a class="toc-backref" href="#raise-wrapper-explanation-from-err" role="doc-backlink"><code class="docutils literal notranslate">raise Wrapper(explanation) from err</code></a></h3> An alternative pattern is to use exception chaining: by raising a ‘wrapper’ exception containing the context or explanation <code class="docutils literal notranslate">from</code> the current exception, we avoid the separation challenges from <code class="docutils literal notranslate">print()</code>. However, this has two key problems. First, it changes the type of the exception, which is often a breaking change for downstream code. We consider always raising a <code class="docutils literal notranslate">Wrapper</code> exception unacceptably inelegant; but because custom exception types might have any number of required arguments we can’t always create an instance of the same type with our explanation. In cases where the exact exception type is known this can work, such as the standard library <code class="docutils literal notranslate">http.client</code> <a class="reference external" href="https://github.com/python/cpython/blob/69ef1b59983065ddb0b712dac3b04107c5059735/Lib/http/client.py#L596-L597">code</a>, but not for libraries which call user code. Second, exception chaining reports several lines of additional detail, which are distracting for experienced users and can be very confusing for beginners. For example, six of the eleven lines reported for this simple example relate to exception chaining, and are unnecessary with <code class="docutils literal notranslate">BaseException.add_note()</code>: <div class="highlight-python notranslate"><div class="highlight"><pre>class Explanation(Exception): def __str__(self): return "\n" + str(self.args[0]) try: raise AssertionError("Failed!") except Exception as e: raise Explanation("You can reproduce this error by ...") from e </pre></div> </div> <div class="highlight-default notranslate"><div class="highlight"><pre>$ python example.py Traceback (most recent call last): File "example.py", line 6, in <module> raise AssertionError(why) AssertionError: Failed! # These lines are The above exception was the direct cause of ... # confusing for new # users, and they Traceback (most recent call last): # only exist due File "example.py", line 8, in <module> # to implementation raise Explanation(msg) from e # constraints :-( Explanation: # Hence this PEP! You can reproduce this error by ... </pre></div> </div> In cases where these two problems do not apply, we encourage use of exception chaining rather than <code class="docutils literal notranslate">__notes__</code>. </section> <section id="an-assignable-note-attribute"> <h3><a class="toc-backref" href="#an-assignable-note-attribute" role="doc-backlink">An assignable <code class="docutils literal notranslate">__note__</code> attribute</a></h3> The first draft and implementation of this PEP defined a single attribute <code class="docutils literal notranslate">__note__</code>, which defaulted to <code class="docutils literal notranslate">None</code> but could have a string assigned. This is substantially simpler if, and only if, there is at most one note. To promote interoperability and support translation of error messages by libraries such as <code class="docutils literal notranslate">friendly-traceback</code>, without resorting to dubious parsing heuristics, we therefore settled on the <code class="docutils literal notranslate">.add_note()</code>-and-<code class="docutils literal notranslate">__notes__</code> API. </section> <section id="subclass-exception-and-add-note-support-downstream"> <h3><a class="toc-backref" href="#subclass-exception-and-add-note-support-downstream" role="doc-backlink">Subclass Exception and add note support downstream</a></h3> Traceback printing is built into the C code, and reimplemented in pure Python in <code class="docutils literal notranslate">traceback.py</code>. To get <code class="docutils literal notranslate">err.__notes__</code> printed from a downstream implementation would also require writing custom traceback-printing code; while this could be shared between projects and reuse some pieces of traceback.py <a class="footnote-reference brackets" href="#id6" id="id3">[3]</a> we prefer to implement this once, upstream. Custom exception types could implement their <code class="docutils literal notranslate">__str__</code> method to include our proposed <code class="docutils literal notranslate">__notes__</code> semantics, but this would be rarely and inconsistently applicable. </section> <section id="don-t-attach-notes-to-exceptions-just-store-them-in-exceptiongroups"> <h3><a class="toc-backref" href="#don-t-attach-notes-to-exceptions-just-store-them-in-exceptiongroups" role="doc-backlink">Don’t attach notes to <code class="docutils literal notranslate">Exception</code>s, just store them in <code class="docutils literal notranslate">ExceptionGroup</code>s</a></h3> The initial motivation for this PEP was to associate a note with each error in an <code class="docutils literal notranslate">ExceptionGroup</code>. At the cost of a remarkably awkward API and the cross-referencing problem discussed <a class="reference external" href="print_idea">above</a>, this use-case could be supported by storing notes on the <code class="docutils literal notranslate">ExceptionGroup</code> instance instead of on each exception it contains. We believe that the cleaner interface, and other use-cases described above, are sufficient to justify the more general feature proposed by this PEP. </section> <section id="add-a-helper-function-contextlib-add-exc-note"> <h3><a class="toc-backref" href="#add-a-helper-function-contextlib-add-exc-note" role="doc-backlink">Add a helper function <code class="docutils literal notranslate">contextlib.add_exc_note()</code></a></h3> It <a class="reference external" href="https://www.reddit.com/r/Python/comments/rmrvxv/pep_678_enriching_exceptions_with_notes/hptbul1/">was suggested</a> that we add a utility such as the one below to the standard library. We do not see this idea as core to the proposal of this PEP, and thus leave it for later or downstream implementation - perhaps based on this example code: <div class="highlight-python notranslate"><div class="highlight"><pre>@contextlib.contextmanager def add_exc_note(note: str): try: yield except Exception as err: err.add_note(note) raise with add_exc_note(f"While attempting to frobnicate {item=}"): frobnicate_or_raise(item) </pre></div> </div> </section> <section id="augment-the-raise-statement"> <h3><a class="toc-backref" href="#augment-the-raise-statement" role="doc-backlink">Augment the <code class="docutils literal notranslate">raise</code> statement</a></h3> One discussion proposed <code class="docutils literal notranslate">raise Exception() with "note contents"</code>, but this does not address the original motivation of compatibility with <code class="docutils literal notranslate">ExceptionGroup</code>. Furthermore, we do not believe that the problem we are solving requires or justifies new language syntax. </section> </section> <section id="acknowledgements"> <h2><a class="toc-backref" href="#acknowledgements" role="doc-backlink">Acknowledgements</a></h2> We wish to thank the many people who have assisted us through conversation, code review, design advice, and implementation: Adam Turner, Alex Grönholm, André Roberge, Barry Warsaw, Brett Cannon, CAM Gerlach, Carol Willing, Damian, Erlend Aasland, Etienne Pot, Gregory Smith, Guido van Rossum, Irit Katriel, Jelle Zijlstra, Ken Jin, Kumar Aditya, Mark Shannon, Matti Picus, Petr Viktorin, Will McGugan, and pseudonymous commenters on Discord and Reddit. </section> <section id="references"> <h2><a class="toc-backref" href="#references" role="doc-backlink">References</a></h2> <aside class="footnote-list brackets"> <aside class="footnote brackets" id="id4" role="doc-footnote"> <dt class="label" id="id4">[<a href="#id1">1</a>]</dt> <dd>this principle was established in the 2003 mail thread which led to <a class="pep reference internal" href="../pep-3134/" title="PEP 3134 – Exception Chaining and Embedded Tracebacks">PEP 3134</a>, and included a proposal for a group-of-exceptions type! <a class="reference external" href="https://mail.python.org/pipermail/python-dev/2003-January/032492.html">https://mail.python.org/pipermail/python-dev/2003-January/032492.html</a></aside> <aside class="footnote brackets" id="id5" role="doc-footnote"> <dt class="label" id="id5">[<a href="#id2">2</a>]</dt> <dd>particularly those at <a class="reference external" href="https://bugs.python.org/issue45607">https://bugs.python.org/issue45607</a>, <a class="reference external" href="https://discuss.python.org/t/accepting-pep-654-exception-groups-and-except/10813/9">https://discuss.python.org/t/accepting-pep-654-exception-groups-and-except/10813/9</a>, <a class="reference external" href="https://github.com/python/cpython/pull/28569#discussion_r721768348">https://github.com/python/cpython/pull/28569#discussion_r721768348</a>, and</aside> <aside class="footnote brackets" id="id6" role="doc-footnote"> <dt class="label" id="id6">[<a href="#id3">3</a>]</dt> <dd>We note that the <code class="docutils literal notranslate">exceptiongroup</code> backport package maintains an exception hook and monkeypatch for <code class="docutils literal notranslate">TracebackException</code> for Pythons older than 3.11, and encourage library authors to avoid creating additional and incompatible backports. We also reiterate our preference for builtin support which makes such measures unnecessary.</aside> </aside> </section> <section id="copyright"> <h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2> This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive. </section> </section> <hr class="docutils" /> Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0678.rst">https://github.com/python/peps/blob/main/peps/pep-0678.rst</a> Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0678.rst">2023-10-10 15:15:34 GMT</a> </article> <nav id="pep-sidebar"> <h2>Contents</h2> <ul> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#motivation">Motivation</a><ul> <li><a class="reference internal" href="#example-usage">Example usage</a></li> <li><a class="reference internal" href="#non-goals">Non-goals</a></li> </ul> </li> <li><a class="reference internal" href="#specification">Specification</a></li> <li><a class="reference internal" href="#backwards-compatibility">Backwards Compatibility</a></li> <li><a class="reference internal" href="#how-to-teach-this">How to Teach This</a></li> <li><a class="reference internal" href="#reference-implementation">Reference Implementation</a></li> <li><a class="reference internal" href="#rejected-ideas">Rejected Ideas</a><ul> <li><a class="reference internal" href="#use-print-or-logging-etc">Use <code class="docutils literal notranslate">print()</code> (or <code class="docutils literal notranslate">logging</code>, etc.)</a></li> <li><a class="reference internal" href="#raise-wrapper-explanation-from-err"><code class="docutils literal notranslate">raise Wrapper(explanation) from err</code></a></li> <li><a class="reference internal" href="#an-assignable-note-attribute">An assignable <code class="docutils literal notranslate">__note__</code> attribute</a></li> <li><a class="reference internal" href="#subclass-exception-and-add-note-support-downstream">Subclass Exception and add note support downstream</a></li> <li><a class="reference internal" href="#don-t-attach-notes-to-exceptions-just-store-them-in-exceptiongroups">Don’t attach notes to <code class="docutils literal notranslate">Exception</code>s, just store them in <code class="docutils literal notranslate">ExceptionGroup</code>s</a></li> <li><a class="reference internal" href="#add-a-helper-function-contextlib-add-exc-note">Add a helper function <code class="docutils literal notranslate">contextlib.add_exc_note()</code></a></li> <li><a class="reference internal" href="#augment-the-raise-statement">Augment the <code class="docutils literal notranslate">raise</code> statement</a></li> </ul> </li> <li><a class="reference internal" href="#acknowledgements">Acknowledgements</a></li> <li><a class="reference internal" href="#references">References</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> <a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0678.rst">Page Source (GitHub)</a> </nav> </section> <script src="../_static/colour_scheme.js"></script> <script src="../_static/wrap_tables.js"></script> <script src="../_static/sticky_banner.js"></script> </body> </html>