Eingebaute Ausnahmen

In Python müssen alle Ausnahmen Instanzen einer Klasse sein, die von BaseException abgeleitet ist. In einer try-Anweisung mit einer except-Klausel, die eine bestimmte Klasse erwähnt, behandelt diese Klausel auch alle abgeleiteten Ausnahmeklassen (aber nicht die Ausnahmeklassen, von denen *sie* abgeleitet ist). Zwei Ausnahmeklassen, die nicht durch Unterklassenbildung miteinander verbunden sind, sind niemals gleichwertig, auch wenn sie den gleichen Namen haben.

Die in diesem Kapitel aufgeführten eingebauten Ausnahmen können vom Interpreter oder von eingebauten Funktionen ausgelöst werden. Sofern nicht anders angegeben, haben sie einen „zugehörigen Wert“, der die detaillierte Ursache des Fehlers angibt. Dies kann ein String oder ein Tupel aus mehreren Informationsstücken sein (z. B. ein Fehlercode und ein String, der den Code erklärt). Der zugehörige Wert wird normalerweise als Argument an den Konstruktor der Ausnahmeklasse übergeben.

Benutzercode kann eingebaute Ausnahmen auslösen. Dies kann verwendet werden, um einen Ausnahmehandler zu testen oder um eine Fehlerbedingung zu melden, „genauso“ wie die Situation, in der der Interpreter die gleiche Ausnahme auslöst; aber Vorsicht: Es gibt nichts, was Benutzercode daran hindert, eine unangemessene Ausnahme auszulösen.

Die eingebauten Ausnahmeklassen können unterklassenbildend für neue Ausnahmen definiert werden; Programmierer werden ermutigt, neue Ausnahmen von der Klasse Exception oder einer ihrer Unterklassen abzuleiten und nicht von BaseException. Weitere Informationen zur Definition von Ausnahmen finden Sie im Python-Tutorial unter Benutzerdefinierte Ausnahmen.

Ausnahmekontext

Drei Attribute von Ausnahmeobjekten liefern Informationen über den Kontext, in dem die Ausnahme ausgelöst wurde

BaseException.__context__

BaseException.__cause__

BaseException.__suppress_context__

Beim Auslösen einer neuen Ausnahme, während eine andere Ausnahme bereits behandelt wird, wird das Attribut __context__ der neuen Ausnahme automatisch auf die behandelte Ausnahme gesetzt. Eine Ausnahme kann behandelt werden, wenn eine except- oder finally-Klausel oder eine with-Anweisung verwendet wird.

Dieser implizite Ausnahmekontext kann mit einer expliziten Ursache ergänzt werden, indem from mit raise verwendet wird

raise new_exc from original_exc

Der Ausdruck nach from muss eine Ausnahme oder None sein. Er wird als __cause__ auf der ausgelösten Ausnahme gesetzt. Das Setzen von __cause__ setzt auch implizit das Attribut __suppress_context__ auf True, sodass die Verwendung von raise new_exc from None effektiv die alte Ausnahme durch die neue für Anzeigezwecke ersetzt (z. B. KeyError in AttributeError konvertiert), während die alte Ausnahme zur Introspektion beim Debugging in __context__ verfügbar bleibt.

Der Standard-Traceback-Anzeigecode zeigt diese verketteten Ausnahmen zusätzlich zum Traceback der Ausnahme selbst an. Eine explizit verkettete Ausnahme in __cause__ wird immer angezeigt, wenn vorhanden. Eine implizit verkettete Ausnahme in __context__ wird nur angezeigt, wenn __cause__ None ist und __suppress_context__ falsch ist.

In beiden Fällen wird die Ausnahme selbst immer nach den verketteten Ausnahmen angezeigt, sodass die letzte Zeile des Tracebacks immer die letzte ausgelöste Ausnahme anzeigt.

Erben von eingebauten Ausnahmen

Benutzercode kann Unterklassen erstellen, die von einem Ausnahmetyp erben. Es wird empfohlen, nur jeweils einen Ausnahmetyp zu unterklassen, um mögliche Konflikte zwischen der Handhabung des args-Attributs durch die Basisklassen zu vermeiden, sowie aufgrund möglicher Inkompatibilitäten im Speicherlayout.

