Inbyggda undantag

I Python måste alla undantag vara instanser av en klass som härstammar från BaseException. I en try-sats med en except-klausul som nämner en viss klass, hanterar den klausulen också alla undantagsklasser som härrör från den klassen (men inte undantagsklasser som den härrör från). Två undantagsklasser som inte är relaterade via subklassning är aldrig likvärdiga, även om de har samma namn.

De inbyggda undantagen som listas i detta kapitel kan genereras av tolken eller inbyggda funktioner. Förutom där det nämns har de ett ”associerat värde” som anger den detaljerade orsaken till felet. Detta kan vara en sträng eller en tupel av flera informationsobjekt (t.ex. en felkod och en sträng som förklarar koden). Det associerade värdet skickas vanligtvis som argument till undantagsklassens konstruktor.

Användarkod kan skapa inbyggda undantag. Detta kan användas för att testa en undantagshanterare eller för att rapportera ett feltillstånd ”precis som” den situation där tolken skapar samma undantag; men tänk på att det inte finns något som hindrar användarkoden från att skapa ett olämpligt fel.

De inbyggda undantagsklasserna kan subklassas för att definiera nya undantag; programmerare uppmuntras att härleda nya undantag från klassen Exception eller någon av dess subklasser, och inte från BaseException. Mer information om hur man definierar undantag finns i Python Tutorial under Användardefinierade undantag.

Kontext för undantag

Tre attribut på undantagsobjekt ger information om i vilket sammanhang undantaget uppstod:

BaseException.__context__
BaseException.__cause__
BaseException.__suppress_context__

När ett nytt undantag skapas medan ett annat undantag redan hanteras, sätts det nya undantagets __context__-attribut automatiskt till det hanterade undantaget. Ett undantag kan hanteras när en except- eller finally-sats, eller en with-sats, används.

Denna implicita undantagskontext kan kompletteras med en explicit orsak genom att använda from med raise:

höja new_exc från original_exc

Uttrycket som följer efter from måste vara ett undantag eller None. Det kommer att ställas in som __cause__ på det uppkomna undantaget. Att ställa in __cause__ ställer också implicit in __suppress_context__ attributet till True, så att genom att använda raise new_exc from None ersätts effektivt det gamla undantaget med det nya för visningsändamål (t.ex. konvertera KeyError till AttributeError), medan det gamla undantaget lämnas tillgängligt i __context__ för introspektion vid felsökning.

Standardkoden för visning av spårning visar dessa kedjade undantag utöver spårningen av själva undantaget. Ett explicit kedjat undantag i __cause__ visas alltid när det finns. Ett implicit kedjat undantag i __context__ visas endast om __cause__ är None och __suppress_context__ är false.

I båda fallen visas alltid själva undantaget efter eventuella kedjade undantag, så att den sista raden i traceback alltid visar det sista undantaget som uppstod.

Ärver från inbyggda undantag

Användarkod kan skapa subklasser som ärver från en undantagstyp. Det rekommenderas att endast subklassa en undantagstyp åt gången för att undvika eventuella konflikter mellan hur baserna hanterar attributet args, samt på grund av eventuella inkompatibiliteter i minneslayouten.

De flesta inbyggda undantag är implementerade i C för effektivitetens skull, se: Objects/exceptions.c. Vissa har anpassade minneslayouter vilket gör det omöjligt att skapa en subklass som ärver från flera undantagstyper. Minneslayouten för en typ är en implementationsdetalj och kan ändras mellan Python-versioner, vilket leder till nya konflikter i framtiden. Därför rekommenderas det att undvika att underklassa flera undantagstyper helt och hållet.

Basklasser

Följande undantag används mest som basklasser för andra undantag.

exception BaseException

Basklassen för alla inbyggda undantag. Den är inte avsedd att ärvas direkt av användardefinierade klasser (för det, använd Exception). Om str() anropas på en instans av den här klassen returneras representationen av argumentet/argumenten till instansen, eller den tomma strängen om det inte fanns några argument.

args

Den tupel av argument som ges till undantagskonstruktören. Vissa inbyggda undantag (som OSError) förväntar sig ett visst antal argument och tilldelar en speciell betydelse till elementen i denna tupel, medan andra vanligtvis bara anropas med en enda sträng som ger ett felmeddelande.

