Eingebaute Exceptions¶

In Python müssen alle Exceptions Instanzen einer Klasse sein, die von BaseException abgeleitet ist. In einer try-Anweisung mit einer except-Klausel, die eine bestimmte Klasse angibt, behandelt diese Klausel auch alle Exception-Klassen, die von dieser Klasse abgeleitet sind (jedoch keine Exception-Klassen, von denen sie abgeleitet ist). Zwei Exception-Klassen, die nicht durch Vererbung miteinander verwandt sind, sind niemals äquivalent, selbst wenn sie denselben Namen tragen.

Die in diesem Kapitel aufgeführten eingebauten Exceptions können vom Interpreter oder von eingebauten Funktionen erzeugt werden. Sofern nicht anders angegeben, besitzen sie einen „zugehörigen Wert“, der die genaue Fehlerursache angibt. Dies kann eine Zeichenkette oder ein Tupel aus mehreren Informationselementen sein (z. B. ein Fehlercode und eine Zeichenkette, die den Code erklärt). Der zugehörige Wert wird üblicherweise als Argument an den Konstruktor der Exception-Klasse übergeben.

Benutzercode kann eingebaute Exceptions auslösen. Dies kann genutzt werden, um einen Exception-Handler zu testen oder einen Fehlerzustand „genauso“ zu melden wie in der Situation, in der der Interpreter dieselbe Exception auslösen würde. Beachte jedoch, dass Benutzercode nicht daran gehindert wird, einen unpassenden Fehler auszulösen.

Von den eingebauten Exception-Klassen können Unterklassen abgeleitet werden, um neue Exceptions zu definieren. Es wird empfohlen, neue Exceptions von der Klasse Exception oder einer ihrer Unterklassen abzuleiten und nicht von BaseException. Weitere Informationen zur Definition von Exceptions findest du im Python-Tutorial unter Benutzerdefinierte Ausnahmen.

Exception-Kontext¶

Drei Attribute von Exception-Objekten liefern Informationen über den Kontext, in dem die Exception ausgelöst wurde:

BaseException.__context__¶

BaseException.__cause__¶

BaseException.__suppress_context__¶

Wird eine neue Exception ausgelöst, während bereits eine andere Exception behandelt wird, wird das Attribut __context__ der neuen Exception automatisch auf die behandelte Exception gesetzt. Eine Exception wird behandelt, wenn eine except- oder finally-Klausel oder eine with-Anweisung verwendet wird.

Dieser implizite Exception-Kontext kann durch die Verwendung von from zusammen mit raise um eine explizite Ursache ergänzt werden:

raise new_exc from original_exc

Der Ausdruck nach from muss eine Exception oder None sein. Er wird als __cause__ für die ausgelöste Exception gesetzt. Das Setzen von __cause__ setzt außerdem implizit das Attribut __suppress_context__ auf True, sodass die Verwendung von raise new_exc from None für Anzeigezwecke die alte Exception effektiv durch die neue ersetzt (z. B. bei der Umwandlung von KeyError in AttributeError), während die alte Exception für die Introspektion beim Debuggen weiterhin in __context__ verfügbar bleibt.

Die Standardausgabe des Tracebacks zeigt diese verketteten Exceptions zusätzlich zum Traceback der Exception selbst an. Eine explizit verkettete Exception in __cause__ wird immer angezeigt, sofern vorhanden. Eine implizit verkettete Exception in __context__ wird nur angezeigt, wenn __cause__ None und __suppress_context__ falsch ist.

In beiden Fällen wird die Exception selbst immer nach allen verketteten Exceptions angezeigt, sodass die letzte Zeile des Tracebacks immer die zuletzt ausgelöste Exception zeigt.

Erben von eingebauten Exceptions¶

Benutzercode kann Unterklassen erstellen, die von einem Exception-Typ erben. Es wird empfohlen, immer nur von einem Exception-Typ gleichzeitig zu erben, um mögliche Konflikte bei der Handhabung des args-Attributs durch die Basisklassen sowie Inkompatibilitäten beim Speicherlayout zu vermeiden.

Die meisten eingebauten Exceptions sind aus Effizienzgründen in C implementiert, siehe Objects/exceptions.c. Einige besitzen spezielle Speicherlayouts, die es unmöglich machen, eine Unterklasse zu erstellen, die von mehreren Exception-Typen erbt. Das Speicherlayout eines Typs ist ein Implementierungsdetail und kann sich zwischen Python-Versionen ändern, was künftig zu neuen Konflikten führen könnte. Daher wird empfohlen, das gleichzeitige Erben von mehreren Exception-Typen gänzlich zu vermeiden.

Basisklassen¶

Die folgenden Exceptions werden hauptsächlich als Basisklassen für andere Exceptions verwendet.

exception BaseException¶

Die Basisklasse für alle eingebauten Exceptions. Sie ist nicht dazu gedacht, direkt von benutzerdefinierten Klassen geerbt zu werden (verwende dafür Exception). Wird str() für eine Instanz dieser Klasse aufgerufen, wird die Darstellung der an die Instanz übergebenen Argumente zurückgegeben oder eine leere Zeichenkette, falls keine Argumente vorhanden waren.

args¶: Das Tupel der Argumente, die an den Exception-Konstruktor übergeben wurden. Einige eingebaute Exceptions (wie OSError) erwarten eine bestimmte Anzahl von Argumenten und weisen den Elementen dieses Tupels eine spezielle Bedeutung zu, während andere üblicherweise nur mit einer einzelnen Zeichenkette aufgerufen werden, die eine Fehlermeldung enthält.

with_traceback(tb)¶