CPython-Implementierungsdetail: Die meisten eingebauten Ausnahmen werden zur Effizienz in C implementiert, siehe: Objects/exceptions.c. Einige haben benutzerdefinierte Speicherlayouts, die es unmöglich machen, eine Unterklasse zu erstellen, die von mehreren Ausnahmetypen erbt. Das Speicherlayout eines Typs ist ein Implementierungsdetail und kann sich zwischen Python-Versionen ändern, was in Zukunft zu neuen Konflikten führen kann. Daher wird empfohlen, das Unterklassenbilden mehrerer Ausnahmetypen gänzlich zu vermeiden.

Basisklassen

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

exception BaseException

Die Basisklasse für alle eingebauten Ausnahmen. Sie ist nicht dazu gedacht, direkt von benutzerdefinierten Klassen abgeleitet zu werden (dafür verwenden Sie Exception). Wenn str() auf eine Instanz dieser Klasse angewendet wird, werden die Repräsentationen der Argumente der Instanz oder ein leerer String zurückgegeben, wenn keine Argumente vorhanden waren.

args

Das Tupel der Argumente, die an den Ausnahmekonstruktor übergeben wurden. Einige eingebaute Ausnahmen (wie OSError) erwarten eine bestimmte Anzahl von Argumenten und weisen den Elementen dieses Tupels eine besondere Bedeutung zu, während andere normalerweise nur mit einem einzigen String aufgerufen werden, der eine Fehlermeldung liefert.

with_traceback(tb)

Diese Methode setzt tb als neuen Traceback für die Ausnahme und gibt das Ausnahmeobjekt zurück. Sie wurde vor der Verfügbarkeit der Ausnahmeverkettungsfunktionen von PEP 3134 häufiger verwendet. Das folgende Beispiel zeigt, wie eine Instanz von SomeException in eine Instanz von OtherException konvertiert werden kann, wobei der Traceback erhalten bleibt. Nach dem Auslösen wird der aktuelle Frame auf den Traceback von OtherException gelegt, wie es auch mit dem Traceback der ursprünglichen SomeException passiert wäre, wenn wir sie an den Aufrufer weitergegeben hätten.

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

__traceback__

Ein schreibbares Feld, das das Traceback-Objekt enthält, das mit dieser Ausnahme verknüpft ist. Siehe auch: Die raise-Anweisung.

add_note(note)

Fügt den String note zu den Notizen der Ausnahme hinzu, die im Standard-Traceback nach der Fehlermeldung erscheinen. Ein TypeError wird ausgelöst, wenn note kein String ist.

Hinzugefügt in Version 3.11.

__notes__

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

Hinzugefügt in Version 3.11.

exception Exception

Alle eingebauten, nicht systembeendenden Ausnahmen sind von dieser Klasse abgeleitet. Alle benutzerdefinierten Ausnahmen sollten ebenfalls von dieser Klasse abgeleitet sein.

exception ArithmeticError

Die Basisklasse für die eingebauten Ausnahmen, die für verschiedene arithmetische Fehler ausgelöst werden: OverflowError, ZeroDivisionError, FloatingPointError.

exception BufferError

Wird ausgelöst, wenn eine Puffer-bezogene Operation (Puffer) nicht durchgeführt werden kann.

exception LookupError

Die Basisklasse für die Ausnahmen, die ausgelöst werden, wenn ein Schlüssel oder Index, der in einer Zuordnung (Mapping) oder Sequenz verwendet wird, ungültig ist: IndexError, KeyError. Dies kann direkt von codecs.lookup() ausgelöst werden.

Konkrete Ausnahmen

Die folgenden Ausnahmen sind die Ausnahmen, die normalerweise ausgelöst werden.

exception AssertionError

Wird ausgelöst, wenn eine assert-Anweisung fehlschlägt.

exception AttributeError

Wird ausgelöst, wenn ein Attributverweis (siehe Attributreferenzen) oder eine Attributzuweisung fehlschlägt. (Wenn ein Objekt Attributverweise oder Attributzuweisungen überhaupt nicht unterstützt, wird TypeError ausgelöst.)

Die optionalen Schlüsselwortargumente name und obj setzen die entsprechenden Attribute

name

Der Name des Attributs, auf das zugegriffen wurde.

obj

Das Objekt, auf das für das benannte Attribut zugegriffen wurde.

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

exception EOFError

Wird ausgelöst, wenn die Funktion input() auf eine End-of-File-Bedingung (EOF) trifft, ohne Daten gelesen zu haben. (Hinweis: Die Methoden io.IOBase.read() und io.IOBase.readline() geben einen leeren String zurück, wenn sie EOF erreichen.)