with_traceback(tb)

Den här metoden anger tb som ny traceback för undantaget och returnerar undantagsobjektet. Den användes oftare innan exception chaining-funktionerna i PEP 3134 blev tillgängliga. Följande exempel visar hur vi kan konvertera en instans av SomeException till en instans av OtherException samtidigt som vi bevarar spårningen. När den väl har uppstått, skjuts den aktuella ramen till spårningen av OtherException, vilket skulle ha hänt med spårningen av den ursprungliga SomeException om vi hade tillåtit den att fortplanta sig till den som anropar.

försök:
    ...
except SomeException:
    tb = sys.exception().__traceback__
    raise AnnanAttent(...).med_traceback(tb)
__traceback__

Ett skrivbart fält som innehåller traceback-objektet som är associerat med detta undantag. Se även: raise-satsen.

add_note(note)

Lägg till strängen note i undantagets anteckningar som visas i standardåterrapporteringen efter undantagssträngen. Ett TypeError uppstår om note inte är en sträng.

Tillagd i version 3.11.

__notes__

En lista över anteckningarna för detta undantag, som lades till med add_note(). Detta attribut skapas när add_note() anropas.

Tillagd i version 3.11.

exception Exception

Alla inbyggda undantag som inte är systemundantag härrör från denna klass. Alla användardefinierade undantag bör också härledas från denna klass.

exception ArithmeticError

Basklass för de inbyggda undantag som uppstår vid olika aritmetiska fel: OverflowError, ZeroDivisionError, FloatingPointError.

exception BufferError

Uppstår när en buffer-relaterad åtgärd inte kan utföras.

exception LookupError

Basklassen för de undantag som uppstår när en nyckel eller ett index som används i en mappning eller sekvens är ogiltigt: IndexError, KeyError. Detta kan tas upp direkt av codecs.lookup().

Betongundantag

Följande undantag är de undantag som vanligtvis tas upp.

exception AssertionError

Uppstår när en assert-sats misslyckas.

exception AttributeError

Utlöses när en attributreferens (se Attributreferenser) eller attributtilldelning misslyckas. (När ett objekt inte stöder attributreferenser eller attributtilldelningar alls, genereras TypeError)

De valfria argumenten name och obj, som endast innehåller nyckelord, anger motsvarande attribut:

name

Namnet på det attribut som man försökte få åtkomst till.

obj

Det objekt som användes för det namngivna attributet.

Ändrad i version 3.10: Lagt till attributen name och obj.

exception EOFError

Utlöses när funktionen input() träffar ett filändsvillkor (EOF) utan att läsa några data. (Obs: metoderna io.IOBase.read() och io.IOBase.readline() returnerar en tom sträng när de träffar EOF)

exception FloatingPointError

Används inte för närvarande.

exception GeneratorExit

Uppstår när en generator eller coroutine stängs; se generator.close() och coroutine.close(). Den ärver direkt från BaseException istället för Exception eftersom det tekniskt sett inte är ett fel.

exception ImportError

Utlöses när import-satsen har problem med att ladda en modul. Uppstår också när ”from-listan” i from ... import har ett namn som inte kan hittas.

De valfria argumenten name och path, som endast innehåller nyckelord, anger motsvarande attribut:

name

Namnet på den modul som man försökte importera.

path

Sökvägen till den fil som utlöste undantaget.

Ändrad i version 3.3: Lagt till attributen name och path.

exception ModuleNotFoundError

En underklass till ImportError som skapas av import när en modul inte kunde hittas. Det visas också när None hittas i sys.modules.

Tillagd i version 3.6.

exception IndexError

Uppstår när ett sekvenssubskript är utanför intervallet. (Slice-index trunkeras i tysthet för att hamna inom det tillåtna intervallet; om ett index inte är ett heltal väcks TypeError)

exception KeyError

Utlöses när en mappningsnyckel (ordbok) inte finns i uppsättningen av befintliga nycklar.

exception KeyboardInterrupt