Diese Methode setzt tb als neuen Traceback für die Exception und gibt das Exception-Objekt zurück. Sie wurde vor der Einführung der Exception-Verkettung aus PEP 3134 häufiger verwendet. Das folgende Beispiel zeigt, wie eine Instanz von SomeException unter Beibehaltung des Tracebacks in eine Instanz von OtherException umgewandelt werden kann. Sobald sie ausgelöst wird, wird der aktuelle Frame auf den Traceback von OtherException gelegt – genauso, wie es beim Traceback der ursprünglichen SomeException geschehen wäre, wenn sie an den Aufrufer weitergeleitet worden wäre.

try:
    ...
except SomeException:
    tb = sys.exception().__traceback__
    raise OtherException(...).with_traceback(tb)

__traceback__¶: Ein beschreibbares Feld, das das mit dieser Exception verknüpfte Traceback-Objekt enthält. Siehe auch Die raise Anweisung.

add_note(note)¶: Fügt die Zeichenkette note zu den Notizen der Exception hinzu, die im Standard-Traceback nach der Exception-Zeichenkette angezeigt werden. Es wird ein TypeError ausgelöst, wenn note keine Zeichenkette ist.

Added in version 3.11.

__notes__¶: Eine Liste der Notizen dieser Exception, die mit add_note() hinzugefügt wurden. Dieses Attribut wird erstellt, wenn add_note() aufgerufen wird.

Added in version 3.11.

exception Exception¶: Alle eingebauten Exceptions, die das System nicht beenden, sind von dieser Klasse abgeleitet. Alle benutzerdefinierten Exceptions sollten ebenfalls von dieser Klasse abgeleitet werden.

exception ArithmeticError¶: Die Basisklasse für diejenigen eingebauten Exceptions, die bei verschiedenen Rechenfehlern ausgelöst werden: OverflowError, ZeroDivisionError, FloatingPointError.

exception BufferError¶: Wird ausgelöst, wenn eine Operation im Zusammenhang mit einem Puffer nicht ausgeführt werden kann.

exception LookupError¶: Die Basisklasse für Exceptions, die ausgelöst werden, wenn ein für ein Mapping oder eine Sequenz verwendeter Schlüssel oder Index ungültig ist: IndexError, KeyError. Dies kann direkt von codecs.lookup() ausgelöst werden.

Konkrete Exceptions¶

Die folgenden Exceptions sind diejenigen, die üblicherweise ausgelöst werden.

exception AssertionError¶: Wird ausgelöst, wenn eine assert-Anweisung fehlschlägt.

exception AttributeError¶

Wird ausgelöst, wenn eine Attribut-Referenzierung (siehe Attributverweise) oder -Zuweisung fehlschlägt. (Wenn ein Objekt überhaupt keine Attribut-Referenzierungen oder -Zuweisungen unterstützt, wird ein TypeError ausgelöst.)

Die optionalen reinen Schlüsselwort-Argumente name und obj setzen die entsprechenden Attribute:

name¶: Der Name des Attributs, auf das zugegriffen werden sollte.

obj¶: Das Objekt, auf dessen genanntes Attribut zugegriffen wurde.

Geändert in Version 3.10: Die Attribute name und obj wurden hinzugefügt.

exception EOFError¶: Wird ausgelöst, wenn die Funktion input() eine End-of-File-Bedingung (EOF) erreicht, ohne Daten zu lesen. (Hinweis: Die Methoden io.TextIOBase.read() und io.IOBase.readline() geben eine leere Zeichenkette zurück, wenn sie auf EOF stoßen.)

exception FloatingPointError¶: Wird derzeit nicht verwendet.

exception GeneratorExit¶: Wird ausgelöst, wenn ein Generator oder eine Coroutine geschlossen wird; siehe generator.close() und coroutine.close(). Sie erbt direkt von BaseException statt von Exception, da es sich technisch gesehen um keinen Fehler handelt.

exception ImportError¶

Wird ausgelöst, wenn die import-Anweisung Probleme beim Laden eines Moduls hat. Wird auch ausgelöst, wenn die „from-Liste“ in from ... import einen Namen enthält, der nicht gefunden werden kann.

Die optionalen reinen Schlüsselwort-Argumente name und path setzen die entsprechenden Attribute:

name¶: Der Name des Moduls, das importiert werden sollte.

path¶: Der Pfad zu einer Datei, die die Exception ausgelöst hat.

Geändert in Version 3.3: Die Attribute name und path wurden hinzugefügt.

exception ModuleNotFoundError¶: Eine Unterklasse von ImportError, die von import ausgelöst wird, wenn ein Modul nicht gefunden werden konnte. Sie wird auch ausgelöst, wenn None in sys.modules vorgefunden wird.

Added in version 3.6.

exception IndexError¶: Wird ausgelöst, wenn ein Sequenzindex außerhalb des gültigen Bereichs liegt. (Slice-Indizes werden stillschweigend gekürzt, um in den zulässigen Bereich zu fallen; wenn ein Index keine Ganzzahl ist, wird ein TypeError ausgelöst.)

exception KeyError¶: Wird ausgelöst, wenn ein Mapping-Schlüssel (Dictionary-Schlüssel) nicht in der Menge der vorhandenen Schlüssel gefunden wird.

exception KeyboardInterrupt¶: Wird ausgelöst, wenn der Benutzer die Unterbrechungstaste drückt (normalerweise Control-C oder Delete). Während der Ausführung wird regelmäßig auf Unterbrechungen geprüft. Die Exception erbt von BaseException, damit sie nicht versehentlich von Code abgefangen wird, der Exception fängt, und so das Beenden des Interpreters verhindert.