exception FloatingPointError

Derzeit nicht verwendet.

exception GeneratorExit

Wird ausgelöst, wenn ein Generator oder Coroutine geschlossen wird; siehe generator.close() und coroutine.close(). Sie erbt direkt von BaseException anstatt von Exception, da sie technisch gesehen kein Fehler ist.

exception ImportError

Wird ausgelöst, wenn die import-Anweisung Probleme beim Laden eines Moduls hat. Wird auch ausgelöst, wenn in der „from list“ von from ... import ein Name nicht gefunden werden kann.

Die optionalen Schlüsselwortargumente name und path setzen die entsprechenden Attribute

name

Der Name des Moduls, das importiert werden sollte.

path

Der Pfad zu jeder Datei, die die Ausnahme ausgelöst hat.

Geändert in Version 3.3: Attribute name und path 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 gefunden wird.

Hinzugefügt in Version 3.6.

exception IndexError

Wird ausgelöst, wenn ein Sequenz-Subskript außerhalb des gültigen Bereichs liegt. (Slice-Indizes werden stillschweigend auf den zulässigen Bereich zugeschnitten; wenn ein Index keine Ganzzahl ist, wird TypeError ausgelöst.)

exception KeyError

Wird ausgelöst, wenn ein Schlüssel einer Zuordnung (Dictionary) 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 Ausnahme erbt von BaseException, damit sie nicht versehentlich von Code abgefangen wird, der Exception abfängt und somit verhindert, dass der Interpreter beendet wird.

Hinweis

Das Abfangen einer KeyboardInterrupt erfordert besondere Überlegungen. Da sie an unvorhersehbaren Stellen ausgelöst werden kann, kann sie das laufende Programm unter Umständen in einem inkonsistenten Zustand hinterlassen. Es ist im Allgemeinen am besten, KeyboardInterrupt so schnell wie möglich das Programm beenden zu lassen oder ganz zu vermeiden. (Siehe Hinweis zu Signalhandlern und Ausnahmen.)

exception MemoryError