Uppstår när användaren trycker på avbrottstangenten (normalt Control-C eller Delete). Under exekveringen görs regelbundet en kontroll av avbrott. Undantaget ärver från BaseException så att det inte av misstag fångas upp av kod som fångar upp Exception och därmed hindrar tolken från att avsluta.

Anteckning

Att fånga ett KeyboardInterrupt kräver särskild hänsyn. Eftersom den kan utlösas vid oförutsägbara tidpunkter kan den under vissa omständigheter lämna det pågående programmet i ett inkonsekvent tillstånd. Det är i allmänhet bäst att låta KeyboardInterrupt avsluta programmet så snabbt som möjligt eller helt undvika att utlösa det. (Se Anmärkning om signalhanterare och undantag.)

exception MemoryError

Utlöses när en operation får slut på minne men situationen fortfarande kan räddas (genom att radera vissa objekt). Det associerade värdet är en sträng som anger vilken typ av (intern) operation som fick slut på minne. Observera att på grund av den underliggande minneshanteringsarkitekturen (C:s malloc()-funktion) kan tolken kanske inte alltid helt återhämta sig från denna situation; den väcker ändå ett undantag så att en stackspårning kan skrivas ut, ifall ett skenande program var orsaken.

exception NameError

Utlöses när ett lokalt eller globalt namn inte hittas. Detta gäller endast okvalificerade namn. Det associerade värdet är ett felmeddelande som innehåller det namn som inte kunde hittas.

Det valfria argumentet name keyword-only anger attributet:

name

Namnet på den variabel som man försökte få åtkomst till.

Ändrad i version 3.10: Lagt till attributet name.

exception NotImplementedError

Detta undantag härrör från RuntimeError. I användardefinierade basklasser bör abstrakta metoder ge upphov till detta undantag när de kräver att härledda klasser åsidosätter metoden, eller medan klassen utvecklas för att indikera att den verkliga implementationen fortfarande behöver läggas till.

Anteckning

Det ska inte användas för att ange att en operator eller metod inte ska stödjas alls - i så fall ska operatorn/metoden antingen lämnas odefinierad eller, om det är en subklass, anges till None.

Försiktighet

NotImplementedError och NotImplemented är inte utbytbara. Detta undantag bör endast användas enligt beskrivningen ovan; se NotImplemented för detaljer om korrekt användning av den inbyggda konstanten.

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

Detta undantag uppstår när en systemfunktion returnerar ett systemrelaterat fel, inklusive I/O-fel som ”file not found” eller ”disk full” (inte för olagliga argumenttyper eller andra tillfälliga fel).

Den andra formen av konstruktorn ställer in motsvarande attribut, som beskrivs nedan. Attributen har som standard None om de inte specificeras. För bakåtkompatibilitet, om tre argument skickas, innehåller attributet args endast en 2-tupel av de två första konstruktörsargumenten.

Konstruktorn returnerar ofta faktiskt en underklass av OSError, som beskrivs i OS-undantag nedan. Den specifika underklassen beror på det slutliga errno-värdet. Detta beteende uppstår endast när man konstruerar OSError direkt eller via ett alias, och ärvs inte vid subklassning.

errno

En numerisk felkod från C-variabeln errno.

winerror

Under Windows ger detta dig den ursprungliga Windows-felkoden. Attributet errno är då en ungefärlig översättning, i POSIX-termer, av den ursprungliga felkoden.

Under Windows, om konstruktörsargumentet winerror är ett heltal, bestäms attributet errno från Windows felkod och argumentet errno ignoreras. På andra plattformar ignoreras winerror-argumentet och attributet winerror existerar inte.

strerror

Det motsvarande felmeddelandet, som tillhandahålls av operativsystemet. Det formateras av C-funktionerna perror() under POSIX och FormatMessage() under Windows.

filename
filename2

För undantag som involverar en filsystemssökväg (t.ex. open() eller os.unlink()) är filename det filnamn som skickas till funktionen. För funktioner som involverar två filsystemssökvägar (t.ex. os.rename()) motsvarar filename2 det andra filnamnet som skickas till funktionen.

Ändrad i version 3.3: EnvironmentError, IOError, WindowsError, socket.error, select.error och mmap.error har slagits samman till OSError, och konstruktören kan returnera en underklass.

