Hantering av undantag

De funktioner som beskrivs i detta kapitel låter dig hantera och skapa Python-undantag. Det är viktigt att förstå några av grunderna i Pythons undantagshantering. Det fungerar ungefär som POSIX errno-variabeln: det finns en global indikator (per tråd) för det senaste felet som inträffade. De flesta C API-funktioner rensar inte detta vid framgång, men kommer att ställa in det för att ange orsaken till felet vid misslyckande. De flesta C API-funktioner returnerar också en felindikator, vanligtvis NULL om de ska returnera en pekare, eller -1 om de returnerar ett heltal (undantag: funktionerna PyArg_* returnerar 1 vid framgång och 0 vid misslyckande).

Konkret består felindikatorn av tre objektpekare: undantagets typ, undantagets värde och traceback-objektet. Vilken som helst av dessa pekare kan vara NULL om den inte är inställd (även om vissa kombinationer är förbjudna, till exempel kan du inte ha en traceback som inte är NULL om undantagstypen är NULL).

När en funktion måste misslyckas på grund av att någon funktion som den anropade misslyckades, sätter den i allmänhet inte felindikatorn; den funktion som den anropade har redan satt den. Den är ansvarig för att antingen hantera felet och rensa undantaget eller återvända efter att ha rensat upp alla resurser den har (t.ex. objektreferenser eller minnesallokeringar); den ska inte fortsätta normalt om den inte är beredd att hantera felet. Om den återvänder på grund av ett fel är det viktigt att ange för den som anropar att ett fel har uppstått. Om felet inte hanteras eller sprids på ett noggrant sätt kan det hända att ytterligare anrop till Python/C API:et inte beter sig som avsett och misslyckas på mystiska sätt.

Anteckning

Felindikatorn är inte resultatet av sys.exc_info(). Det förstnämnda motsvarar ett undantag som ännu inte har fångats upp (och som därför fortfarande sprids), medan det sistnämnda returnerar ett undantag efter att det har fångats upp (och därför har slutat spridas).

Tryckning och clearing

void PyErr_Clear()

En del av Stabil ABI.

Rensa felindikatorn. Om felindikatorn inte är inställd har det ingen effekt.

void PyErr_PrintEx(int set_sys_last_vars)

En del av Stabil ABI.

Skriver ut en standardspårning till sys.stderr och rensar felindikatorn. Om felet inte är ett SystemExit, i så fall skrivs ingen spårning ut och Python-processen avslutas med den felkod som anges av SystemExit -instansen.

Anropa denna funktion endast när felindikatorn är inställd. Annars kommer den att orsaka ett dödligt fel!

Om set_sys_last_vars inte är noll, sätts variabeln sys.last_exc till det utskrivna undantaget. För bakåtkompatibilitet sätts även de föråldrade variablerna sys.last_type, sys.last_value och sys.last_traceback till typ, värde respektive traceback för detta undantag.

Ändrad i version 3.12: Inställningen sys.last_exc har lagts till.

void PyErr_Print()

En del av Stabil ABI.

Alias för PyErr_PrintEx(1).

void PyErr_WriteUnraisable(PyObject *obj)

En del av Stabil ABI.

Anropa sys.unraisablehook() med aktuellt undantag och obj-argument.

Den här funktionen skriver ut ett varningsmeddelande till sys.stderr när ett undantag har ställts in men det är omöjligt för tolken att faktiskt lösa ut undantaget. Den används t.ex. när ett undantag inträffar i en __del__()-metod.

Funktionen anropas med ett enda argument obj som identifierar det sammanhang där det ovärderliga undantaget inträffade. Om möjligt skrivs repr av obj ut i varningsmeddelandet. Om obj är NULL skrivs endast spårningen ut.

Ett undantag måste ställas in när denna funktion anropas.

Ändrad i version 3.4: Skriv ut en spårning. Skriv endast ut en återgång om obj är NULL.

Ändrad i version 3.8: Använd sys.unraisablehook().

void PyErr_FormatUnraisable(const char *format, ...)

Liknar PyErr_WriteUnraisable(), men format och efterföljande parametrar hjälper till att formatera varningsmeddelandet; de har samma betydelse och värden som i PyUnicode_FromFormat(). PyErr_WriteUnraisable(obj) är ungefär likvärdigt med PyErr_FormatUnraisable("Exception ignored in: %R", obj). Om format är NULL skrivs endast spårningen ut.

Tillagd i version 3.13.

void PyErr_DisplayException(PyObject *exc)

En del av Stabil ABI sedan version 3.12.

Skriv ut standardspårningsvisningen av exc till sys.stderr, inklusive kedjade undantag och anteckningar.

Tillagd i version 3.12.

Upprättande av undantag

Dessa funktioner hjälper dig att ställa in den aktuella trådens felindikator. För enkelhetens skull returnerar vissa av dessa funktioner alltid en NULL -pekare för användning i ett return-uttryck.

void PyErr_SetString(PyObject *type, const char *message)

En del av Stabil ABI.

Detta är det vanligaste sättet att ställa in felindikatorn. Det första argumentet anger undantagstypen; det är normalt ett av standardundantagen, t.ex. PyExc_RuntimeError. Du behöver inte skapa en ny strong reference till den (t.ex. med Py_INCREF()). Det andra argumentet är ett felmeddelande; det avkodas från 'utf-8'.

void PyErr_SetObject(PyObject *type, PyObject *value)

En del av Stabil ABI.

Den här funktionen liknar PyErr_SetString() men låter dig ange ett godtyckligt Python-objekt som ”värde” för undantaget.

PyObject *PyErr_Format(PyObject *exception, const char *format, ...)

Returvärde: Alltid NULL. En del av Stabil ABI.

Denna funktion anger felindikatorn och returnerar NULL. exception bör vara en Python exception-klass. Parametrarna format och följande hjälper till att formatera felmeddelandet; de har samma betydelse och värden som i PyUnicode_FromFormat(). format är en ASCII-kodad sträng.