Bemerkung

Das Abfangen eines KeyboardInterrupt erfordert besondere Vorsicht. Da er an unvorhersehbaren Stellen ausgelöst werden kann, kann er das laufende Programm unter Umständen in einem inkonsistenten Zustand hinterlassen. Es ist im Allgemeinen am besten, dem KeyboardInterrupt zu erlauben, das Programm so schnell wie möglich zu beenden, oder das Auslösen gänzlich zu vermeiden. (Siehe Note on Signal Handlers and Exceptions.)

exception MemoryError¶: Wird ausgelöst, wenn einer Operation der Speicher ausgeht, die Situation aber noch gerettet werden kann (durch Löschen einiger Objekte). Der zugehörige Wert ist eine Zeichenkette, die angibt, welcher Art von (interner) Operation der Speicher ausgegangen ist. Beachte, dass sich der Interpreter aufgrund der zugrunde liegenden Speicherverwaltungsarchitektur (C-Funktion malloc()) möglicherweise nicht immer vollständig von dieser Situation erholen kann; er löst dennoch eine Exception aus, damit ein Stack-Traceback ausgegeben werden kann, falls ein außer Kontrolle geratenes Programm die Ursache war.

exception NameError¶

Wird ausgelöst, wenn ein lokaler oder globaler Name nicht gefunden wird. Dies gilt nur für unqualifizierte Namen. Der zugehörige Wert ist eine Fehlermeldung, die den nicht auffindbaren Namen enthält.

Das optionale reine Schlüsselwort-Argument name setzt das Attribut:

name¶: Der Name der Variable, auf die zugegriffen werden sollte.

Geändert in Version 3.10: Das Attribut name wurde hinzugefügt.

exception NotImplementedError¶: Diese Exception ist von RuntimeError abgeleitet. In benutzerdefinierten Basisklassen sollten abstrakte Methoden diese Exception auslösen, wenn abgeleitete Klassen die Methode überschreiben müssen oder während die Klasse entwickelt wird, um anzuzeigen, dass die eigentliche Implementierung noch ergänzt werden muss.

Bemerkung

Sie sollte nicht verwendet werden, um anzuzeigen, dass ein Operator oder eine Methode überhaupt nicht unterstützt werden soll – belasse in diesem Fall den Operator bzw. die Methode entweder undefiniert oder setze sie in einer Unterklasse auf None.

Vorsicht

NotImplementedError und NotImplemented sind nicht austauschbar. Diese Exception sollte nur wie oben beschrieben verwendet werden; siehe NotImplemented für Details zur korrekten Verwendung der eingebauten Konstante.

exception OSError([arg])¶

exception OSError(errno, strerror[, filename[, winerror[, filename2]]])

Diese Exception wird ausgelöst, wenn eine Systemfunktion einen systembezogenen Fehler zurückgibt, einschließlich E/A-Fehlern wie „Datei nicht gefunden“ oder „Festplatte voll“ (nicht bei unzulässigen Argumenttypen oder anderen beiläufigen Fehlern).

Die zweite Form des Konstruktors setzt die entsprechenden, unten beschriebenen Attribute. Sofern nicht angegeben, sind die Attribute standardmäßig None. Aus Gründen der Abwärtskompatibilität enthält das Attribut args bei Übergabe von drei Argumenten nur ein 2-Tupel der ersten beiden Konstruktorargumente.

Der Konstruktor gibt häufig tatsächlich eine Unterklasse von OSError zurück, wie unten in OS exceptions beschrieben. Die jeweilige Unterklasse hängt vom endgültigen Wert von errno ab. Dieses Verhalten tritt nur auf, wenn OSError direkt oder über einen Alias konstruiert wird, und wird beim Erstellen von Unterklassen nicht vererbt.

errno¶: Ein numerischer Fehlercode aus der C-Variable errno.

winerror¶

Unter Windows liefert dies den nativen Windows-Fehlercode. Das Attribut errno ist dann eine ungefähre Übersetzung dieses nativen Fehlercodes in POSIX-Begriffe.

Wenn unter Windows das Konstruktorargument winerror eine Ganzzahl ist, wird das Attribut errno aus dem Windows-Fehlercode bestimmt und das Argument errno wird ignoriert. Auf anderen Plattformen wird das Argument winerror ignoriert und das Attribut winerror existiert nicht.

strerror¶: Die entsprechende Fehlermeldung, wie sie vom Betriebssystem bereitgestellt wird. Sie wird unter POSIX durch die C-Funktion perror() und unter Windows durch FormatMessage() formatiert.

filename¶
filename2¶: Bei Exceptions, die einen Dateisystempfad betreffen (wie open() oder os.unlink()), ist filename der an die Funktion übergebene Dateiname. Bei Funktionen, die zwei Dateisystempfade betreffen (wie os.rename()), entspricht filename2 dem zweiten an die Funktion übergebenen Dateinamen.

Geändert in Version 3.3: EnvironmentError, IOError, WindowsError, socket.error, select.error und mmap.error wurden in OSError zusammengeführt, und der Konstruktor kann eine Unterklasse zurückgeben.

Geändert in Version 3.4: Das Attribut filename ist nun der ursprüngliche, an die Funktion übergebene Dateiname anstelle des Namens, der in die oder aus der Dateisystem-Kodierung und der Fehlerbehandler kodiert oder dekodiert wurde. Zudem wurden das Konstruktorargument und das Attribut filename2 hinzugefügt.

