Exceptions in einer Python-Bibliothek gestalten

Ziel

Aufrufenden erlauben, die Fehlschläge, die sie behandeln können, von jenen zu unterscheiden, die sie nicht behandeln können, ohne Meldungen zu parsen, und die ursprüngliche Ursache erhalten, wenn Fehler über Schichten hinweg übersetzt werden.

Voraussetzungen

Ein klares Bild der Fehlerklassen der Bibliothek: ungültige Eingabe, fehlendes Objekt, Konflikt, nicht verfügbare Abhängigkeit.

Schritte

1. class LibraryError(Exception) als Basis definieren und eine Unterklasse pro Fehlerklasse, die eine aufrufende Stelle unterschiedlich behandeln könnte (NotFound, Conflict, Unavailable).
2. Die spezifischste Klasse mit einer Meldung auslösen, die festhält, was erwartet und was gefunden wurde, ohne Geheimnisse.
3. Beim Umhüllen eines tieferliegenden Fehlers raise Specific(...) from original verwenden, damit __cause__ gesetzt wird und der Traceback beide zeigt.
4. Exceptions nur dort abfangen, wo man sich davon erholen, es erneut versuchen oder sie übersetzen kann (zum Beispiel in einen HTTP-Status an der API-Grenze); den Rest weiterreichen lassen.
5. In Bibliothekscode niemals BaseException oder ein nacktes except: abfangen; KeyboardInterrupt und SystemExit müssen durchgereicht werden.
6. Die ausgelösten Exceptions im Docstring der öffentlichen Funktion dokumentieren.

Erwartetes Ergebnis

Aufrufende schreiben except NotFound: statt Zeichenketten abzugleichen; Logs zeigen die vollständige Ursachenkette; unerwartete Fehler sind sichtbar, statt still verschluckt zu werden.

Grenzen und Prüfbasis

Zu feine Hierarchien werden zu Rauschen; drei bis sechs Klassen decken die meisten Bibliotheken ab. Exceptions sind kein Ersatz für Rückgabewerte in Hot Paths, in denen Fehlschlag der Regelfall ist. Die Mechanik folgt der zitierten Dokumentation.