PEP 678: Clarify how the notes tuple is updated and when it is copied (#2377)

Co-authored-by: Irit Katriel <1055913+iritkatriel@users.noreply.github.com>
This commit is contained in:
Zac Hatfield-Dodds 2022-03-03 07:02:22 -08:00 committed by GitHub
parent 358854aac9
commit f373d8bbab
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 18 additions and 13 deletions

View File

@ -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 <print_idea>`__, 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.