Ändrad i version 3.4: Attributet filename är nu det ursprungliga filnamnet som skickas till funktionen, istället för det namn som kodats till eller avkodats från filesystem encoding and error handler. Dessutom har konstruktörsargumentet och attributet filename2 lagts till.

exception OverflowError

Utlöses när resultatet av en aritmetisk operation är för stort för att kunna representeras. Detta kan inte inträffa för heltal (som hellre ger upphov till MemoryError än ger upp). Av historiska skäl visas dock ibland OverflowError för heltal som ligger utanför ett önskat intervall. På grund av bristen på standardisering av undantagshantering för flyttal i C kontrolleras inte de flesta flyttalsoperationer.

exception PythonFinalizationError

Detta undantag härstammar från RuntimeError. Det uppstår när en operation blockeras under nedstängning av tolken, även känt som Python finalization.

Exempel på operationer som kan blockeras med ett PythonFinalizationError under Python-finaliseringen:

Se även funktionen sys.is_finalizing().

Tillagd i version 3.13: Tidigare gavs ett vanligt RuntimeError.

Ändrad i version 3.14: threading.Thread.join() kan nu ge upphov till detta undantag.

exception RecursionError

Detta undantag härstammar från RuntimeError. Det uppstår när tolken upptäcker att det maximala rekursionsdjupet (se sys.getrecursionlimit()) har överskridits.

Tillagd i version 3.5: Tidigare gavs ett vanligt RuntimeError.

exception ReferenceError

Detta undantag uppstår när en proxy för svaga referenser, skapad av funktionen weakref.proxy(), används för att komma åt ett attribut hos referenten efter att den har samlats in. För mer information om svaga referenser, se modulen weakref.

exception RuntimeError

Utlöses när ett fel upptäcks som inte faller inom någon av de andra kategorierna. Det associerade värdet är en sträng som anger exakt vad som gick fel.

exception StopIteration

Utlöses av den inbyggda funktionen next() och en iterator:s __next__()-metod för att signalera att det inte finns några fler objekt som produceras av iteratorn.

value

Undantagsobjektet har ett enda attribut value, som anges som ett argument när undantaget konstrueras och som standard är None.

När en generator eller coroutine-funktion returneras, skapas en ny StopIteration-instans och det värde som returneras av funktionen används som value-parameter i konstruktören för undantaget.

Om en generatorkod direkt eller indirekt ger upphov till StopIteration, konverteras den till en RuntimeError (med StopIteration som orsak till det nya undantaget).

Ändrad i version 3.3: Lagt till attributet value och möjligheten för generatorfunktioner att använda det för att returnera ett värde.

Ändrad i version 3.5: Införde transformationen RuntimeError via from __future__ import generator_stop, se PEP 479.

Ändrad i version 3.7: Aktivera PEP 479 för all kod som standard: ett StopIteration-fel som uppstår i en generator omvandlas till ett RuntimeError.

exception StopAsyncIteration

Måste tas fram av __anext__()-metoden för ett asynkron iterator-objekt för att stoppa iterationen.

Tillagd i version 3.5.

exception SyntaxError(message, details)

Utlöses när parsern stöter på ett syntaxfel. Detta kan inträffa i en import-sats, i ett anrop till de inbyggda funktionerna compile(), exec() eller eval(), eller vid läsning av det inledande skriptet eller standardinmatningen (även interaktivt).

Undantagsinstansens str() returnerar endast felmeddelandet. Details är en tupel vars medlemmar också är tillgängliga som separata attribut.

filename

Namnet på den fil där syntaxfelet inträffade.

lineno

Vilket radnummer i filen som felet uppstod i. Detta är 1-indexerat: den första raden i filen har en lineno på 1.

offset

Kolumnen i raden där felet inträffade. Detta är 1-indexerat: det första tecknet på raden har en offset på 1.

text

Den källkodstext som är inblandad i felet.

end_lineno

Vilket radnummer i filen som felet inträffade slutar på. Detta är 1-indexerat: den första raden i filen har en lineno på 1.

end_offset

Kolumnen i slutraden där felet uppstod avslutas. Detta är 1-indexerat: det första tecknet på raden har en offset på 1.

