Skip to content

Commit

Permalink
PEP 678: Convert footnotes to inline links
Browse files Browse the repository at this point in the history
  • Loading branch information
Zac-HD committed Feb 8, 2022
1 parent 84bbab8 commit 23d1716
Showing 1 changed file with 25 additions and 27 deletions.
52 changes: 25 additions & 27 deletions pep-0678.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
<https://discuss.python.org/t/accepting-pep-654-exception-groups-and-except/10813/26>`__
instead (or additionally) choosing a convention for an attribute like e.g.
``err._parse_errors = ...`` on the error or ``ExceptionGroup``.

As a rule of thumb, prefer `exception chaining
<https://docs.python.org/3/tutorial/errors.html#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
Expand All @@ -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
<https://docs.python.org/3/reference/lexical_analysis.html#reserved-classes-of-identifiers>`__.

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
Expand All @@ -163,17 +165,17 @@ 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
<https://github.com/python/cpython/pull/30441>`__.


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 <https://github.com/python/cpython/pull/29880>`__ and released in CPython
3.11.0a3, following discussions related to :pep:`654`. [2]_

https://bugs.python.org/issue45607

Rejected Ideas
==============
Expand Down Expand Up @@ -204,8 +206,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
<https://github.com/python/cpython/blob/69ef1b59983065ddb0b712dac3b04107c5059735/Lib/http/client.py#L596-L597>`__,
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.
Expand Down Expand Up @@ -297,9 +300,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
<https://www.reddit.com/r/Python/comments/rmrvxv/pep_678_enriching_exceptions_with_notes/hptbul1/>`__
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
Expand Down Expand Up @@ -329,19 +334,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
Expand Down

0 comments on commit 23d1716

Please sign in to comment.