摘要

異常物件通常用描述所發生錯誤的訊息進行初始化。由於當捕獲並重新引發異常時，或者包含在 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 許可證下，以更寬鬆者為準。