摘要

异常对象通常用描述所发生错误的消息进行初始化。由于当捕获并重新引发异常时，或者包含在 ExceptionGroup 中时，可能会有更多信息可用，本 PEP 提议添加 BaseException.add_note(note)，一个 .__notes__ 属性，用于存储所添加备注的列表，并更新内置的追溯格式化代码，以便在格式化的追溯中将备注包含在异常字符串之后。

这对于与 PEP 654 ExceptionGroup 有关的情况特别有用，它使以前的变通方法无效或令人困惑。在标准库、Hypothesis 和 cattrs 包以及带有重试的常见代码模式中已经确定了用例。

动机

当创建异常以便引发时，它通常用描述所发生错误的信息进行初始化。在某些情况下，在捕获异常后添加信息会很有用。例如，

• 测试库可能希望显示失败断言中涉及的值，或重现失败的步骤（例如 pytest 和 hypothesis；下面的示例）。
• 当操作出错时重试的代码可能希望将迭代、时间戳或其他解释与多个错误中的每一个关联起来——尤其是在 ExceptionGroup 中重新引发它们时。
• 为初学者设计的编程环境可以提供各种错误的更详细描述，以及解决它们的提示。

现有方法必须在传递这些额外信息的同时，使其与已引发的以及可能已捕获或已链接的异常状态保持同步。这已经容易出错，并且由于 PEP 654 ExceptionGroup 而变得更加困难，因此是时候采用内置解决方案了。因此，我们提议添加

• 一个新方法 BaseException.add_note(note: str)，
• BaseException.__notes__，一个使用 .add_note() 添加的备注字符串列表，以及
• 内置追溯格式化代码中的支持，以便在格式化的追溯中将备注显示在异常字符串之后。

>>> 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
>>>

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,
    | )
    +------------------------------------

规范

BaseException 获得一个新方法 .add_note(note: str)。如果 note 是一个字符串，.add_note(note) 会将其附加到 __notes__ 列表，如果该属性不存在则创建它。如果 note 不是字符串，.add_note() 会引发 TypeError。

如果 __notes__ 列表已创建，库可以通过修改或删除该列表来清除现有备注，包括使用 del err.__notes__ 清除所有备注。这允许完全控制附加的备注，而不会过度复杂化 API 或向 BaseException.__dict__ 添加多个名称。

当解释器的内置回溯渲染代码显示异常时，它的备注（如果有的话）将紧跟在异常消息之后，按照添加的顺序显示，每个备注从新的一行开始。

如果 __notes__ 已被创建，BaseExceptionGroup.subgroup 和 BaseExceptionGroup.split 会为每个新实例创建一个新列表，其中包含与原始异常组的 __notes__ 相同的内容。

我们**不**指定当用户将非列表值分配给 __notes__，或包含非字符串元素的列表时，预期的行为。实现可以选择发出警告、丢弃或忽略错误值、将其转换为字符串、引发异常或完全做其他事情。

向后兼容性

系统定义的或“dunder”名称（遵循 __*__ 模式）是语言规范的一部分，未分配的名称保留供将来使用，并且可能会在不事先通知的情况下中断。我们也没有发现任何会因添加 __notes__ 而导致中断的代码。

我们也没有发现任何会因添加 BaseException.add_note() 而中断的代码：虽然在 Google 和 GitHub 上找到了几个 .add_note() 方法的定义，但它们都不是 BaseException 的子类。

如何教授此内容

add_note() 方法和 __notes__ 属性将作为语言标准的一部分进行文档化，并在“错误和异常”教程中进行解释。

参考实现

在围绕PEP 654[2]进行的讨论之后，此提案的早期版本在 CPython 3.11.0a3 中实现并发布，带有一个可变的字符串或 None 类型的 __note__ 属性。

CPython PR #31317 实现了 .add_note() 和 __notes__。

被拒绝的想法

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

$ 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 ...

@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)

致谢

我们要感谢许多通过对话、代码审查、设计建议和实现帮助过我们的人：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，以及 Discord 和 Reddit 上的匿名评论者。

参考资料

版权

本文档置于公共领域或 CC0-1.0-Universal 许可证下，以更宽松者为准。