PyObject *PyErr_FormatV(PyObject *exception, const char *format, va_list vargs)

Returvärde: Alltid NULL. En del av Stabil ABI sedan version 3.5.

Samma som PyErr_Format(), men tar ett va_list-argument i stället för ett variabelt antal argument.

Tillagd i version 3.5.

void PyErr_SetNone(PyObject *type)

En del av Stabil ABI.

Detta är en förkortning för PyErr_SetObject(type, Py_None).

int PyErr_BadArgument()

En del av Stabil ABI.

Detta är en förkortning för PyErr_SetString(PyExc_TypeError, message), där message anger att en inbyggd operation anropades med ett olagligt argument. Den är mestadels för internt bruk.

PyObject *PyErr_NoMemory()

Returvärde: Alltid NULL. En del av Stabil ABI.

Detta är en förkortning för PyErr_SetNone(PyExc_MemoryError); den returnerar NULL så att en objektallokeringsfunktion kan skriva return PyErr_NoMemory(); när den har slut på minne.

PyObject *PyErr_SetFromErrno(PyObject *type)

Returvärde: Alltid NULL. En del av Stabil ABI.

Detta är en bekvämlighetsfunktion för att skapa ett undantag när en C-biblioteksfunktion har returnerat ett fel och satt C-variabeln errno. Den konstruerar ett tuple-objekt vars första post är heltalet errno-värdet och vars andra post är motsvarande felmeddelande (hämtat från strerror()), och anropar sedan PyErr_SetObject(type, object). På Unix, när errno-värdet är EINTR, vilket indikerar ett avbrutet systemanrop, anropas PyErr_CheckSignals(), och om det ställde in felindikatorn, lämnas den inställd på det. Funktionen returnerar alltid NULL, så en wrapperfunktion runt ett systemanrop kan skriva return PyErr_SetFromErrno(type); när systemanropet returnerar ett fel.

PyObject *PyErr_SetFromErrnoWithFilenameObject(PyObject *type, PyObject *filenameObject)

Returvärde: Alltid NULL. En del av Stabil ABI.

Liknar PyErr_SetFromErrno(), med det ytterligare beteendet att om filenameObject inte är NULL, skickas det till konstruktören av type som en tredje parameter. I fallet med OSError undantag, används detta för att definiera filename attributet för undantagsinstansen.

PyObject *PyErr_SetFromErrnoWithFilenameObjects(PyObject *type, PyObject *filenameObject, PyObject *filenameObject2)

Returvärde: Alltid NULL. En del av Stabil ABI sedan version 3.7.

Liknar PyErr_SetFromErrnoWithFilenameObject(), men tar ett andra filnamnsobjekt, för att skapa fel när en funktion som tar två filnamn misslyckas.

Tillagd i version 3.4.

PyObject *PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename)

Returvärde: Alltid NULL. En del av Stabil ABI.

Liknar PyErr_SetFromErrnoWithFilenameObject(), men filnamnet anges som en C-sträng. filename är avkodad från filesystem encoding and error handler.

PyObject *PyErr_SetFromWindowsErr(int ierr)

Returvärde: Alltid NULL. En del av Stabil ABI on Windows sedan version 3.7.

Detta är en bekvämlighetsfunktion för att skapa OSError. Om den anropas med ierr på 0 används istället den felkod som returneras av ett anrop till GetLastError(). Den anropar Win32-funktionen FormatMessage() för att hämta Windows-beskrivningen av felkoden som ges av ierr eller GetLastError(), och konstruerar sedan ett OSError-objekt med attributet winerror-attributet satt till felkoden, strerror-attributet satt till motsvarande felmeddelande (hämtat från FormatMessage()), och anropar sedan PyErr_SetObject(PyExc_OSError, object). Denna funktion returnerar alltid NULL.

Tillgänglighet: Windows.

PyObject *PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)

Returvärde: Alltid NULL. En del av Stabil ABI on Windows sedan version 3.7.

Liknar PyErr_SetFromWindowsErr(), med en ytterligare parameter som anger vilken typ av undantag som ska tas upp.

Tillgänglighet: Windows.

PyObject *PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)

Returvärde: Alltid NULL. En del av Stabil ABI on Windows sedan version 3.7.

Liknar PyErr_SetFromWindowsErr(), med det ytterligare beteendet att om filnamn inte är NULL, avkodas det från filsystemets kodning (os.fsdecode()) och skickas till konstruktören av OSError som en tredje parameter som används för att definiera attributet filnamn för undantagsinstansen.

Tillgänglighet: Windows.

PyObject *PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject *type, int ierr, PyObject *filename)

Returvärde: Alltid NULL. En del av Stabil ABI on Windows sedan version 3.7.

Liknar PyErr_SetExcFromWindowsErr(), med det ytterligare beteendet att om filnamn inte är NULL, skickas det till konstruktören av OSError som en tredje parameter som används för att definiera attributet filename för undantagsinstansen.

Tillgänglighet: Windows.

PyObject *PyErr_SetExcFromWindowsErrWithFilenameObjects(PyObject *type, int ierr, PyObject *filename, PyObject *filename2)

Returvärde: Alltid NULL. En del av Stabil ABI on Windows sedan version 3.7.

Liknar PyErr_SetExcFromWindowsErrWithFilenameObject(), men accepterar ett andra filnamnsobjekt.

Tillgänglighet: Windows.

Tillagd i version 3.4.

PyObject *PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, const char *filename)

Returvärde: Alltid NULL. En del av Stabil ABI on Windows sedan version 3.7.

Liknar PyErr_SetFromWindowsErrWithFilename(), med en ytterligare parameter som anger vilken typ av undantag som ska tas upp.

Tillgänglighet: Windows.

PyObject *PyErr_SetImportError(PyObject *msg, PyObject *name, PyObject *path)

Returvärde: Alltid NULL. En del av Stabil ABI sedan version 3.7.

Detta är en bekvämlighetsfunktion för att skapa ImportError. msg kommer att sättas som undantagets meddelandesträng. name och path, som båda kan vara NULL, kommer att anges som ImportError’s respektive attribut name och path.

