diff --git a/pep-0678.rst b/pep-0678.rst index df3b97c88..22a04dc76 100644 --- a/pep-0678.rst +++ b/pep-0678.rst @@ -59,6 +59,7 @@ therefore propose to add: Example usage ------------- +:: >>> try: ... raise TypeError('bad type') @@ -140,10 +141,11 @@ are collecting multiple exception objects to handle together. [1]_ Specification ============= -``BaseException`` gains a new read-only attribute ``__notes__``, an initially -empty tuple, and a new method ``.add_note(note: str)``. ``note`` is added to -the exception's notes, which appear in the standard traceback after the -exception string. A ``TypeError`` is raised if ``note`` is not a string. +``BaseException`` gains a new new method ``.add_note(note: str)``. Notes are +exposed as a tuple via the read-only attribute ``__notes__``, and appear in +the standard traceback after the exception string. ``.add_note(note)`` replaces +``__notes__`` with a new tuple equal to ``__notes__ + (note,)``, if ``note`` +is a string, and raises ``TypeError`` otherwise. ``del err.__notes__`` clears the contents of the ``__notes__`` attribute, leaving it an empty tuple as if ``.add_note()`` had never been called. This @@ -198,6 +200,8 @@ implements ``.add_note()`` and ``__notes__``. Rejected Ideas ============== +.. _print_idea: + Use ``print()`` (or ``logging``, etc.) -------------------------------------- Reporting explanatory or contextual information about an error by printing or @@ -319,15 +323,16 @@ proposed ``__notes__`` semantics, but this would be rarely and inconsistently applicable. -Store notes in ``ExceptionGroup``\ s ------------------------------------- -Initial discussions proposed making a more focussed change by thinking about -how to associate messages with the nested exceptions in ``ExceptionGroup`` s, -such as a list of notes or mapping of exceptions to notes. However, this would -force a remarkably awkward API and retains a lesser form of the -cross-referencing problem discussed under "use ``print()``" above; if this PEP -is rejected we prefer the status quo. Finally, of course, ``__notes__`` are -not only useful with ``ExceptionGroup``\ s! +Don't attach notes to ``Exception``\ s, just store them in ``ExceptionGroup``\ s +-------------------------------------------------------------------------------- +The initial motivation for this PEP was to associate a note with each error +in an ``ExceptionGroup``. At the cost of a remarkably awkward API and the +cross-referencing problem discussed `above `__, this +use-case could be supported by storing notes on the ``ExceptionGroup`` +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.