Beispielhafte Nutzung

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

Beim Sammeln von Ausnahmen in einer Ausnahme-Gruppe möchten wir möglicherweise Kontextinformationen für die einzelnen Fehler hinzufügen. Im folgenden Beispiel mit Hypothesis' vorgeschlagener Unterstützung für ExceptionGroup enthält jede Ausnahme eine Notiz des minimalen fehlerhaften Beispiels

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

Non-goals

Das Verfolgen mehrerer Notizen als Liste anstatt durch Aneinanderreihung von Zeichenketten beim Hinzufügen von Notizen soll die Unterscheidung zwischen den einzelnen Notizen beibehalten. Dies könnte in spezialisierten Anwendungsfällen erforderlich sein, z. B. bei der Übersetzung von Notizen durch Pakete wie friendly-traceback.

Es ist jedoch nicht beabsichtigt, dass __notes__ strukturierte Daten enthält. Wenn Ihre Notiz für die Verwendung durch ein Programm und nicht zur Anzeige für einen Menschen bestimmt ist, empfehlen wir stattdessen (oder zusätzlich) eine Konvention für ein Attribut zu wählen, z. B. err._parse_errors = ... für den Fehler oder die ExceptionGroup.

Als Faustregel schlagen wir vor, dass Sie die Ausnahmeverkettung bevorzugen sollten, wenn die Ausnahme erneut ausgelöst oder als einzelne Ausnahme behandelt wird, und .add_note() bevorzugen sollten, wenn Sie den Ausnahmetyp nicht ändern möchten oder mehrere Ausnahmeobjekte zum gemeinsamen Verarbeiten sammeln. [1]

Verwenden Sie print() (oder logging, etc.)

Das Melden von erklärenden oder kontextbezogenen Informationen über einen Fehler durch Drucken oder Protokollieren war historisch gesehen eine akzeptable Lösung. Wir mögen jedoch nicht, wie dies den Inhalt von dem Ausnahmeobjekt trennt, auf das es sich bezieht – dies kann zu „verwaisten“ Berichten führen, wenn der Fehler später abgefangen und behandelt wurde, oder lediglich zu erheblichen Schwierigkeiten bei der Zuordnung, welche Erklärung zu welchem Fehler gehört. Der neue ExceptionGroup-Typ verschärft diese bestehenden Herausforderungen.

Das Beibehalten der __notes__ am Ausnahmeobjekt, auf die gleiche Weise wie das __traceback__-Attribut, eliminiert diese Probleme.

raise Wrapper(explanation) from err

Ein alternatives Muster ist die Verwendung von Ausnahmeverkettung: Indem eine „Wrapper“-Ausnahme ausgelöst wird, die den Kontext oder die Erklärung from der aktuellen Ausnahme enthält, vermeiden wir die Trennungsprobleme von print(). Dies hat jedoch zwei Hauptprobleme.

Erstens ändert es den Typ der Ausnahme, was für nachgelagerten Code oft eine brechende Änderung darstellt. Wir halten das *ständige* Auslösen einer Wrapper-Ausnahme für unannehmbar unintelligent; aber da benutzerdefinierte Ausnahmetypen beliebige erforderliche Argumente haben können, können wir nicht immer eine Instanz des *gleichen* Typs mit unserer Erklärung erstellen. In Fällen, in denen der genaue Ausnahmetyp bekannt ist, kann dies funktionieren, wie z. B. im Code der Standardbibliothek http.client Code, aber nicht für Bibliotheken, die Benutzercode aufrufen.

Zweitens zeigt die Ausnahmeverkettung mehrere zusätzliche Zeilen an Details an, die für erfahrene Benutzer ablenkend und für Anfänger sehr verwirrend sein können. Zum Beispiel beziehen sich sechs der elf Zeilen, die für dieses einfache Beispiel gemeldet werden, auf Ausnahmeverkettung und sind mit BaseException.add_note() unnötig.

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

**In Fällen, in denen diese beiden Probleme nicht zutreffen, empfehlen wir die Verwendung von Ausnahmeverkettung anstelle von** __notes__.

Ein zuweisbares Attribut __note__

Der erste Entwurf und die Implementierung dieser PEP definierten ein einzelnes Attribut __note__, das standardmäßig None war, dem aber eine Zeichenkette zugewiesen werden konnte. Dies ist nur dann wesentlich einfacher, wenn es höchstens eine Notiz gibt.

Um die Interoperabilität zu fördern und die Übersetzung von Fehlermeldungen durch Bibliotheken wie friendly-traceback ohne zweifelhafte Parsing-Heuristiken zu unterstützen, haben wir uns daher für die API .add_note() und __notes__ entschieden.

Leiten Sie von Exception ab und fügen Sie nachgelagert Notizunterstützung hinzu

Die Traceback-Ausgabe ist in C-Code eingebaut und wird in reinem Python in traceback.py neu implementiert. Um err.__notes__ aus einer nachgelagerten Implementierung drucken zu lassen, müsste man *auch* benutzerdefinierten Code zur Traceback-Ausgabe schreiben; obwohl dieser zwischen Projekten geteilt und einige Teile von traceback.py wiederverwenden könnte [3], ziehen wir es vor, dies einmal, upstream, zu implementieren.

Benutzerdefinierte Ausnahmetypen könnten ihre __str__-Methode implementieren, um unsere vorgeschlagene __notes__-Semantik einzubeziehen, aber dies wäre selten und inkonsistent anwendbar.

Hängen Sie keine Notizen an Exceptions, sondern speichern Sie sie nur in ExceptionGroups

Die ursprüngliche Motivation für diese PEP war, jeder Ausnahme in einer ExceptionGroup eine Notiz zuzuordnen. Auf Kosten einer bemerkenswert umständlichen API und des oben diskutierten Cross-Referencing-Problems könnte dieser Anwendungsfall unterstützt werden, indem Notizen auf der ExceptionGroup-Instanz anstatt auf jeder einzelnen Ausnahme, die sie enthält, gespeichert werden.

Wir glauben, dass die sauberere Schnittstelle und andere oben beschriebene Anwendungsfälle ausreichen, um das allgemeinere Feature, das diese PEP vorschlägt, zu rechtfertigen.

Fügen Sie eine Hilfsfunktion contextlib.add_exc_note() hinzu

Es wurde vorgeschlagen, dass wir ein Dienstprogramm wie das untenstehende zur Standardbibliothek hinzufügen. Wir sehen diese Idee nicht als Kernstück des Vorschlags dieser PEP an und überlassen sie daher einer späteren oder nachgelagerten Implementierung – möglicherweise basierend auf diesem Beispielcode.

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

Erweitern Sie die raise-Anweisung

Eine Diskussion schlug raise Exception() with "note contents" vor, aber dies löst nicht die ursprüngliche Motivation der Kompatibilität mit ExceptionGroup.

Darüber hinaus glauben wir nicht, dass das Problem, das wir lösen, eine neue Syntax erfordert oder rechtfertigt.