Tillagd i version 3.3.

PyObject *PyErr_SetImportErrorSubclass(PyObject *exception, PyObject *msg, PyObject *name, PyObject *path)

Returvärde: Alltid NULL. En del av Stabil ABI sedan version 3.6.

Ungefär som PyErr_SetImportError() men den här funktionen gör det möjligt att ange en underklass av ImportError som ska uppstå.

Tillagd i version 3.6.

void PyErr_SyntaxLocationObject(PyObject *filename, int lineno, int col_offset)

Ställer in fil-, rad- och offsetinformation för det aktuella undantaget. Om det aktuella undantaget inte är ett SyntaxError, anges ytterligare attribut som får subsystemet för utskrift av undantag att tro att undantaget är ett SyntaxError.

Tillagd i version 3.4.

void PyErr_SyntaxLocationEx(const char *filename, int lineno, int col_offset)

En del av Stabil ABI sedan version 3.7.

Som PyErr_SyntaxLocationObject(), men filnamn är en byte-sträng avkodad från filesystem encoding and error handler.

Tillagd i version 3.2.

void PyErr_SyntaxLocation(const char *filename, int lineno)

En del av Stabil ABI.

Som PyErr_SyntaxLocationEx(), men parametern col_offset är utelämnad.

void PyErr_BadInternalCall()

En del av Stabil ABI.

Detta är en förkortning för PyErr_SetString(PyExc_SystemError, message), där message indikerar att en intern operation (t.ex. en Python/C API-funktion) anropades med ett olagligt argument. Den är mestadels för internt bruk.

Utfärdande av varningar

Använd dessa funktioner för att utfärda varningar från C-kod. De speglar liknande funktioner som exporteras av Python warnings-modulen. De skriver normalt ut ett varningsmeddelande till sys.stderr, men det är också möjligt att användaren har angett att varningar ska omvandlas till fel, och i så fall kommer de att ge upphov till ett undantag. Det är också möjligt att funktionerna ger upphov till ett undantag på grund av ett problem med varningsmaskineriet. Returvärdet är 0 om inget undantag uppstår, eller -1 om ett undantag uppstår. (Det är inte möjligt att avgöra om ett varningsmeddelande faktiskt skrivs ut eller vad orsaken till undantaget är; detta är avsiktligt) Om ett undantag uppstår bör anroparen göra sin normala undantagshantering (t.ex. Py_DECREF() äger referenser och returnerar ett felvärde).

int PyErr_WarnEx(PyObject *category, const char *message, Py_ssize_t stack_level)

En del av Stabil ABI.

Utfärdar ett varningsmeddelande. Argumentet category är en varningskategori (se nedan) eller NULL; argumentet message är en UTF-8-kodad sträng. stack_level är ett positivt tal som anger ett antal stackrutor; varningen kommer att utfärdas från den kodrad som för närvarande körs i den stackrutan. En stack_level på 1 är den funktion som anropar PyErr_WarnEx(), 2 är funktionen ovanför den, och så vidare.

Varningskategorier måste vara subklasser av PyExc_Warning; PyExc_Warning är en subklass av PyExc_Exception; standardvarningskategorin är PyExc_RuntimeWarning. Pythons standardvarningskategorier finns tillgängliga som globala variabler vars namn räknas upp på Typer av varningar.

Mer information om varningskontroll finns i dokumentationen för modulen warnings och alternativet -W i kommandoradsdokumentationen. Det finns inget C API för varningskontroll.

int PyErr_WarnExplicitObject(PyObject *category, PyObject *message, PyObject *filename, int lineno, PyObject *module, PyObject *registry)

Utfärda ett varningsmeddelande med explicit kontroll över alla varningsattribut. Detta är en enkel omslutning av Python-funktionen warnings.warn_explicit(); se där för mer information. Argumenten module och registry kan sättas till NULL för att få den förvalda effekten som beskrivs där.

Tillagd i version 3.4.

int PyErr_WarnExplicit(PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry)

En del av Stabil ABI.

Liknar PyErr_WarnExplicitObject() förutom att message och module är UTF-8-kodade strängar och filename är avkodad från filesystem encoding and error handler.

int PyErr_WarnFormat(PyObject *category, Py_ssize_t stack_level, const char *format, ...)

En del av Stabil ABI.

Funktion liknande PyErr_WarnEx(), men använd PyUnicode_FromFormat() för att formatera varningsmeddelandet. format är en ASCII-kodad sträng.

Tillagd i version 3.2.

int PyErr_ResourceWarning(PyObject *source, Py_ssize_t stack_level, const char *format, ...)

En del av Stabil ABI sedan version 3.6.

Funktion liknande PyErr_WarnFormat(), men category är ResourceWarning och den skickar source till warnings.WarningMessage.

Tillagd i version 3.6.

Fråga efter felindikatorn

PyObject *PyErr_Occurred()

Returnera värde: Lånad referens. En del av Stabil ABI.

Testar om felindikatorn är inställd. Om den är inställd, returneras undantagets typ (det första argumentet till det senaste anropet till en av funktionerna PyErr_Set* eller till PyErr_Restore()). Om den inte är inställd returneras NULL. Du äger inte en referens till returvärdet, så du behöver inte Py_DECREF() det.

Den som anropar måste ha en attached thread state.

Anteckning

Jämför inte returvärdet med ett specifikt undantag; använd istället PyErr_ExceptionMatches(), som visas nedan. (Jämförelsen kan lätt misslyckas eftersom undantaget kan vara en instans i stället för en klass, i fallet med ett klassundantag, eller det kan vara en underklass av det förväntade undantaget)

int PyErr_ExceptionMatches(PyObject *exc)

En del av Stabil ABI.

Motsvarar PyErr_GivenExceptionMatches(PyErr_Occurred(), exc). Detta bör endast anropas när ett undantag faktiskt har ställts in; en minnesåtkomstöverträdelse kommer att inträffa om inget undantag har ställts in.