exception OverflowError¶: Wird ausgelöst, wenn das Ergebnis einer arithmetischen Operation zu groß ist, um dargestellt zu werden. Dies kann bei Ganzzahlen nicht vorkommen (die eher einen MemoryError auslösen würden, als aufzugeben). Aus historischen Gründen wird OverflowError jedoch manchmal für Ganzzahlen ausgelöst, die außerhalb eines erforderlichen Bereichs liegen. Aufgrund der fehlenden Standardisierung der Behandlung von Gleitkomma-Exceptions in C werden die meisten Gleitkommaoperationen nicht überprüft.

exception PythonFinalizationError¶

Diese Exception ist von RuntimeError abgeleitet. Sie wird ausgelöst, wenn eine Operation während des Herunterfahrens des Interpreters blockiert wird, auch bekannt als Python-Finalisierung.

Beispiele für Operationen, die während der Python-Finalisierung mit einem PythonFinalizationError blockiert werden können:

Erstellen eines neuen Python-Threads.
os.fork().

Siehe auch die Funktion sys.is_finalizing().

Added in version 3.13: Zuvor wurde ein einfacher RuntimeError ausgelöst.

exception RecursionError¶: Diese Exception ist von RuntimeError abgeleitet. Sie wird ausgelöst, wenn der Interpreter feststellt, dass die maximale Rekursionstiefe (siehe sys.getrecursionlimit()) überschritten wurde.

Added in version 3.5: Zuvor wurde ein einfacher RuntimeError ausgelöst.

exception ReferenceError¶: Diese Exception wird ausgelöst, wenn ein von der Funktion weakref.proxy() erstellter Proxy für schwache Referenzen verwendet wird, um auf ein Attribut des Referenzobjekts zuzugreifen, nachdem dieses von der Garbage Collection bereinigt wurde. Weitere Informationen zu schwachen Referenzen findest du im Modul weakref.

exception RuntimeError¶: Wird ausgelöst, wenn ein Fehler erkannt wird, der in keine der anderen Kategorien fällt. Der zugehörige Wert ist eine Zeichenkette, die angibt, was genau schiefgelaufen ist.

exception StopIteration¶

Wird von der eingebauten Funktion next() und der Methode __next__() eines Iterators ausgelöst, um zu signalisieren, dass vom Iterator keine weiteren Elemente erzeugt werden.

value¶: Das Exception-Objekt besitzt ein einzelnes Attribut value, das bei der Konstruktion der Exception als Argument übergeben wird und standardmäßig None ist.

Wenn eine Generator- oder Coroutine-Funktion zurückkehrt, wird eine neue StopIteration-Instanz ausgelöst und der von der Funktion zurückgegebene Wert als value-Parameter an den Konstruktor der Exception übergeben.

Wenn Generatorcode direkt oder indirekt StopIteration auslöst, wird dies in einen RuntimeError umgewandelt (wobei die StopIteration als Ursache der neuen Exception beibehalten wird).

Geändert in Version 3.3: Das Attribut value und die Möglichkeit für Generatorfunktionen, damit einen Wert zurückzugeben, wurden hinzugefügt.

Geändert in Version 3.5: Die RuntimeError-Umwandlung über from __future__ import generator_stop wurde eingeführt, siehe PEP 479.

Geändert in Version 3.7: PEP 479 wurde standardmäßig für sämtlichen Code aktiviert: Ein in einem Generator ausgelöster StopIteration-Fehler wird in einen RuntimeError umgewandelt.

exception StopAsyncIteration¶: Muss von der Methode __anext__() eines asynchronen Iterators ausgelöst werden, um die Iteration zu stoppen.

Added in version 3.5.

exception SyntaxError(message, details)¶

Wird ausgelöst, wenn der Parser auf einen Syntaxfehler stößt. Dies kann in einer import-Anweisung, bei einem Aufruf der eingebauten Funktionen compile(), exec() oder eval() oder beim Einlesen des ursprünglichen Skripts bzw. der Standardeingabe (auch interaktiv) geschehen.

Der Aufruf von str() auf der Exception-Instanz gibt nur die Fehlermeldung zurück. Die Details sind ein Tupel, dessen Elemente auch als separate Attribute verfügbar sind.

filename¶: Der Name der Datei, in der der Syntaxfehler aufgetreten ist.

lineno¶: Die Zeilennummer in der Datei, in der der Fehler aufgetreten ist. Die Zählung beginnt bei 1: Die erste Zeile in der Datei hat die lineno 1.

offset¶: Die Spalte in der Zeile, in der der Fehler aufgetreten ist. Die Zählung beginnt bei 1: Das erste Zeichen in der Zeile hat den offset 1.

text¶: Der Quelltext, der an dem Fehler beteiligt war.

end_lineno¶: Die Zeilennummer in der Datei, in der der Fehler endet. Die Zählung beginnt bei 1: Die erste Zeile in der Datei hat die lineno 1.

end_offset¶: Die Spalte in der Endzeile, an der der Fehler endet. Die Zählung beginnt bei 1: Das erste Zeichen in der Zeile hat den offset 1.

Bei Fehlern in f-String-Feldern wird der Meldung „f-string: “ vorangestellt und die Offsets beziehen sich auf einen aus dem Ersetzungsausdruck konstruierten Text. Beispielsweise führt das Kompilieren von f’Bad {a b} field‘ zu folgendem args-Attribut: (‚f-string: …‘, (‚‘, 1, 2, ‚(a b)n‘, 1, 5)).

Geändert in Version 3.10: Die Attribute end_lineno und end_offset wurden hinzugefügt.

exception IndentationError¶: Basisklasse für Syntaxfehler im Zusammenhang mit fehlerhafter Einrückung. Dies ist eine Unterklasse von SyntaxError.