För fel i fält med f-strängar inleds meddelandet med ”f-sträng: ” och offseten är offseten i en text som konstruerats utifrån ersättningsuttrycket. Exempelvis resulterar kompilering av f’Bad {a b} field’ i detta args-attribut: (’f-string: …’, (’’, 1, 2, ’(a b)n’, 1, 5)).

Ändrad i version 3.10: Lagt till attributen end_lineno och end_offset.

exception IndentationError

Basklass för syntaxfel relaterade till felaktig indragning. Detta är en underklass till SyntaxError.

exception TabError

Utlöses när indentation innehåller en inkonsekvent användning av tabbar och mellanslag. Detta är en underklass till IndentationError.

exception SystemError

Utlöses när tolken hittar ett internt fel, men situationen inte ser så allvarlig ut att den får den att ge upp allt hopp. Det associerade värdet är en sträng som anger vad som gick fel (i lågnivåtermer). I CPython kan detta uppstå genom felaktig användning av Pythons C API, t.ex. att returnera ett NULL-värde utan en undantagsuppsättning.

Om du är säker på att detta undantag inte var ditt fel, eller felet i ett paket som du använder, bör du rapportera detta till författaren eller underhållaren av din Python-tolk. Var noga med att rapportera versionen av Python-tolken (sys.version; den skrivs också ut i början av en interaktiv Python-session), det exakta felmeddelandet (undantagets associerade värde) och om möjligt källan till det program som utlöste felet.

exception SystemExit

Detta undantag skapas av funktionen sys.exit(). Det ärver från BaseException istället för Exception så att det inte av misstag fångas upp av kod som fångar upp Exception. Detta gör att undantaget kan spridas ordentligt uppåt och få tolken att avsluta. När det inte hanteras avslutas Python-tolken; ingen stack traceback skrivs ut. Konstruktören accepterar samma valfria argument som skickas till sys.exit(). Om värdet är ett heltal anger det systemets exitstatus (skickas till C:s funktion exit()); om det är None är exitstatusen noll; om det har en annan typ (t.ex. en sträng) skrivs objektets värde ut och exitstatusen är ett.

Ett anrop till sys.exit() översätts till ett undantag så att rensningshanterare (finally-klausuler i try-satser) kan köras och så att en debugger kan köra ett skript utan att riskera att förlora kontrollen. Funktionen os._exit() kan användas om det är absolut nödvändigt att avsluta omedelbart (t.ex. i barnprocessen efter ett anrop till os.fork()).

code

Utgångsstatus eller felmeddelande som skickas till konstruktören. (Standardvärdet är None.)

exception TypeError

Utlöses när en operation eller funktion tillämpas på ett objekt av olämplig typ. Det associerade värdet är en sträng som ger information om felaktig typmatchning.

Detta undantag kan skapas av användarkod för att indikera att ett försök att utföra en operation på ett objekt inte stöds och inte heller är avsett att stödjas. Om ett objekt är avsett att stödja en viss operation men ännu inte har tillhandahållit en implementering, är NotImplementedError det korrekta undantaget.

Att skicka argument av fel typ (t.ex. att skicka en list när en int förväntas) bör resultera i ett TypeError, men att skicka argument med fel värde (t.ex. ett tal utanför förväntade gränser) bör resultera i ett ValueError.

exception UnboundLocalError

Utlöses när en referens görs till en lokal variabel i en funktion eller metod, men inget värde har bundits till variabeln. Detta är en underklass till NameError.

exception UnicodeError

Utlöses när ett Unicode-relaterat kodnings- eller avkodningsfel inträffar. Det är en underklass till ValueError.

UnicodeError har attribut som beskriver kodnings- eller avkodningsfelet. Till exempel ger err.object[err.start:err.end] den specifika ogiltiga indata som codec misslyckades med.

encoding

Namnet på den kodning som orsakade felet.

reason

En sträng som beskriver det specifika codec-felet.

object

Det objekt som codec försökte koda eller avkoda.

start

Det första indexet för ogiltiga data i object.

Detta värde bör inte vara negativt eftersom det tolkas som en absolut förskjutning, men denna begränsning tillämpas inte under körning.

end

Indexet efter den sista ogiltiga uppgiften i object.