int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)

En del av Stabil ABI.

Returnerar true om det givna undantaget matchar undantagstypen i exc. Om exc är ett klassobjekt returneras även true när given är en instans av en underklass. Om exc är en tupel, söks alla undantagstyper i tupeln (och rekursivt i subtuplar) efter en matchning.

PyObject *PyErr_GetRaisedException(void)

Returnera värde: Ny referens. En del av Stabil ABI sedan version 3.12.

Returnerar det undantag som för närvarande tas upp och rensar samtidigt felindikatorn. Returnerar NULL om felindikatorn inte är inställd.

Denna funktion används av kod som behöver fånga upp undantag, eller kod som behöver spara och återställa felindikatorn tillfälligt.

Till exempel:

{
   PyObject *exc = PyErr_GetRaisedException();

   /* ... kod som kan producera andra fel ... */

   PyErr_SetRaisedException(exc);
}

Se även

PyErr_GetHandledException(), för att spara det undantag som för närvarande hanteras.

Tillagd i version 3.12.

void PyErr_SetRaisedException(PyObject *exc)

En del av Stabil ABI sedan version 3.12.

Ange exc som det undantag som för närvarande tas upp, och rensa det befintliga undantaget om ett sådant har angetts.

Varning

Detta anrop stjäl en referens till exc, som måste vara ett giltigt undantag.

Tillagd i version 3.12.

void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)

En del av Stabil ABI.

Föråldrad sedan version 3.12: Använd PyErr_GetRaisedException() istället.

Hämta felindikatorn till tre variabler vars adresser skickas. Om felindikatorn inte är inställd, ställ in alla tre variablerna till NULL. Om den är inställd kommer den att rensas och du äger en referens till varje objekt som hämtas. Värde- och spårningsobjektet kan vara NULL även om typobjektet inte är det.

Anteckning

Den här funktionen används normalt bara av äldre kod som behöver fånga upp undantag eller spara och återställa felindikatorn tillfälligt.

Till exempel:

{
   PyObject *type, *value, *traceback;
   PyErr_Fetch(&type, &value, &traceback);

   /* ... code that might produce other errors ... */

   PyErr_Restore(type, value, traceback);
}

void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback)

En del av Stabil ABI.

Föråldrad sedan version 3.12: Använd PyErr_SetRaisedException() istället.

Ställ in felindikatorn från de tre objekten type, value och traceback och rensa den befintliga undantagsindikatorn om en sådan finns. Om objekten är NULL rensas felindikatorn. Skicka inte en NULL -typ och ett icke- NULL -värde eller en traceback. Undantagstypen ska vara en klass. Skicka inte en ogiltig undantagstyp eller ett ogiltigt undantagsvärde. (Om du bryter mot dessa regler kan det uppstå subtila problem senare.) Detta anrop tar bort en referens till varje objekt: du måste äga en referens till varje objekt före anropet och efter anropet äger du inte längre dessa referenser. (Om du inte förstår detta ska du inte använda denna funktion. Jag har varnat dig.)

Anteckning

Den här funktionen används normalt bara av äldre kod som behöver spara och återställa felindikatorn tillfälligt. Använd PyErr_Fetch() för att spara den aktuella felindikatorn.

void PyErr_NormalizeException(PyObject **exc, PyObject **val, PyObject **tb)

En del av Stabil ABI.

Föråldrad sedan version 3.12: Använd PyErr_GetRaisedException() istället, för att undvika eventuell de-normalisering.

Under vissa omständigheter kan värdena som returneras av PyErr_Fetch() nedan vara ”onormaliserade”, vilket innebär att *exc är ett klassobjekt men *val inte är en instans av samma klass. Denna funktion kan användas för att instansiera klassen i det fallet. Om värdena redan är normaliserade händer ingenting. Den fördröjda normaliseringen är implementerad för att förbättra prestandan.

Anteckning

Den här funktionen ställer inte implicit in attributet __traceback__ på undantagsvärdet. Om man vill ställa in traceback på rätt sätt behövs följande ytterligare snutt:

if (tb != NULL) {
  PyException_SetTraceback(val, tb);
}

PyObject *PyErr_GetHandledException(void)

En del av Stabil ABI sedan version 3.11.

Hämtar den aktiva undantagsinstansen, som den skulle returneras av sys.exception(). Detta hänvisar till ett undantag som redan fångats upp, inte till ett undantag som nyligen har uppstått. Returnerar en ny referens till undantaget eller NULL. Ändrar inte tolkens undantagstillstånd.

Anteckning

Denna funktion används normalt inte av kod som vill hantera undantag. Istället kan den användas när koden behöver spara och återställa undantagstillståndet tillfälligt. Använd PyErr_SetHandledException() för att återställa eller rensa undantagstillståndet.

Tillagd i version 3.11.

void PyErr_SetHandledException(PyObject *exc)

En del av Stabil ABI sedan version 3.11.

Ställer in det aktiva undantaget, enligt sys.exception(). Detta hänvisar till ett undantag som redan fångats, inte till ett undantag som nyligen har uppstått. För att rensa undantagstillståndet, skicka NULL.

Anteckning

Denna funktion används normalt inte av kod som vill hantera undantag. Istället kan den användas när koden behöver spara och återställa undantagstillståndet tillfälligt. Använd PyErr_GetHandledException() för att hämta undantagstillståndet.

Tillagd i version 3.11.

void PyErr_GetExcInfo(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)

En del av Stabil ABI sedan version 3.7.

Hämtar den gammaldags representationen av undantagsinformationen, som den är känd från sys.exc_info(). Detta hänvisar till ett undantag som redan fångats upp, inte till ett undantag som nyligen uppstått. Returnerar nya referenser för de tre objekten, varav något kan vara NULL. Ändrar inte tillståndet för undantagsinfo. Denna funktion behålls för bakåtkompatibilitet. Föredrar att använda PyErr_GetHandledException().

Anteckning