exception TabError¶: Wird ausgelöst, wenn die Einrückung eine uneinheitliche Verwendung von Tabs und Leerzeichen aufweist. Dies ist eine Unterklasse von IndentationError.

exception SystemError¶

Wird ausgelöst, wenn der Interpreter einen internen Fehler findet, die Situation jedoch nicht so gravierend erscheint, dass alle Hoffnung verloren ist. Der zugehörige Wert ist eine Zeichenkette, die (in systemnahen Begriffen) angibt, was schiefgelaufen ist. In CPython könnte dies durch die fehlerhafte Nutzung der C-API von Python ausgelöst werden, etwa durch die Rückgabe eines NULL-Wertes, ohne dass eine Exception gesetzt wurde.

Wenn du sicher bist, dass diese Exception nicht durch deinen eigenen Fehler oder den eines verwendeten Pakets verursacht wurde, solltest du dies dem Autor oder Betreuer deines Python-Interpreters melden. Achte darauf, die Version des Python-Interpreters anzugeben (sys.version; sie wird auch zu Beginn einer interaktiven Python-Sitzung ausgegeben), die genaue Fehlermeldung (den zugehörigen Wert der Exception) und nach Möglichkeit den Quelltext des Programms, das den Fehler ausgelöst hat.

exception SystemExit¶

Diese Exception wird von der Funktion sys.exit() ausgelöst. Sie erbt von BaseException anstelle von Exception, damit sie nicht versehentlich von Code abgefangen wird, der Exception behandelt. Dadurch kann die Exception sauber nach oben weitergereicht werden und das Beenden des Interpreters veranlassen. Wenn sie nicht behandelt wird, beendet sich der Python-Interpreter; es wird kein Stack-Traceback ausgegeben. Der Konstruktor akzeptiert dasselbe optionale Argument, das auch an sys.exit() übergeben wird. Wenn der Wert eine Ganzzahl ist, gibt er den System-Exit-Status an (übergeben an die C-Funktion exit()); ist er None, ist der Exit-Status null; hat er einen anderen Typ (z. B. eine Zeichenkette), wird der Wert des Objekts ausgegeben und der Exit-Status ist eins.

Ein Aufruf von sys.exit() wird in eine Exception umgewandelt, damit Bereinigungs-Handler (finally-Klauseln von try-Anweisungen) ausgeführt werden können und ein Debugger ein Skript ausführen kann, ohne Gefahr zu laufen, die Kontrolle zu verlieren. Die Funktion os._exit() kann verwendet werden, wenn ein sofortiges Beenden zwingend erforderlich ist (beispielsweise im Kindprozess nach einem Aufruf von os.fork()).

code¶: Der Exit-Status oder die Fehlermeldung, die an den Konstruktor übergeben wird. (Standardwert ist None.)

exception TypeError¶

Wird ausgelöst, wenn eine Operation oder Funktion auf ein Objekt eines unpassenden Typs angewendet wird. Der zugehörige Wert ist eine Zeichenkette, die Details über die Typabweichung enthält.

Diese Exception kann von Benutzercode ausgelöst werden, um anzuzeigen, dass eine versuchte Operation auf einem Objekt nicht unterstützt wird und auch nicht unterstützt werden soll. Wenn ein Objekt eine gegebene Operation unterstützen soll, dafür aber noch keine Implementierung bereitgestellt hat, ist NotImplementedError die passende Exception.

Die Übergabe von Argumenten des falschen Typs (z. B. die Übergabe einer list, wenn ein int erwartet wird) sollte zu einem TypeError führen, die Übergabe von Argumenten mit dem falschen Wert (z. B. eine Zahl außerhalb der erwarteten Grenzen) jedoch zu einem ValueError.

exception UnboundLocalError¶: Wird ausgelöst, wenn in einer Funktion oder Methode auf eine lokale Variable verwiesen wird, an diese Variable jedoch kein Wert gebunden ist. Dies ist eine Unterklasse von NameError.

exception UnicodeError¶

Wird ausgelöst, wenn ein Unicode-bezogener Kodierungs- oder Dekodierungsfehler auftritt. Dies ist eine Unterklasse von ValueError.

UnicodeError besitzt Attribute, die den Kodierungs- oder Dekodierungsfehler beschreiben. Beispielsweise liefert err.object[err.start:err.end] die konkrete ungültige Eingabe, an der der Codec gescheitert ist.

encoding¶: Der Name der Kodierung, die den Fehler ausgelöst hat.

reason¶: Eine Zeichenkette, die den spezifischen Codec-Fehler beschreibt.

object¶: Das Objekt, das der Codec zu kodieren oder dekodieren versuchte.

start¶: Der erste Index ungültiger Daten in object.

end¶: Der Index nach den letzten ungültigen Daten in object.

exception UnicodeEncodeError¶: Wird ausgelöst, wenn bei der Kodierung ein Unicode-bezogener Fehler auftritt. Dies ist eine Unterklasse von UnicodeError.

exception UnicodeDecodeError¶: Wird ausgelöst, wenn bei der Dekodierung ein Unicode-bezogener Fehler auftritt. Dies ist eine Unterklasse von UnicodeError.

exception UnicodeTranslateError¶: Wird ausgelöst, wenn bei der Übersetzung ein Unicode-bezogener Fehler auftritt. Dies ist eine Unterklasse von UnicodeError.

exception ValueError¶: Wird ausgelöst, wenn eine Operation oder Funktion ein Argument erhält, das zwar den richtigen Typ, aber einen unpassenden Wert besitzt, und die Situation nicht durch eine präzisere Exception wie IndexError beschrieben wird.