Wird ausgelöst, wenn eine Operation keinen Speicher mehr hat, die Situation aber noch gerettet werden kann (durch Löschen einiger Objekte). Der zugehörige Wert ist ein String, der angibt, welche Art von (interner) Operation den Speicher aufgebraucht hat. Beachten Sie, dass der Interpreter aufgrund der zugrunde liegenden Speicherverwaltung (C's malloc()-Funktion) diese Situation möglicherweise nicht immer vollständig beheben kann; er löst dennoch eine Ausnahme aus, damit ein Stack-Traceback gedruckt 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 nicht qualifizierte Namen. Der zugehörige Wert ist eine Fehlermeldung, die den nicht gefundenen Namen enthält.

Das optionale Schlüsselwortargument name setzt das Attribut

name

Der Name der Variablen, auf die zugegriffen werden sollte.

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

exception NotImplementedError

Diese Ausnahme ist von RuntimeError abgeleitet. In benutzerdefinierten Basisklassen sollten abstrakte Methoden diese Ausnahme auslösen, wenn sie abgeleitete Klassen zwingen, die Methode zu überschreiben, oder während der Entwicklung der Klasse, um anzuzeigen, dass die tatsächliche Implementierung noch hinzugefügt werden muss.

Hinweis

Sie sollte nicht verwendet werden, um anzuzeigen, dass ein Operator oder eine Methode überhaupt nicht unterstützt werden soll – hinterlassen Sie in diesem Fall entweder den Operator/die Methode undefiniert oder, wenn es sich um eine Unterklasse handelt, setzen Sie sie auf None.

Vorsicht

NotImplementedError und NotImplemented sind nicht austauschbar. Diese Ausnahme 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 Ausnahme wird ausgelöst, wenn eine Systemfunktion einen systembezogenen Fehler zurückgibt, einschließlich E/A-Fehlern wie „Datei nicht gefunden“ oder „Festplatte voll“ (nicht für ungültige Argumenttypen oder andere zufällige Fehler).

Die zweite Form des Konstruktors setzt die entsprechenden Attribute, die unten beschrieben sind. Die Attribute sind standardmäßig None, wenn nicht angegeben. Aus Kompatibilitätsgründen enthält das Attribut args nur ein 2-Tupel der ersten beiden Konstruktorargumente, wenn drei Argumente übergeben werden.

Der Konstruktor gibt oft tatsächlich eine Unterklasse von OSError zurück, wie in Betriebssystem-Ausnahmen weiter unten beschrieben. Die spezifische Unterklasse hängt vom endgültigen errno-Wert ab. Dieses Verhalten tritt nur beim direkten Erstellen von OSError oder über einen Alias auf und wird beim Unterklassenbilden nicht vererbt.

errno

Ein numerischer Fehlercode aus der C-Variable errno.

winerror

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

Unter Windows wird, wenn das Konstruktorargument winerror eine Ganzzahl ist, das Attribut errno aus dem Windows-Fehlercode ermittelt, 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 von den C-Funktionen perror() unter POSIX und FormatMessage() unter Windows formatiert.

filename

filename2

Für Ausnahmen, die einen Dateisystempfad betreffen (wie z. B. open() oder os.unlink()), ist filename der an die Funktion übergebene Dateiname. Für Funktionen, die zwei Dateisystempfade betreffen (wie z. B. 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 Dateiname, der an die Funktion übergeben wurde, anstatt des Namens, der in die Dateisystemkodierung und Fehlerbehandlung kodiert oder daraus dekodiert wurde. Außerdem wurde das Konstruktorargument und 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 auftreten (die eher 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 mangelnder Standardisierung der Gleitkomma-Ausnahmebehandlung in C werden die meisten Gleitkommaoperationen nicht überprüft.

exception PythonFinalizationError

Diese Ausnahme ist von RuntimeError abgeleitet. Sie wird ausgelöst, wenn eine Operation während der Interpreterbeendigung, auch bekannt als Python-Finalisierung, blockiert wird.

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

• Erstellung eines neuen Python-Threads.

• Joining eines laufenden Daemon-Threads.

• os.fork().

Siehe auch die Funktion sys.is_finalizing().

Hinzugefügt in Version 3.13: Zuvor wurde ein einfacher RuntimeError ausgelöst.

Geändert in Version 3.14: threading.Thread.join() kann nun diese Ausnahme auslösen.

exception RecursionError

Diese Ausnahme ist von RuntimeError abgeleitet. Sie wird ausgelöst, wenn der Interpreter feststellt, dass die maximale Rekursionstiefe (siehe sys.getrecursionlimit()) überschritten wird.

Hinzugefügt in Version 3.5: Zuvor wurde ein einfacher RuntimeError ausgelöst.

exception ReferenceError

Diese Ausnahme wird ausgelöst, wenn ein schwacher Referenz-Proxy, der von der Funktion weakref.proxy() erstellt wurde, verwendet wird, um auf ein Attribut des referenzierten Objekts zuzugreifen, nachdem dieses vom Garbage Collector aufgeräumt wurde. Weitere Informationen zu schwachen Referenzen finden Sie im Modul weakref.

exception RuntimeError

Wird ausgelöst, wenn ein Fehler erkannt wird, der in keine andere Kategorie fällt. Der zugehörige Wert ist eine Zeichenkette, die angibt, was genau schief gelaufen ist.

exception StopIteration

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

value

Das Ausnahmeobjekt hat ein einzelnes Attribut value, das beim Erstellen der Ausnahme als Argument übergeben wird und standardmäßig None ist.

Wenn eine Generatorfunktion oder Coroutinenfunktion zurückkehrt, wird eine neue StopIteration-Instanz ausgelöst und der von der Funktion zurückgegebene Wert wird als Parameter value für den Konstruktor der Ausnahme verwendet.

Wenn ein Generator-Code direkt oder indirekt StopIteration auslöst, wird diese in einen RuntimeError umgewandelt (wobei StopIteration als Ursache der neuen Ausnahme beibehalten wird).

Geändert in Version 3.3: Attribut value und die Möglichkeit für Generatorfunktionen, es zur Rückgabe eines Wertes zu verwenden, hinzugefügt.

Geändert in Version 3.5: Einführung der RuntimeError-Transformation über from __future__ import generator_stop, siehe PEP 479.

Geändert in Version 3.7: PEP 479 standardmäßig für allen Code aktiviert: eine in einem Generator ausgelöste StopIteration-Ausnahme wird in einen RuntimeError umgewandelt.

exception StopAsyncIteration

Muss von der Methode __anext__() eines asynchronen Iterators ausgelöst werden, um die Iteration zu beenden.

Hinzugefügt in Version 3.5.

exception SyntaxError(message, details)

Wird ausgelöst, wenn der Parser auf einen Syntaxfehler stößt. Dies kann bei einer import-Anweisung, bei einem Aufruf der eingebauten Funktionen compile(), exec() oder eval() oder beim Lesen des initialen Skripts oder der Standardeingabe (auch interaktiv) auftreten.

Die str()-Darstellung der Ausnahmeinstanz gibt nur die Fehlermeldung zurück. Details ist ein Tupel, dessen Elemente auch als separate Attribute verfügbar sind.

filename

Der Name der Datei, in der der Syntaxfehler aufgetreten ist.

lineno

Welche Zeilennummer in der Datei der Fehler aufgetreten ist. Diese ist 1-basiert: Die erste Zeile in der Datei hat eine lineno von 1.

offset

Die Spalte in der Zeile, in der der Fehler aufgetreten ist. Diese ist 1-basiert: Das erste Zeichen in der Zeile hat einen offset von 1.

text

Der Quellcode-Text, der vom Fehler betroffen ist.

end_lineno

Welche Zeilennummer in der Datei der Fehler endet. Diese ist 1-basiert: Die erste Zeile in der Datei hat eine lineno von 1.

end_offset

Die Spalte in der Endzeile, in der der Fehler endet. Diese ist 1-basiert: Das erste Zeichen in der Zeile hat einen offset von 1.

Bei Fehlern in f-String-Feldern wird die Nachricht mit "f-string: " präfixiert, und die Offsets sind Offsets in einem Text, der aus dem Ersetzungs-Ausdruck konstruiert wurde. Zum Beispiel führt das Kompilieren von f'Bad {a b} field' zu folgenden Args-Attributen: ('f-string: ...', ('', 1, 2, '(a b)n', 1, 5)).

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

exception IndentationError

Basisklasse für Syntaxfehler, die mit falscher Einrückung zusammenhängen. Dies ist eine Unterklasse von SyntaxError.

exception TabError

Wird ausgelöst, wenn die Einrückung eine inkonsistente Verwendung von Tabs und Leerzeichen enthält. Dies ist eine Unterklasse von IndentationError.

exception SystemError

Wird ausgelöst, wenn der Interpreter einen internen Fehler feststellt, die Situation aber nicht so ernst ist, dass er alle Hoffnungen aufgibt. Der zugehörige Wert ist eine Zeichenkette, die angibt, was schief gelaufen ist (auf Low-Level-Basis). In CPython kann dies durch unsachgemäße Verwendung der C-API von Python ausgelöst werden, z.B. durch Rückgabe eines NULL-Wertes, ohne dass eine Ausnahme gesetzt ist.

Wenn Sie sicher sind, dass diese Ausnahme nicht Ihre Schuld war oder die Schuld eines von Ihnen verwendeten Pakets war, sollten Sie dies dem Autor oder Maintainer Ihres Python-Interpreters melden. Stellen Sie sicher, dass Sie die Version des Python-Interpreters (sys.version; sie wird auch zu Beginn einer interaktiven Python-Sitzung ausgegeben), die genaue Fehlermeldung (der zugehörige Wert der Ausnahme) und, wenn möglich, die Quelle des Programms, das den Fehler ausgelöst hat, melden.

exception SystemExit

Diese Ausnahme 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 abfängt. Dies ermöglicht es der Ausnahme, ordnungsgemäß nach oben zu propagieren und den Interpreter zum Beenden zu veranlassen. Wenn sie nicht behandelt wird, beendet sich der Python-Interpreter; es wird kein Stack-Traceback ausgegeben. Der Konstruktor akzeptiert das gleiche optionale Argument, das an sys.exit() übergeben wird. Wenn der Wert eine Ganzzahl ist, gibt er den System-Exit-Status an (der an die C-Funktion exit() übergeben wird); wenn er None ist, ist der Exit-Status null; wenn er einen anderen Typ hat (z.B. eine Zeichenkette), wird der Wert des Objekts ausgegeben und der Exit-Status ist eins.

Ein Aufruf von sys.exit() wird in eine Ausnahme umgewandelt, damit Bereinigungs-Handler (finally-Klauseln von try-Anweisungen) ausgeführt werden können, und damit ein Debugger ein Skript ausführen kann, ohne die Kontrolle zu verlieren. Die Funktion os._exit() kann verwendet werden, wenn es absolut notwendig ist, sofort zu beenden (z.B. im Kindprozess nach einem Aufruf von os.fork()).

code

Der Exit-Status oder die Fehlermeldung, die an den Konstruktor übergeben wird. (Standard ist None.)

exception TypeError

Wird ausgelöst, wenn eine Operation oder Funktion auf ein Objekt des ungeeigneten Typs angewendet wird. Der zugehörige Wert ist eine Zeichenkette, die Details über die Typen-Diskrepanz angibt.

Diese Ausnahme kann vom Benutzer-Code 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 bestimmte Operation unterstützen soll, aber noch keine Implementierung bereitgestellt hat, ist NotImplementedError die richtige Ausnahme, die ausgelöst werden sollte.

Das Übergeben von Argumenten des falschen Typs (z.B. Übergabe einer Liste, wenn eine Ganzzahl erwartet wird) sollte zu einem TypeError führen, aber das Übergeben von Argumenten mit falschem Wert (z.B. eine Zahl außerhalb der erwarteten Grenzen) sollte zu einem ValueError führen.

exception UnboundLocalError

Wird ausgelöst, wenn eine Referenz auf eine lokale Variable in einer Funktion oder Methode gemacht wird, aber kein Wert an diese Variable gebunden wurde. Dies ist eine Unterklasse von NameError.

exception UnicodeError

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

UnicodeError hat Attribute, die den Kodierungs- oder Dekodierungsfehler beschreiben. Zum Beispiel gibt err.object[err.start:err.end] die spezifischen ungültigen Eingaben an, mit denen der Codec Probleme hatte.

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.

Dieser Wert sollte nicht negativ sein, da er als absoluter Offset interpretiert wird, diese Einschränkung wird jedoch zur Laufzeit nicht erzwungen.

end

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

Dieser Wert sollte nicht negativ sein, da er als absoluter Offset interpretiert wird, diese Einschränkung wird jedoch zur Laufzeit nicht erzwungen.

exception UnicodeEncodeError

Wird ausgelöst, wenn während der Kodierung ein Unicode-bezogener Fehler auftritt. Es ist eine Unterklasse von UnicodeError.

exception UnicodeDecodeError

Wird ausgelöst, wenn während der Dekodierung ein Unicode-bezogener Fehler auftritt. Es ist eine Unterklasse von UnicodeError.

exception UnicodeTranslateError

Wird ausgelöst, wenn während der Übersetzung ein Unicode-bezogener Fehler auftritt. Es ist eine Unterklasse von UnicodeError.

exception ValueError

Wird ausgelöst, wenn eine Operation oder Funktion ein Argument erhält, das den richtigen Typ, aber einen ungeeigneten Wert hat, und die Situation nicht durch eine genauere Ausnahme 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 Ausnahmen werden aus Kompatibilitätsgründen mit früheren Versionen beibehalten; ab Python 3.3 sind sie Aliase für OSError.

exception EnvironmentError

exception IOError

exception WindowsError

Nur unter Windows verfügbar.

Betriebssystem-Ausnahmen

Die folgenden Ausnahmen sind Unterklassen von OSError und werden je nach 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 eingestellt ist. Entspricht errno EAGAIN, EALREADY, EWOULDBLOCK und EINPROGRESS.

Zusätzlich zu den Attributen von OSError kann BlockingIOError ein weiteres Attribut haben:

characters_written

Eine Ganzzahl, die die Anzahl der Zeichen enthält, die vor dem Blockieren in den Stream geschrieben wurden. 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 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 wenn versucht wird, in einen Socket zu schreiben, der für Schreibvorgänge heruntergefahren wurde. Entspricht errno EPIPE und ESHUTDOWN.

exception ConnectionAbortedError

Eine Unterklasse von ConnectionError, die ausgelöst wird, wenn ein Verbindungsversuch vom Partner abgebrochen wird. Entspricht errno ECONNABORTED.

exception ConnectionRefusedError

Eine Unterklasse von ConnectionError, die ausgelöst wird, wenn ein Verbindungsversuch vom Partner abgelehnt wird. Entspricht errno ECONNREFUSED.

exception ConnectionResetError

Eine Unterklasse von ConnectionError, die ausgelöst wird, wenn eine Verbindung vom Partner zurückgesetzt wird. Entspricht errno ECONNRESET.

exception FileExistsError

Wird ausgelöst, wenn versucht wird, eine Datei oder ein Verzeichnis zu erstellen, das bereits existiert. Entspricht errno EEXIST.

exception FileNotFoundError

Wird ausgelöst, wenn eine Datei oder ein Verzeichnis angefordert wird, das nicht existiert. Entspricht errno ENOENT.

exception InterruptedError

Wird ausgelöst, wenn ein Systemaufruf durch ein eingehendes Signal unterbrochen wird. Entspricht errno EINTR.

Geändert in Version 3.5: Python versucht nun Systemaufrufe erneut, wenn sie durch ein Signal unterbrochen werden, es sei denn, der Signalhandler löst eine Ausnahme aus (siehe PEP 475 für die Begründung), anstatt InterruptedError auszulösen.

exception IsADirectoryError

Wird ausgelöst, wenn eine Dateioperation (wie z. B. os.remove()) auf einem Verzeichnis angefordert wird. Entspricht errno EISDIR.

exception NotADirectoryError

Wird ausgelöst, wenn eine Verzeichnisoperation (wie z. B. os.listdir()) auf etwas angefordert wird, das kein Verzeichnis ist. Auf den meisten POSIX-Plattformen kann dies auch ausgelöst werden, wenn eine Operation versucht, eine Datei, die kein Verzeichnis ist, wie ein Verzeichnis zu öffnen oder zu durchlaufen. Entspricht errno ENOTDIR.

exception PermissionError

Wird ausgelöst, wenn versucht wird, eine Operation ohne ausreichende Zugriffsrechte auszuführen – z. B. Dateisystemberechtigungen. Entspricht errno EACCES, EPERM und ENOTCAPABLE.

Geändert in Version 3.11.1: WASI's ENOTCAPABLE wird nun auf PermissionError abgebildet.

exception ProcessLookupError

Wird ausgelöst, wenn ein bestimmter Prozess nicht existiert. Entspricht errno ESRCH.

exception TimeoutError

Wird ausgelöst, wenn eine Systemfunktion auf Systemebene abgelaufen ist. Entspricht errno ETIMEDOUT.

Hinzugefügt in Version 3.3: Alle oben genannten Unterklassen von OSError wurden hinzugefügt.

Siehe auch

PEP 3151 - Überarbeitung der Ausnahmehierarchie für OS und IO

Warnungen

Die folgenden Ausnahmen werden als Warnungskategorien verwendet; weitere Details finden Sie in der Dokumentation Warnungskategorien.

exception Warning

Basisklasse für Warnungskategorien.

exception UserWarning

Basisklasse für Warnungen, die vom Benutzercode generiert werden.

exception DeprecationWarning

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

Wird von den Standard-Warnfiltern ignoriert, außer im __main__-Modul (PEP 565). Das Aktivieren des Python Development Mode zeigt diese Warnung an.

Die Deprecation-Richtlinie ist in PEP 387 beschrieben.

exception PendingDeprecationWarning

Basisklasse für Warnungen über Funktionen, die veraltet sind und voraussichtlich in Zukunft veraltet werden, aber derzeit nicht veraltet sind.

Diese Klasse wird selten verwendet, da das Ausgeben einer Warnung über eine mögliche zukünftige Veralterung ungewöhnlich ist und DeprecationWarning für bereits aktive Veralterungen bevorzugt wird.

Wird von den Standard-Warnfiltern ignoriert. Das Aktivieren des Python Development Mode zeigt diese Warnung an.

Die Deprecation-Richtlinie ist in PEP 387 beschrieben.

exception SyntaxWarning

Basisklasse für Warnungen über zweifelhafte Syntax.

Diese Warnung wird typischerweise beim Kompilieren von Python-Quellcode ausgegeben und normalerweise nicht beim Ausführen bereits kompilierter Code.

exception RuntimeWarning

Basisklasse für Warnungen über zweifelhaftes Laufzeitverhalten.

exception FutureWarning

Basisklasse für Warnungen über veraltete Funktionen, wenn diese Warnungen für Endbenutzer von Anwendungen bestimmt sind, die in Python geschrieben sind.

exception ImportWarning

Basisklasse für Warnungen über wahrscheinliche Fehler bei Modulimporten.

Wird von den Standard-Warnfiltern ignoriert. Das Aktivieren des Python Development Mode zeigt diese Warnung an.

exception UnicodeWarning

Basisklasse für Warnungen im Zusammenhang mit Unicode.

exception EncodingWarning

Basisklasse für Warnungen im Zusammenhang mit Encodings.

Details finden Sie unter Opt-in EncodingWarning.

Hinzugefügt 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. Das Aktivieren des Python Development Mode zeigt diese Warnung an.

Hinzugefügt in Version 3.2.

Exception-Gruppen

Die folgenden werden verwendet, wenn es notwendig ist, mehrere unabhängige Ausnahmen auszulösen. Sie sind Teil der Ausnahmehierarchie, sodass sie wie alle anderen Ausnahmen mit except behandelt werden können. Zusätzlich werden sie von except* erkannt, das ihre Untergruppen basierend auf den Typen der enthaltenen Ausnahmen abgleicht.

exception ExceptionGroup(msg, excs)

exception BaseExceptionGroup(msg, excs)

Beide Ausnahmetypen kapseln die Ausnahmen in der Sequenz excs. Der Parameter msg muss eine Zeichenkette sein. Der Unterschied zwischen den beiden Klassen besteht darin, dass BaseExceptionGroup von BaseException erbt und jede Ausnahme kapseln kann, während ExceptionGroup von Exception erbt und nur Unterklassen von Exception kapseln kann. Dieses Design ermöglicht es, dass except Exception eine ExceptionGroup abfängt, aber keine BaseExceptionGroup.

Der Konstruktor BaseExceptionGroup gibt eine ExceptionGroup und keine BaseExceptionGroup zurück, wenn alle enthaltenen Ausnahmen Instanzen von Exception sind, sodass die Auswahl automatisch erfolgen kann. Der Konstruktor von ExceptionGroup hingegen löst einen TypeError aus, wenn eine enthaltene Ausnahme keine Unterklasse von Exception ist.

message

Das Argument msg für den Konstruktor. Dies ist ein schreibgeschütztes Attribut.

exceptions

Ein Tupel der Ausnahmen in der Sequenz excs, die dem Konstruktor übergeben wurde. Dies ist ein schreibgeschütztes Attribut.

subgroup(condition)

Gibt eine Ausnahme-Gruppe zurück, die nur die Ausnahmen aus der aktuellen Gruppe enthält, die condition entsprechen, oder None, wenn das Ergebnis leer ist.

Die Bedingung kann ein Ausnahmetyp oder ein Tupel von Ausnahmetypen sein, in diesem Fall wird jede Ausnahme auf Übereinstimmung geprüft, mit der gleichen Prüfung, die in einer except-Klausel verwendet wird. Die Bedingung kann auch ein aufrufbares Objekt (außer einem Typobjekt) sein, das eine Ausnahme als einziges Argument akzeptiert und für die Ausnahmen, die in der Untergruppe enthalten sein sollen, true zurückgibt.

Die Verschachtelungsstruktur der aktuellen Ausnahme wird im Ergebnis beibehalten, ebenso wie die Werte ihrer Felder message, __traceback__, __cause__, __context__ und __notes__. Leere verschachtelte Gruppen werden vom Ergebnis weggelassen.

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

Hinzugefügt in Version 3.13: condition kann jedes aufrufbare Objekt sein, das kein Typobjekt ist.

split(condition)

Wie subgroup(), gibt aber das Paar (match, rest) zurück, wobei match subgroup(condition) und rest der verbleibende Nicht-Übereinstimmungsteil ist.

derive(excs)

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

Diese Methode wird von subgroup() und split() verwendet, die in verschiedenen Kontexten zum Aufteilen einer Ausnahme-Gruppe verwendet werden. Eine Unterklasse muss sie überschreiben, um subgroup() und split() Instanzen der Unterklasse anstelle von ExceptionGroup zurückgeben zu lassen.

subgroup() und split() kopieren die Felder __traceback__, __cause__, __context__ und __notes__ von der ursprünglichen Ausnahme-Gruppe zu der von derive() zurückgegebenen, 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

Beachten Sie, dass BaseExceptionGroup __new__() definiert, sodass Unterklassen, die eine andere Konstruktorsignatur benötigen, diese anstelle von __init__() überschreiben müssen. Zum Beispiel definiert das Folgende eine Unterklasse von Ausnahme-Gruppen, die einen Exit-Code akzeptiert und aus diesem die Nachricht der Gruppe erstellt.

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)

Ähnlich wie ExceptionGroup kann jede Unterklasse von BaseExceptionGroup, die auch eine Unterklasse von Exception ist, nur Instanzen von Exception kapseln.

Hinzugefügt in Version 3.11.

Ausnahmehierarchie

Die Klassenhierarchie für integrierte Ausnahmen 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