Denna funktion används normalt inte av kod som vill hantera undantag. Istället kan den användas när koden behöver spara och återställa undantagstillståndet tillfälligt. Använd PyErr_SetExcInfo() för att återställa eller rensa undantagstillståndet.

Tillagd i version 3.3.

void PyErr_SetExcInfo(PyObject *type, PyObject *value, PyObject *traceback)

En del av Stabil ABI sedan version 3.7.

Ställer in undantagsinformationen, som den är känd från sys.exc_info(). Detta hänvisar till ett undantag som redan fångats, inte till ett undantag som nyligen uppstod. Den här funktionen stjäl argumentens referenser. För att rensa undantagstillståndet, skicka NULL för alla tre argumenten. Denna funktion behålls för bakåtkompatibilitet. Föredrar att använda PyErr_SetHandledException().

Anteckning

Denna funktion används normalt inte av kod som vill hantera undantag. Istället kan den användas när koden behöver spara och återställa undantagstillståndet tillfälligt. Använd PyErr_GetExcInfo() för att läsa undantagstillståndet.

Tillagd i version 3.3.

Ändrad i version 3.11: Argumenten type och traceback används inte längre och kan vara NULL. Tolken härleder dem nu från undantagsinstansen (argumentet value). Funktionen stjäl fortfarande referenser till alla tre argumenten.

Signalhantering

int PyErr_CheckSignals()

En del av Stabil ABI.

Denna funktion interagerar med Pythons signalhantering.

Om funktionen anropas från huvudtråden och under Pythons huvudtolk, kontrollerar den om en signal har skickats till processerna och anropar i så fall motsvarande signalhanterare. Om modulen signal stöds kan den anropa en signalhanterare som är skriven i Python.

Funktionen försöker hantera alla väntande signaler och returnerar sedan 0. Men om en Python-signalhanterare ger upphov till ett undantag, sätts felindikatorn och funktionen returnerar -1 omedelbart (så att andra väntande signaler kanske inte har hanterats ännu: de kommer att hanteras vid nästa PyErr_CheckSignals()-inkallning).

Om funktionen anropas från en tråd som inte är huvudtråd, eller under en Python-tolk som inte är huvudtråd, gör den ingenting och returnerar 0.

Den här funktionen kan anropas av C-kod som körs under lång tid och som vill kunna avbrytas av användaren (t.ex. genom att trycka på Ctrl-C).

Anteckning

Pythons standardsignalhanterare för SIGINT ger upphov till undantaget KeyboardInterrupt.

void PyErr_SetInterrupt()

En del av Stabil ABI.

Simulerar effekten av att en SIGINT-signal anländer. Detta är likvärdigt med PyErr_SetInterruptEx(SIGINT).

Anteckning

Denna funktion är async-signal-säker. Den kan anropas utan en attached thread state och från en C-signalhanterare.

int PyErr_SetInterruptEx(int signum)

En del av Stabil ABI sedan version 3.10.

Simulerar effekten av att en signal anländer. Nästa gång PyErr_CheckSignals() anropas, kommer Python-signalhanteraren för det angivna signalnumret att anropas.

Denna funktion kan anropas av C-kod som ställer in sin egen signalhantering och vill att Pythons signalhanterare ska anropas som förväntat när ett avbrott begärs (t.ex. när användaren trycker på Ctrl-C för att avbryta en operation).

Om den angivna signalen inte hanteras av Python (den var inställd på signal.SIG_DFL eller signal.SIG_IGN), ignoreras den.

Om signum ligger utanför det tillåtna intervallet för signalnummer, returneras -1. I annat fall returneras 0. Felindikatorn ändras aldrig av denna funktion.

Anteckning

Denna funktion är async-signal-säker. Den kan anropas utan en attached thread state och från en C-signalhanterare.

Tillagd i version 3.10.

int PySignal_SetWakeupFd(int fd)

Denna utility-funktion specificerar en filbeskrivare till vilken signalnumret skrivs som en enda byte när en signal tas emot. fd måste vara icke-blockerande. Den returnerar den föregående sådana fildescriptorn.

Värdet -1 inaktiverar funktionen; detta är det initiala tillståndet. Detta är likvärdigt med signal.set_wakeup_fd() i Python, men utan någon felkontroll. fd bör vara en giltig filbeskrivare. Funktionen bör endast anropas från huvudtråden.

Ändrad i version 3.5: I Windows stöder funktionen nu även socket-handtag.

Undantagsklasser

PyObject *PyErr_NewException(const char *name, PyObject *base, PyObject *dict)

Returnera värde: Ny referens. En del av Stabil ABI.

Denna verktygsfunktion skapar och returnerar en ny undantagsklass. Argumentet name måste vara namnet på det nya undantaget, en C-sträng av formen module.classname. Argumenten base och dict är normalt NULL. Detta skapar ett klassobjekt som härrör från Exception (tillgängligt i C som PyExc_Exception).

Attributet __module__ för den nya klassen sätts till den första delen (upp till den sista punkten) av argumentet name och klassnamnet sätts till den sista delen (efter den sista punkten). Argumentet base kan användas för att ange alternativa basklasser; det kan antingen vara bara en klass eller en tupel av klasser. Argumentet dict kan användas för att ange en ordbok över klassens variabler och metoder.

PyObject *PyErr_NewExceptionWithDoc(const char *name, const char *doc, PyObject *base, PyObject *dict)

Returnera värde: Ny referens. En del av Stabil ABI.

Samma som PyErr_NewException(), förutom att den nya undantagsklassen enkelt kan ges en docstring: Om doc är icke-NULL, kommer den att användas som dokumentsträng för undantagsklassen.

Tillagd i version 3.2.

int PyExceptionClass_Check(PyObject *ob)

Returnerar icke-noll om ob är en undantagsklass, noll annars. Denna funktion lyckas alltid.

const char *PyExceptionClass_Name(PyObject *ob)

En del av Stabil ABI sedan version 3.8.

Returnerar tp_name i undantagsklassen ob.

Objekt för undantag