exception ZeroDivisionError¶: Wird ausgelöst, wenn das zweite Argument einer Divisions- oder Modulo-Operation null ist. Der zugehörige Wert ist eine Zeichenkette, die den Typ der Operanden und die Operation angibt.

Die folgenden Exceptions werden aus Kompatibilitätsgründen mit früheren Versionen beibehalten; ab Python 3.3 sind sie Aliase von OSError.

exception EnvironmentError¶

exception IOError¶

exception WindowsError¶: Nur unter Windows verfügbar.

OS-Exceptions¶

Die folgenden Exceptions sind Unterklassen von OSError; sie werden in Abhängigkeit vom Systemfehlercode ausgelöst.

exception BlockingIOError¶

Wird ausgelöst, wenn eine Operation auf einem Objekt (z. B. Socket) blockieren würde, das für den nicht-blockierenden Betrieb konfiguriert ist. Entspricht der errno EAGAIN, EALREADY, EWOULDBLOCK und EINPROGRESS.

Zusätzlich zu denen von OSError kann BlockingIOError ein weiteres Attribut besitzen:

characters_written¶: Eine Ganzzahl, die die Anzahl der Bytes enthält, die in den Stream geschrieben wurden, bevor er blockiert wurde. Dieses Attribut ist verfügbar, wenn die gepufferten I/O-Klassen aus dem Modul io verwendet werden.

exception ChildProcessError¶: Wird ausgelöst, wenn eine Operation auf einem Kindprozess fehlschlägt. Entspricht der errno ECHILD.

exception ConnectionError¶

Eine Basisklasse für verbindungsbezogene Probleme.

Unterklassen sind BrokenPipeError, ConnectionAbortedError, ConnectionRefusedError und ConnectionResetError.

exception BrokenPipeError¶: Eine Unterklasse von ConnectionError, die ausgelöst wird, wenn versucht wird, in eine Pipe zu schreiben, deren anderes Ende geschlossen wurde, oder in einen Socket zu schreiben, der für Schreibvorgänge heruntergefahren wurde. Entspricht der errno EPIPE und ESHUTDOWN.

exception ConnectionAbortedError¶: Eine Unterklasse von ConnectionError, die ausgelöst wird, wenn ein Verbindungsversuch von der Gegenstelle abgebrochen wird. Entspricht der errno ECONNABORTED.

exception ConnectionRefusedError¶: Eine Unterklasse von ConnectionError, die ausgelöst wird, wenn ein Verbindungsversuch von der Gegenstelle abgelehnt wird. Entspricht der errno ECONNREFUSED.

exception ConnectionResetError¶: Eine Unterklasse von ConnectionError, die ausgelöst wird, wenn eine Verbindung von der Gegenstelle zurückgesetzt wird. Entspricht der errno ECONNRESET.

exception FileExistsError¶: Wird ausgelöst, wenn versucht wird, eine Datei oder ein Verzeichnis zu erstellen, die bzw. das bereits existiert. Entspricht der errno EEXIST.

exception FileNotFoundError¶: Wird ausgelöst, wenn eine Datei oder ein Verzeichnis angefordert wird, aber nicht existiert. Entspricht der errno ENOENT.

exception InterruptedError¶: Wird ausgelöst, wenn ein Systemaufruf durch ein eingehendes Signal unterbrochen wird. Entspricht der errno EINTR.

Geändert in Version 3.5: Python wiederholt Systemaufrufe nun, wenn ein Aufruf durch ein Signal unterbrochen wird, es sei denn, der Signal-Handler löst eine Exception aus (siehe PEP 475 für die Begründung), anstatt InterruptedError auszulösen.

exception IsADirectoryError¶: Wird ausgelöst, wenn eine Dateioperation (wie os.remove()) auf ein Verzeichnis angewendet werden soll. Entspricht der errno EISDIR.

exception NotADirectoryError¶: Wird ausgelöst, wenn eine Verzeichnisoperation (wie os.listdir()) auf etwas angewendet werden soll, das kein Verzeichnis ist. Auf den meisten POSIX-Plattformen kann sie auch ausgelöst werden, wenn eine Operation versucht, eine Datei, die kein Verzeichnis ist, so zu öffnen oder zu durchlaufen, als wäre sie ein Verzeichnis. Entspricht der errno ENOTDIR.

exception PermissionError¶: Wird ausgelöst, wenn versucht wird, eine Operation ohne ausreichende Zugriffsrechte auszuführen – beispielsweise Dateisystemberechtigungen. Entspricht der errno EACCES, EPERM und ENOTCAPABLE.

Geändert in Version 3.11.1: ENOTCAPABLE von WASI ist nun auf PermissionError gemappt.

exception ProcessLookupError¶: Wird ausgelöst, wenn ein angegebener Prozess nicht existiert. Entspricht der errno ESRCH.

exception TimeoutError¶: Wird ausgelöst, wenn eine Systemfunktion auf Systemebene eine Zeitüberschreitung erlitten hat. Entspricht der errno ETIMEDOUT.

Added in version 3.3: Alle oben genannten OSError-Unterklassen wurden hinzugefügt.

Siehe auch

PEP 3151 – Überarbeitung der OS- und IO-Exception-Hierarchie

Warnungen¶

Die folgenden Exceptions werden als Warnungskategorien verwendet; siehe die Dokumentation zu Warning Categories für weitere Details.

exception Warning¶: Basisklasse für Warnungskategorien.

exception UserWarning¶: Basisklasse für von Benutzercode erzeugte Warnungen.

exception DeprecationWarning¶

Basisklasse für Warnungen über veraltete Features, wenn diese Warnungen für andere Python-Entwickler bestimmt sind.

