diff --git a/pep-0678.rst b/pep-0678.rst index 3aa8b66779e..c7acdcc07e6 100644 --- a/pep-0678.rst +++ b/pep-0678.rst @@ -115,15 +115,16 @@ includes a note of the minimal failing example:: Non-goals --------- ``__note__`` is *not* intended to carry structured data. If your note is for -use by a program rather than display to a human, we recommend instead (or -additionally) choosing a convention for an attribute like e.g. -``err._parse_errors = ...`` on the error or ``ExceptionGroup`` [1]_ [2]_ +use by a program rather than display to a human, `we recommend +`__ +instead (or additionally) choosing a convention for an attribute, e.g. +``err._parse_errors = ...`` on the error or ``ExceptionGroup``. As a rule of thumb, prefer `exception chaining `__ when the error is going to be re-raised or handled as an individual error, and prefer ``__note__`` when you are collecting multiple exception objects to handle -together or later. [3]_ +together or later. [1]_ Specification @@ -149,8 +150,9 @@ Backwards Compatibility ======================= System-defined or "dunder" names (following the pattern ``__*__``) are part of -the language specification, with unassigned names reserved for future use and -subject to breakage without warning [4]_. +the language specification, with `unassigned names reserved for future use and +subject to breakage without warning +`__. We are also unaware of any code which *would* be broken by adding ``__note__``; assigning to a ``.__note__`` attribute already *works* on current versions of @@ -163,16 +165,15 @@ How to Teach This ================= The ``__note__`` attribute will be documented as part of the language standard, -and explained as part of the tutorial "Errors and Exceptions" [5]_. - +and explained as part of `the "Errors and Exceptions" tutorial +`__. Reference Implementation ======================== -``BaseException.__note__`` was implemented in [6]_ and released in CPython -3.11.0a3, following discussions related to :pep:`654`. [7]_ [8]_ [9]_ - +``BaseException.__note__`` was `implemented in `__ and released in CPython +3.11.0a3, following discussions related to :pep:`654`. [2]_ Rejected Ideas @@ -204,8 +205,9 @@ for downstream code. We consider *always* raising a ``Wrapper`` 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 ``http.client`` code [10]_, but not -for libraries which call user code. +this can work, such as the standard library ``http.client`` `code +`__, +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. @@ -297,9 +299,11 @@ formatted for display after propagation. Add a helper function ``contextlib.add_exc_note()`` --------------------------------------------------- -It was suggested [11]_ that we add a utility such as the one below to the -standard library. We are open to this idea, but do not see it as a core part of -the proposal of this PEP as it can be added as an enhancement later. +It `was suggested +`__ +that we add a utility such as the one below to the standard library. We are +open to this idea, but do not see it as a core part of the proposal of this PEP +as it can be added as an enhancement later. .. code-block:: python @@ -329,19 +333,12 @@ justifies new language syntax. References ========== -.. [1] https://discuss.python.org/t/accepting-pep-654-exception-groups-and-except/10813/26 -.. [2] https://bugs.python.org/issue46431 -.. [3] this principle was established in the 2003 mail thread which led to :pep:`3134`, +.. [1] this principle was established in the 2003 mail thread which led to :pep:`3134`, and included a proposal for a group-of-exceptions type! https://mail.python.org/pipermail/python-dev/2003-January/032492.html -.. [4] https://docs.python.org/3/reference/lexical_analysis.html#reserved-classes-of-identifiers -.. [5] https://github.com/python/cpython/pull/30441 -.. [6] https://github.com/python/cpython/pull/29880 -.. [7] https://discuss.python.org/t/accepting-pep-654-exception-groups-and-except/10813/9 -.. [8] https://github.com/python/cpython/pull/28569#discussion_r721768348 -.. [9] https://bugs.python.org/issue45607 -.. [10] https://github.com/python/cpython/blob/69ef1b59983065ddb0b712dac3b04107c5059735/Lib/http/client.py#L596-L597 -.. [11] https://www.reddit.com/r/Python/comments/rmrvxv/pep_678_enriching_exceptions_with_notes/hptbul1/ +.. [2] particularly those at https://bugs.python.org/issue45607, + https://discuss.python.org/t/accepting-pep-654-exception-groups-and-except/10813/9, + https://github.com/python/cpython/pull/28569#discussion_r721768348, and