PyObject *PyException_GetTraceback(PyObject *ex)

Returnera värde: Ny referens. En del av Stabil ABI.

Returnerar den traceback som är associerad med undantaget som en ny referens, som tillgänglig från Python genom attributet __traceback__. Om det inte finns någon traceback associerad, returneras NULL.

int PyException_SetTraceback(PyObject *ex, PyObject *tb)

En del av Stabil ABI.

Ställ in den traceback som är kopplad till undantaget till tb. Använd Py_None för att rensa det.

PyObject *PyException_GetContext(PyObject *ex)

Returnera värde: Ny referens. En del av Stabil ABI.

Returnerar kontexten (en annan undantagsinstans under vars hantering ex togs upp) som är associerad med undantaget som en ny referens, som tillgänglig från Python genom attributet __context__. Om det inte finns någon kontext associerad, returneras NULL.

void PyException_SetContext(PyObject *ex, PyObject *ctx)

En del av Stabil ABI.

Ställ in kontexten som är associerad med undantaget till ctx. Använd NULL för att rensa den. Det finns ingen typkontroll för att se till att ctx är en undantagsinstans. Detta stjäl en referens till ctx.

PyObject *PyException_GetCause(PyObject *ex)

Returnera värde: Ny referens. En del av Stabil ABI.

Returnerar orsaken (antingen en undantagsinstans eller None, inställd av raise ... from ...) associerad med undantaget som en ny referens, som tillgänglig från Python genom attributet __cause__.

void PyException_SetCause(PyObject *ex, PyObject *cause)

En del av Stabil ABI.

Ange orsaken till undantaget till cause. Använd NULL för att rensa den. Det finns ingen typkontroll för att se till att cause antingen är en undantagsinstans eller None. Detta stjäl en referens till cause.

Attributet __suppress_context__ sätts implicit till True av denna funktion.

PyObject *PyException_GetArgs(PyObject *ex)

Returnera värde: Ny referens. En del av Stabil ABI sedan version 3.12.

Returnera args för undantag ex.

void PyException_SetArgs(PyObject *ex, PyObject *args)

En del av Stabil ABI sedan version 3.12.

Ställ in args för undantag ex till args.

PyObject *PyUnstable_Exc_PrepReraiseStar(PyObject *orig, PyObject *excs)

Detta är Instabilt API. Den kan ändras utan förvarning i mindre versioner.

Implementerar en del av tolkens implementation av except*. orig är det ursprungliga undantaget som fångades upp och excs är listan över de undantag som måste tas upp. Denna lista innehåller den ohanterade delen av orig, om någon, samt de undantag som togs upp från except*-klausulerna (så de har en annan traceback än orig) och de som togs upp igen (och har samma traceback som orig). Returnerar den ExceptionGroup som behöver återupplivas i slutet, eller None om det inte finns något att återuppliva.

Tillagd i version 3.12.

Objekt för Unicode-undantag

Följande funktioner används för att skapa och modifiera Unicode-undantag från C.

PyObject *PyUnicodeDecodeError_Create(const char *encoding, const char *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)

Returnera värde: Ny referens. En del av Stabil ABI.

Skapa ett UnicodeDecodeError-objekt med attributen encoding, object, length, start, end och reason. encoding och reason är UTF-8-kodade strängar.

PyObject *PyUnicodeDecodeError_GetEncoding(PyObject *exc)

PyObject *PyUnicodeEncodeError_GetEncoding(PyObject *exc)

Returnera värde: Ny referens. En del av Stabil ABI.

Returnerar encoding-attributet för det angivna undantagsobjektet.

PyObject *PyUnicodeDecodeError_GetObject(PyObject *exc)

PyObject *PyUnicodeEncodeError_GetObject(PyObject *exc)

PyObject *PyUnicodeTranslateError_GetObject(PyObject *exc)

Returnera värde: Ny referens. En del av Stabil ABI.

Returnerar object-attributet för det angivna undantagsobjektet.

int PyUnicodeDecodeError_GetStart(PyObject *exc, Py_ssize_t *start)

int PyUnicodeEncodeError_GetStart(PyObject *exc, Py_ssize_t *start)

int PyUnicodeTranslateError_GetStart(PyObject *exc, Py_ssize_t *start)

En del av Stabil ABI.

Hämta start-attributet för det angivna undantagsobjektet och placera det i *start. start får inte vara NULL. Returnerar 0 vid framgång, -1 vid misslyckande.

Om UnicodeError.object är en tom sekvens, är den resulterande starten 0. Annars klipps den till [0, len(object) - 1].

Se även

UnicodeError.start

int PyUnicodeDecodeError_SetStart(PyObject *exc, Py_ssize_t start)

int PyUnicodeEncodeError_SetStart(PyObject *exc, Py_ssize_t start)

int PyUnicodeTranslateError_SetStart(PyObject *exc, Py_ssize_t start)

En del av Stabil ABI.

Sätter attributet start för det angivna undantagsobjektet till start. Returnerar 0 vid framgång, -1 vid misslyckande.

Anteckning

Även om det inte leder till något undantag att skicka en negativ start, kommer motsvarande getters inte att betrakta den som en relativ offset.

int PyUnicodeDecodeError_GetEnd(PyObject *exc, Py_ssize_t *end)

int PyUnicodeEncodeError_GetEnd(PyObject *exc, Py_ssize_t *end)

int PyUnicodeTranslateError_GetEnd(PyObject *exc, Py_ssize_t *end)

En del av Stabil ABI.

Hämta end-attributet för det angivna undantagsobjektet och placera det i *end. end får inte vara NULL. Returnerar 0 vid framgång, -1 vid misslyckande.

Om UnicodeError.object är en tom sekvens, blir det resulterande slutet 0. Annars klipps den till [1, len(object)].

int PyUnicodeDecodeError_SetEnd(PyObject *exc, Py_ssize_t end)

int PyUnicodeEncodeError_SetEnd(PyObject *exc, Py_ssize_t end)

int PyUnicodeTranslateError_SetEnd(PyObject *exc, Py_ssize_t end)