Wird von den Standard-Warnfiltern ignoriert, außer im __main__-Modul (PEP 565). Die Aktivierung des Python-Entwicklungsmodus zeigt diese Warnung an.

Die Richtlinie für veraltete Funktionen wird in PEP 387 beschrieben.

exception PendingDeprecationWarning¶

Basisklasse für Warnungen über Funktionen, die obsolet sind und von denen erwartet wird, dass sie in Zukunft als veraltet markiert werden, es derzeit jedoch noch nicht sind.

Diese Klasse wird selten verwendet, da die Ausgabe einer Warnung vor einer möglichen künftigen Veraltung unüblich ist; für bereits aktive Veraltungen wird DeprecationWarning bevorzugt.

Wird von den Standard-Warnfiltern ignoriert. Die Aktivierung des Python-Entwicklungsmodus zeigt diese Warnung an.

Die Richtlinie für veraltete Funktionen wird in PEP 387 beschrieben.

exception SyntaxWarning¶

Basisklasse für Warnungen bezüglich zweifelhafter Syntax.

Diese Warnung wird typischerweise beim Kompilieren von Python-Quelltext ausgegeben und tritt beim Ausführen von bereits kompiliertem Code üblicherweise nicht auf.

exception RuntimeWarning¶: Basisklasse für Warnungen bezüglich zweifelhaften Laufzeitverhaltens.

exception FutureWarning¶: Basisklasse für Warnungen über veraltete Features, wenn diese Warnungen für Endbenutzer von in Python geschriebenen Anwendungen bestimmt sind.

exception ImportWarning¶

Basisklasse für Warnungen vor wahrscheinlichen Fehlern bei Modulimporten.

Wird von den Standard-Warnfiltern ignoriert. Die Aktivierung des Python-Entwicklungsmodus zeigt diese Warnung an.

exception UnicodeWarning¶: Basisklasse für Warnungen im Zusammenhang mit Unicode.

exception EncodingWarning¶

Basisklasse für Warnungen im Zusammenhang mit Kodierungen.

Siehe Opt-in EncodingWarning für Details.

Added in version 3.10.

exception BytesWarning¶: Basisklasse für Warnungen im Zusammenhang mit bytes und bytearray.

exception ResourceWarning¶

Basisklasse für Warnungen im Zusammenhang mit der Ressourcennutzung.

Wird von den Standard-Warnfiltern ignoriert. Die Aktivierung des Python-Entwicklungsmodus zeigt diese Warnung an.

Added in version 3.2.

Exception-Gruppen¶

Die folgenden Klassen werden verwendet, wenn mehrere voneinander unabhängige Exceptions ausgelöst werden müssen. Sie sind Teil der Exception-Hierarchie, sodass sie wie alle anderen Exceptions mit except behandelt werden können. Zudem werden sie von except* erkannt, was ihre Untergruppen anhand der Typen der enthaltenen Exceptions abgleicht.

exception ExceptionGroup(msg, excs)¶

exception BaseExceptionGroup(msg, excs)¶

Beide Exception-Typen kapseln die Exceptions in der Sequenz excs. Der Parameter msg muss eine Zeichenkette sein. Der Unterschied zwischen den beiden Klassen besteht darin, dass BaseExceptionGroup BaseException erweitert und jede Exception kapseln kann, während ExceptionGroup Exception erweitert und nur Unterklassen von Exception kapseln kann. Dieser Entwurf sorgt dafür, dass except Exception eine ExceptionGroup abfängt, nicht jedoch BaseExceptionGroup.

Der Konstruktor von BaseExceptionGroup gibt eine ExceptionGroup statt einer BaseExceptionGroup zurück, wenn alle enthaltenen Exceptions Instanzen von Exception sind; er kann daher verwendet werden, um die Auswahl automatisch zu treffen. Der Konstruktor von ExceptionGroup hingegen löst einen TypeError aus, wenn eine enthaltene Exception keine Unterklasse von Exception ist.

Exception-Gruppen sind hinsichtlich des Typs ihrer enthaltenen Ausnahmen generisch.

Der Parameter excs kann eine beliebige Sequenz sein, wobei Listen und Tupel hier speziell effizienter verarbeitet werden. Für optimale Leistung übergib excs als Tupel.

message¶: Das Argument msg an den Konstruktor. Dies ist ein schreibgeschütztes Attribut.

exceptions¶: Ein Tupel der Exceptions in der Sequenz excs, die an den Konstruktor übergeben wurde. Dies ist ein schreibgeschütztes Attribut.

subgroup(condition)¶

Gibt eine Exception-Gruppe zurück, die nur diejenigen Exceptions der aktuellen Gruppe enthält, die auf condition zutreffen, oder None, wenn das Ergebnis leer ist.

Die Bedingung kann ein Exception-Typ oder ein Tupel von Exception-Typen sein; in diesem Fall wird jede Exception anhand derselben Prüfung auf Übereinstimmung getestet, die in einer except-Klausel verwendet wird. Die Bedingung kann auch ein Aufrufobjekt (außer einem Typobjekt) sein, das eine Exception als einziges Argument akzeptiert und für diejenigen Exceptions True zurückgibt, die in der Untergruppe enthalten sein sollen.

Die Verschachtelung der aktuellen Exception bleibt im Ergebnis erhalten, ebenso wie die Werte der Felder message, __traceback__, __cause__, __context__ und __notes__. Leere verschachtelte Gruppen werden im Ergebnis weggelassen.

Die Bedingung wird für alle Exceptions in der geschachtelten Exception-Gruppe geprüft, einschließlich der obersten Ebene und aller geschachtelten Exception-Gruppen. Wenn die Bedingung für eine solche Exception-Gruppe wahr ist, wird sie vollständig in das Ergebnis aufgenommen.