Detta värde bör inte vara negativt eftersom det tolkas som en absolut förskjutning, men denna begränsning tillämpas inte under körning.

exception UnicodeEncodeError

Uppstår när ett Unicode-relaterat fel inträffar under kodningen. Det är en underklass till UnicodeError.

exception UnicodeDecodeError

Uppstår när ett Unicode-relaterat fel inträffar under avkodningen. Det är en underklass till UnicodeError.

exception UnicodeTranslateError

Uppstår när ett Unicode-relaterat fel inträffar under översättningen. Det är en underklass till UnicodeError.

exception ValueError

Utlöses när en operation eller funktion får ett argument som har rätt typ men ett olämpligt värde, och situationen inte beskrivs av ett mer precist undantag som IndexError.

exception ZeroDivisionError

Uppstår när det andra argumentet i en divisions- eller modulooperation är noll. Det associerade värdet är en sträng som anger typen av operander och operation.

Följande undantag finns kvar för kompatibilitet med tidigare versioner; från och med Python 3.3 är de alias för OSError.

exception EnvironmentError
exception IOError
exception WindowsError

Endast tillgängligt på Windows.

OS-undantag

Följande undantag är underklasser till OSError, de aktiveras beroende på systemets felkod.

exception BlockingIOError

Uppstår när en operation skulle blockera ett objekt (t.ex. socket) som är inställt för icke-blockerande operationer. Motsvarar errno EAGAIN, EALREADY, EWOULDBLOCK och EINPROGRESS.

Utöver de attribut som finns för OSError kan BlockingIOError ha ytterligare ett attribut:

characters_written

Ett heltal som innehåller antalet tecken som skrevs till strömmen innan den blockerades. Detta attribut är tillgängligt när du använder de buffrade I/O-klasserna från modulen io.

exception ChildProcessError

Utlöses när en åtgärd på en underordnad process misslyckades. Motsvarar errno ECHILD.

exception ConnectionError

En basklass för anslutningsrelaterade frågor.

Underklasser är BrokenPipeError, ConnectionAbortedError, ConnectionRefusedError och ConnectionResetError.

exception BrokenPipeError

En underklass till ConnectionError, som uppstår när man försöker skriva på en pipe medan den andra änden har stängts, eller när man försöker skriva på en socket som har stängts för skrivning. Motsvarar errno EPIPE och ESHUTDOWN.

exception ConnectionAbortedError

En underklass till ConnectionError, som uppstår när ett anslutningsförsök avbryts av motparten. Motsvarar errno ECONNABORTED.

exception ConnectionRefusedError

En underklass till ConnectionError, som uppstår när ett anslutningsförsök nekas av motparten. Motsvarar errno ECONNREFUSED.

exception ConnectionResetError

En underklass till ConnectionError, som uppstår när en anslutning återställs av motparten. Motsvarar errno ECONNRESET.

exception FileExistsError

Utlöses när man försöker skapa en fil eller katalog som redan finns. Motsvarar errno EEXIST.

exception FileNotFoundError

Utlöses när en fil eller katalog begärs men inte finns. Motsvarar errno ENOENT.

exception InterruptedError

Utlöses när ett systemanrop avbryts av en inkommande signal. Motsvarar errno EINTR.

Ändrad i version 3.5: Python gör nu om systemanrop när ett syscall avbryts av en signal, utom om signalhanteraren gör ett undantag (se PEP 475 för motivering), istället för att göra InterruptedError.

exception IsADirectoryError

Utlöses när en filoperation (t.ex. os.remove()) begärs på en katalog. Motsvarar errno EISDIR.

exception NotADirectoryError

Utlöses när en katalogoperation (t.ex. os.listdir()) begärs på något som inte är en katalog. På de flesta POSIX-plattformar kan det också uppstå om en åtgärd försöker öppna eller gå igenom en fil som inte är en katalog som om den vore en katalog. Motsvarar errno ENOTDIR.

exception PermissionError

Utlöses när man försöker köra en operation utan tillräckliga rättigheter - till exempel filsystembehörighet. Motsvarar errno EACCES, EPERM, och ENOTCAPABLE.

Ändrad i version 3.11.1: WASI:s ENOTCAPABLE mappas nu till PermissionError.