En del av Stabil ABI.

Sätter attributet end för det angivna undantagsobjektet till end. Returnerar 0 vid framgång, -1 vid misslyckande.

Se även

UnicodeError.end

PyObject *PyUnicodeDecodeError_GetReason(PyObject *exc)

PyObject *PyUnicodeEncodeError_GetReason(PyObject *exc)

PyObject *PyUnicodeTranslateError_GetReason(PyObject *exc)

Returnera värde: Ny referens. En del av Stabil ABI.

Returnerar attributet reason för det angivna undantagsobjektet.

int PyUnicodeDecodeError_SetReason(PyObject *exc, const char *reason)

int PyUnicodeEncodeError_SetReason(PyObject *exc, const char *reason)

int PyUnicodeTranslateError_SetReason(PyObject *exc, const char *reason)

En del av Stabil ABI.

Sätter attributet reason för det angivna undantagsobjektet till reason. Returnerar 0 vid framgång, -1 vid misslyckande.

Kontroll av rekursion

Dessa två funktioner gör det möjligt att utföra säkra rekursiva anrop på C-nivå, både i kärnan och i tilläggsmoduler. De behövs om den rekursiva koden inte nödvändigtvis anropar Python-kod (som spårar sitt rekursionsdjup automatiskt). De behövs inte heller för tp_call-implementeringar eftersom call protocol tar hand om rekursionshanteringen.

int Py_EnterRecursiveCall(const char *where)

En del av Stabil ABI sedan version 3.9.

Markerar en punkt där ett rekursivt anrop på C-nivå är på väg att utföras.

Funktionen kontrollerar sedan om stackgränsen är nådd. Om så är fallet anges ett RecursionError och ett värde som inte är noll returneras. Annars returneras noll.

där ska vara en UTF-8-kodad sträng som " in instance check" som ska konkateneras till meddelandet RecursionError som orsakas av gränsen för rekursionsdjup.

Ändrad i version 3.9: Denna funktion är nu också tillgänglig i limited API.

void Py_LeaveRecursiveCall(void)

En del av Stabil ABI sedan version 3.9.

Avslutar en Py_EnterRecursiveCall(). Måste anropas en gång för varje lyckad anrop av Py_EnterRecursiveCall().

Ändrad i version 3.9: Denna funktion är nu också tillgänglig i limited API.

Korrekt implementering av tp_repr för containertyper kräver speciell rekursionshantering. Förutom att skydda stacken måste tp_repr också spåra objekt för att förhindra cykler. Följande två funktioner underlättar denna funktionalitet. I praktiken är dessa C-motsvarigheten till reprlib.recursive_repr().

int Py_ReprEnter(PyObject *object)

En del av Stabil ABI.

Anropas i början av tp_repr-implementeringen för att upptäcka cykler.

Om objektet redan har bearbetats returnerar funktionen ett positivt heltal. I så fall bör tp_repr-implementeringen returnera ett strängobjekt som indikerar en cykel. Som exempel kan nämnas att dict-objekt returnerar {...} och list-objekt returnerar [...].

Funktionen returnerar ett negativt heltal om rekursionsgränsen är nådd. I så fall bör implementeringen tp_repr typiskt returnera NULL.

I annat fall returnerar funktionen noll och tp_repr-implementeringen kan fortsätta normalt.

void Py_ReprLeave(PyObject *object)

En del av Stabil ABI.

Avslutar en Py_ReprEnter(). Måste anropas en gång för varje anrop av Py_ReprEnter() som returnerar noll.

Typer av undantag och varningar

Alla Pythons standardundantag och varningskategorier finns tillgängliga som globala variabler vars namn är PyExc_ följt av Pythons undantagsnamn. Dessa har typen PyObject*; de är alla klassobjekt.

För fullständighetens skull, här är alla variabler:

Typer av undantag

