摘要

异常对象通常使用描述已发生错误的消息进行初始化。因为在捕获和重新引发异常时或包含在 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__ 或包含非字符串元素的列表时的预期行为。实现可以选择发出警告、丢弃或忽略错误值、将其转换为字符串、引发异常或执行其他任何操作。

向后兼容性

系统定义或“双下划线”名称（遵循 __*__ 模式）是语言规范的一部分，其中 未分配的名称保留供将来使用，并且可能会在未经警告的情况下被破坏。我们也不知道有任何代码会被添加 __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 许可证，以两者中更宽松者为准。