exception ProcessLookupError

Utlöses när en viss process inte existerar. Motsvarar errno ESRCH.

exception TimeoutError

Utlöses när en systemfunktion timade ut på systemnivå. Motsvarar errno ETIMEDOUT.

Tillagd i version 3.3: Alla ovanstående OSError-subklasser lades till.

Se även

PEP 3151 - Omarbetning av undantagshierarkin för OS och IO

Varningar

Följande undantag används som varningskategorier; se Varningskategorier-dokumentationen för mer information.

exception Warning

Basklass för varningskategorier.

exception UserWarning

Basklass för varningar som genereras av användarkod.

exception DeprecationWarning

Basklass för varningar om föråldrade funktioner när dessa varningar är avsedda för andra Python-utvecklare.

Ignoreras av standardvarningsfiltren, utom i modulen __main__ (PEP 565). Om du aktiverar Python Development Mode visas denna varning.

Policyn för utfasning beskrivs i PEP 387.

exception PendingDeprecationWarning

Basklass för varningar om funktioner som är föråldrade och förväntas bli utdaterade i framtiden, men som inte är utdaterade för tillfället.

Denna klass används sällan eftersom det är ovanligt att skicka ut en varning om en eventuell kommande deprecation, och DeprecationWarning föredras för redan aktiva deprecations.

Ignoreras av standardvarningsfiltren. Om du aktiverar Python Development Mode visas den här varningen.

Policyn för utfasning beskrivs i PEP 387.

exception SyntaxWarning

Basklass för varningar om tvivelaktig syntax.

exception RuntimeWarning

Basklass för varningar om tvivelaktigt beteende under körtid.

exception FutureWarning

Basklass för varningar om föråldrade funktioner när dessa varningar är avsedda för slutanvändare av program som är skrivna i Python.

exception ImportWarning

Basklass för varningar om troliga misstag i modulimporten.

Ignoreras av standardvarningsfiltren. Om du aktiverar Python Development Mode visas den här varningen.

exception UnicodeWarning

Basklass för varningar relaterade till Unicode.

exception EncodingWarning

Basklass för varningar relaterade till kodning.

Se Opt-in-kodningVarning för mer information.

Tillagd i version 3.10.

exception BytesWarning

Basklass för varningar relaterade till bytes och bytearray.

exception ResourceWarning

Basklass för varningar relaterade till resursanvändning.

Ignoreras av standardvarningsfiltren. Om du aktiverar Python Development Mode visas den här varningen.

Tillagd i version 3.2.

Undantagsgrupper

Följande används när det är nödvändigt att skapa flera orelaterade undantag. De är en del av undantagshierarkin så de kan hanteras med except som alla andra undantag. Dessutom känns de igen av except*, som matchar deras undergrupper baserat på typerna av de undantag som ingår.

exception ExceptionGroup(msg, excs)
exception BaseExceptionGroup(msg, excs)

Båda dessa undantagstyper packar in undantagen i sekvensen excs. Parametern msg måste vara en sträng. Skillnaden mellan de två klasserna är att BaseExceptionGroup extenderar BaseException och kan fånga alla undantag, medan ExceptionGroup extenderar Exception och bara kan fånga subklasser av Exception. Denna design är så att except Exception fångar en ExceptionGroup men inte BaseExceptionGroup.

Konstruktören BaseExceptionGroup returnerar en ExceptionGroup i stället för en BaseExceptionGroup om alla undantag som ingår är Exception-instanser, så den kan användas för att göra urvalet automatiskt. Konstruktören för ExceptionGroup, å andra sidan, ger upphov till ett TypeError om något undantag som ingår inte är en underklass till Exception.

message

Argumentet msg till konstruktören. Detta är ett skrivskyddat attribut.

exceptions

En tupel av undantagen i sekvensen excs som ges till konstruktören. Detta är ett skrivskyddat attribut.

subgroup(condition)

Returnerar en undantagsgrupp som bara innehåller de undantag från den aktuella gruppen som matchar villkor, eller None om resultatet är tomt.