C-namn	Python-namn
PyObject *PyExc_BaseException En del av Stabil ABI.	BaseException
PyObject *PyExc_BaseExceptionGroup En del av Stabil ABI sedan version 3.11.	BaseExceptionGroup
PyObject *PyExc_Exception En del av Stabil ABI.	Untantagande
PyObject *PyExc_ArithmeticError En del av Stabil ABI.	Aritmetiskt fel
PyObject *PyExc_AssertionError En del av Stabil ABI.	AssertionError
PyObject *PyExc_AttributeError En del av Stabil ABI.	AttributeError
PyObject *PyExc_BlockingIOError En del av Stabil ABI sedan version 3.7.	BlockingIOError
PyObject *PyExc_BrokenPipeError En del av Stabil ABI sedan version 3.7.	BrokenPipeError
PyObject *PyExc_BufferError En del av Stabil ABI.	BufferError
PyObject *PyExc_ChildProcessError En del av Stabil ABI sedan version 3.7.	ChildProcessError
PyObject *PyExc_ConnectionAbortedError En del av Stabil ABI sedan version 3.7.	Fel vid avbruten anslutning
PyObject *PyExc_ConnectionError En del av Stabil ABI sedan version 3.7.	AnslutningFel
PyObject *PyExc_ConnectionRefusedError En del av Stabil ABI sedan version 3.7.	AnslutningRefusedError
PyObject *PyExc_ConnectionResetError En del av Stabil ABI sedan version 3.7.	Fel vid återställning av anslutning
PyObject *PyExc_EOFError En del av Stabil ABI.	EOFError
PyObject *PyExc_FileExistsError En del av Stabil ABI sedan version 3.7.	FileExistsError
PyObject *PyExc_FileNotFoundError En del av Stabil ABI sedan version 3.7.	FileNotFoundError
PyObject *PyExc_FloatingPointError En del av Stabil ABI.	FloatingPointError
PyObject *PyExc_GeneratorExit En del av Stabil ABI.	GeneratorExit
PyObject *PyExc_ImportError En del av Stabil ABI.	ImportError
PyObject *PyExc_IndentationError En del av Stabil ABI.	IndentationError
PyObject *PyExc_IndexError En del av Stabil ABI.	IndexError
PyObject *PyExc_InterruptedError En del av Stabil ABI sedan version 3.7.	AvbrutetFel
PyObject *PyExc_IsADirectoryError En del av Stabil ABI sedan version 3.7.	IsADirectoryError
PyObject *PyExc_KeyError En del av Stabil ABI.	KeyError
PyObject *PyExc_KeyboardInterrupt En del av Stabil ABI.	KeyboardInterrupt
PyObject *PyExc_LookupError En del av Stabil ABI.	LookupError
PyObject *PyExc_MemoryError En del av Stabil ABI.	MemoryError
PyObject *PyExc_ModuleNotFoundError En del av Stabil ABI sedan version 3.6.	ModuleNotFoundError
PyObject *PyExc_NameError En del av Stabil ABI.	NamnFel
PyObject *PyExc_NotADirectoryError En del av Stabil ABI sedan version 3.7.	NotADirectoryError
PyObject *PyExc_NotImplementedError En del av Stabil ABI.	NotImplementedError
PyObject *PyExc_OSError En del av Stabil ABI.	OSError
PyObject *PyExc_OverflowError En del av Stabil ABI.	OverflowError
PyObject *PyExc_PermissionError En del av Stabil ABI sedan version 3.7.	PermissionError
PyObject *PyExc_ProcessLookupError En del av Stabil ABI sedan version 3.7.	ProcessLookupError
PyObject *PyExc_PythonFinalizationError	PythonFinalizationError
PyObject *PyExc_RecursionError En del av Stabil ABI sedan version 3.7.	RecursionError
PyObject *PyExc_ReferenceError En del av Stabil ABI.	ReferenceError
PyObject *PyExc_RuntimeError En del av Stabil ABI.	RuntimeError
PyObject *PyExc_StopAsyncIteration En del av Stabil ABI sedan version 3.7.	StopAsyncIteration
PyObject *PyExc_StopIteration En del av Stabil ABI.	StopIteration
PyObject *PyExc_SyntaxError En del av Stabil ABI.	SyntaxError
PyObject *PyExc_SystemError En del av Stabil ABI.	SystemError
PyObject *PyExc_SystemExit En del av Stabil ABI.	SystemExit
PyObject *PyExc_TabError En del av Stabil ABI.	TabError
PyObject *PyExc_TimeoutError En del av Stabil ABI sedan version 3.7.	TimeoutError
PyObject *PyExc_TypeError En del av Stabil ABI.	TypeError
PyObject *PyExc_UnboundLocalError En del av Stabil ABI.	UnboundLocalError
PyObject *PyExc_UnicodeDecodeError En del av Stabil ABI.	UnicodeDecodeError
PyObject *PyExc_UnicodeEncodeError En del av Stabil ABI.	UnicodeEncodeError
PyObject *PyExc_UnicodeError En del av Stabil ABI.	UnicodeError
PyObject *PyExc_UnicodeTranslateError En del av Stabil ABI.	UnicodeTranslateError
PyObject *PyExc_ValueError En del av Stabil ABI.	ValueError
PyObject *PyExc_ZeroDivisionError En del av Stabil ABI.	ZeroDivisionError

Tillagd i version 3.3: PyExc_BlockingIOError, PyExc_BrokenPipeError, PyExc_ChildProcessError, PyExc_ConnectionError, PyExc_ConnectionAbortedError, PyExc_ConnectionRefusedError, PyExc_ConnectionResetError, PyExc_FileExistsError, PyExc_FileNotFoundError, PyExc_InterruptedError, PyExc_IsADirectoryError, PyExc_NotADirectoryError, PyExc_PermissionError, PyExc_ProcessLookupError och PyExc_TimeoutError infördes enligt PEP 3151.

Tillagd i version 3.5: PyExc_StopAsyncIteration och PyExc_RecursionError.

Tillagd i version 3.6: PyExc_ModuleNotFoundError.

Tillagd i version 3.11: PyExc_BaseExceptionGroup.

OSError-aliaser

Följande är kompatibla alias till PyExc_OSError.

Ändrad i version 3.3: Dessa alias brukade tidigare vara separata undantagstyper.

C-namn	Python-namn	Anteckningar
PyObject *PyExc_EnvironmentError En del av Stabil ABI.	OSError
PyObject *PyExc_IOError En del av Stabil ABI.	OSError
PyObject *PyExc_WindowsError En del av Stabil ABI on Windows sedan version 3.7.	OSError	[win]

Anteckningar:

[win]

PyExc_WindowsError definieras endast på Windows; skydda kod som använder detta genom att testa att preprocessormakrot MS_WINDOWS är definierat.

Typer av varningar

C-namn	Python-namn
PyObject *PyExc_Warning En del av Stabil ABI.	Varning
PyObject *PyExc_BytesWarning En del av Stabil ABI.	BytesWarning
PyObject *PyExc_DeprecationWarning En del av Stabil ABI.	DeprecationWarning
PyObject *PyExc_EncodingWarning En del av Stabil ABI sedan version 3.10.	EncodingWarning
PyObject *PyExc_FutureWarning En del av Stabil ABI.	FutureWarning
PyObject *PyExc_ImportWarning En del av Stabil ABI.	ImportWarning
PyObject *PyExc_PendingDeprecationWarning En del av Stabil ABI.	PendingDeprecationWarning
PyObject *PyExc_ResourceWarning En del av Stabil ABI sedan version 3.7.	ResourceWarning
PyObject *PyExc_RuntimeWarning En del av Stabil ABI.	RuntimeWarning
PyObject *PyExc_SyntaxWarning En del av Stabil ABI.	SyntaxWarning
PyObject *PyExc_UnicodeWarning En del av Stabil ABI.	UnicodeWarning
PyObject *PyExc_UserWarning En del av Stabil ABI.	UserWarning

Tillagd i version 3.2: PyExc_ResourceWarning.

Tillagd i version 3.10: PyExc_EncodingWarning.