Added in version 3.13: condition kann jedes aufrufbare Objekt sein, das kein Typobjekt ist.

split(condition)¶: Wie subgroup(), gibt jedoch das Paar (match, rest) zurück, wobei match subgroup(condition) entspricht und rest der verbleibende, nicht übereinstimmende Teil ist.

derive(excs)¶

Gibt eine Exception-Gruppe mit derselben message zurück, die jedoch die Exceptions in excs kapselt.

Diese Methode wird von subgroup() und split() verwendet, die in verschiedenen Kontexten zum Aufteilen einer Exception-Gruppe dienen. Eine Unterklasse muss diese Methode überschreiben, damit subgroup() und split() Instanzen der Unterklasse anstelle von ExceptionGroup zurückgeben.

subgroup() und split() kopieren die Felder __traceback__, __cause__, __context__ und __notes__ von der ursprünglichen Exception-Gruppe in die von derive() zurückgegebene Gruppe, sodass diese Felder nicht von derive() aktualisiert werden müssen.

>>> class MyGroup(ExceptionGroup):
...     def derive(self, excs):
...         return MyGroup(self.message, excs)
...
>>> e = MyGroup("eg", [ValueError(1), TypeError(2)])
>>> e.add_note("a note")
>>> e.__context__ = Exception("context")
>>> e.__cause__ = Exception("cause")
>>> try:
...    raise e
... except Exception as e:
...    exc = e
...
>>> match, rest = exc.split(ValueError)
>>> exc, exc.__context__, exc.__cause__, exc.__notes__
(MyGroup('eg', [ValueError(1), TypeError(2)]), Exception('context'), Exception('cause'), ['a note'])
>>> match, match.__context__, match.__cause__, match.__notes__
(MyGroup('eg', [ValueError(1)]), Exception('context'), Exception('cause'), ['a note'])
>>> rest, rest.__context__, rest.__cause__, rest.__notes__
(MyGroup('eg', [TypeError(2)]), Exception('context'), Exception('cause'), ['a note'])
>>> exc.__traceback__ is match.__traceback__ is rest.__traceback__
True

Beachte, dass BaseExceptionGroup __new__() definiert; Unterklassen, die eine abweichende Konstruktor-Signatur benötigen, müssen daher diese Methode anstelle von __init__() überschreiben. Das folgende Beispiel definiert etwa eine Exception-Gruppen-Unterklasse, die einen exit_code entgegennimmt und daraus die Nachricht der Gruppe konstruiert:

class Errors(ExceptionGroup):
   def __new__(cls, errors, exit_code):
      self = super().__new__(Errors, f"exit code: {exit_code}", errors)
      self.exit_code = exit_code
      return self

   def derive(self, excs):
      return Errors(excs, self.exit_code)

Wie ExceptionGroup kann jede Unterklasse von BaseExceptionGroup, die zugleich eine Unterklasse von Exception ist, nur Instanzen von Exception kapseln.

Added in version 3.11.

Exception-Hierarchie¶

Die Klassenhierarchie für eingebaute Exceptions ist:

BaseException
 ├── BaseExceptionGroup
 ├── GeneratorExit
 ├── KeyboardInterrupt
 ├── SystemExit
 └── Exception
      ├── ArithmeticError
      │    ├── FloatingPointError
      │    ├── OverflowError
      │    └── ZeroDivisionError
      ├── AssertionError
      ├── AttributeError
      ├── BufferError
      ├── EOFError
      ├── ExceptionGroup [BaseExceptionGroup]
      ├── ImportError
      │    └── ModuleNotFoundError
      ├── LookupError
      │    ├── IndexError
      │    └── KeyError
      ├── MemoryError
      ├── NameError
      │    └── UnboundLocalError
      ├── OSError
      │    ├── BlockingIOError
      │    ├── ChildProcessError
      │    ├── ConnectionError
      │    │    ├── BrokenPipeError
      │    │    ├── ConnectionAbortedError
      │    │    ├── ConnectionRefusedError
      │    │    └── ConnectionResetError
      │    ├── FileExistsError
      │    ├── FileNotFoundError
      │    ├── InterruptedError
      │    ├── IsADirectoryError
      │    ├── NotADirectoryError
      │    ├── PermissionError
      │    ├── ProcessLookupError
      │    └── TimeoutError
      ├── ReferenceError
      ├── RuntimeError
      │    ├── NotImplementedError
      │    ├── PythonFinalizationError
      │    └── RecursionError
      ├── StopAsyncIteration
      ├── StopIteration
      ├── SyntaxError
      │    └── IndentationError
      │         └── TabError
      ├── SystemError
      ├── TypeError
      ├── ValueError
      │    └── UnicodeError
      │         ├── UnicodeDecodeError
      │         ├── UnicodeEncodeError
      │         └── UnicodeTranslateError
      └── Warning
           ├── BytesWarning
           ├── DeprecationWarning
           ├── EncodingWarning
           ├── FutureWarning
           ├── ImportWarning
           ├── PendingDeprecationWarning
           ├── ResourceWarning
           ├── RuntimeWarning
           ├── SyntaxWarning
           ├── UnicodeWarning
           └── UserWarning

Eingebaute Exceptions¶

Exception-Kontext¶

Erben von eingebauten Exceptions¶

Basisklassen¶

Konkrete Exceptions¶

OS-Exceptions¶

Warnungen¶

Exception-Gruppen¶

Exception-Hierarchie¶

Inhaltsverzeichnis

Vorheriges Thema

Nächstes Thema

Diese Seite