Villkoret kan vara en undantagstyp eller en tupel av undantagstyper, i vilket fall varje undantag kontrolleras för matchning med samma kontroll som används i en except-klausul. Villkoret kan också vara en callable (annat än ett typobjekt) som accepterar ett undantag som enda argument och returnerar true för de undantag som bör ingå i undergruppen.

Det aktuella undantagets nestningsstruktur bevaras i resultatet, liksom värdena i fälten message, __traceback__, __cause__, __context__ och __notes__. Tomma nästlade grupper utelämnas från resultatet.

Villkoret kontrolleras för alla undantag i den nästlade undantagsgruppen, inklusive den översta nivån och alla nästlade undantagsgrupper. Om villkoret är sant för en sådan undantagsgrupp ingår den i resultatet i sin helhet.

Tillagd i version 3.13: condition kan vara vilken callable som helst som inte är ett typobjekt.

split(condition)

Som subgroup(), men returnerar paret (match, rest) där match är subgroup(condition) och rest är den återstående icke-matchande delen.

derive(excs)

Returnerar en undantagsgrupp med samma message, men som omsluter undantagen i excs.

Den här metoden används av subgroup() och split(), som används i olika sammanhang för att bryta upp en undantagsgrupp. En subklass måste åsidosätta den för att få subgroup() och split() att returnera instanser av subklassen istället för ExceptionGroup.

subgroup() och split() kopierar fälten __traceback__, __cause__, __context__ och __notes__ från den ursprungliga undantagsgruppen till den som returneras av derive(), så dessa fält behöver inte uppdateras av derive().

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

Observera att BaseExceptionGroup definierar __new__(), så underklasser som behöver en annan konstruktörsignatur måste åsidosätta den i stället för __init__(). Följande definierar till exempel en exception group-underklass som tar emot en exit_code och konstruerar gruppens meddelande utifrån den.

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

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

Liksom ExceptionGroup kan en subklass av BaseExceptionGroup som också är en subklass av Exception bara omsluta instanser av Exception.

Tillagd i version 3.11.

Undantagshierarki

Klasshierarkin för inbyggda undantag är:

BaseException
 ├── BaseExceptionGroup
 ├─── GeneratorExit
 keyboardInterrupt
 ├── SystemExit
 └── Undantag
      aritmetiskt fel (ArithmeticError)
      │ ├── FloatingPointError
      │ ├── Överflödesfel
      │ └── NollDivisionsFel
      ├── AssertionError
      ├── AttributFel
      ├── Buffertfel
      ├── EOFError
      ├── ExceptionGroup [BaseExceptionGroup]
      ├── ImportFel
      │ └── ModulFinnsInteFel
      ├── LookupError
      │ ├── IndexError
      │ └── KeyError
      ├─── MemoryError
      ├── NamnFel
      │ └── ObundetLokaltFel
      ├── OSError
      │ ├── BlockerandeIOFel
      │ ├── ChildProcessError
      │ ├── AnslutningFel
      │ │ ├── BrokenPipeError
      │ │ ├── ConnectionAbortedError
      │ │ ├── ConnectionRefusedError
      │ │ └── ConnectionResetError
      │ ├── FileExistsError
      │ ├── FileNotFoundError
      │ ├── AvbrutetFel
      │ ├── IsADirectoryError
      │ ├── InteADirectoryError
      │ ├── PermissionError
      │ ├── ProcessLookupError
      │ └── TimeoutError
      ├── ReferensFel
      ├── RuntimeError
      │ ├── InteImplementeratFel
      │ ├── PythonFinalizationError
      │ └── Rekursionsfel
      ├── StopAsyncIteration
      ├── StopIteration
      ├── SyntaxFel
      │ └── Indragningsfel
      │ └── TabError
      ├─── Systemfel
      ├── TypeError
      ├── VärdeFel
      │ └── UnicodeFel
      │ ├── UnicodeDecodeError
      │ ├── UnicodeEncodeError
      │ └── UnicodeTranslateError
      └── Varning
           bytesvarning
           ├── Avvecklingsvarning
           kodningsvarning
           ├── Framtida varning
           ├── Importvarning
           ├── VäntarPåAvvecklingVarning
           ├── Resursvarning
           runtimeWarning
           syntaxvarning
           unicodeWarning
           └── Användarvarning