異常處理

The functions described in this chapter will let you handle and raise python exceptions. It is important to understand some of the basics of Python exception handling. It works somewhat like the POSIX errno variable: there is a global indicator (per thread) of the last error that occurred. Most C API functions don’t clear this on success, but will set it to indicate the cause of the error on failure. Most C API functions also return an error indicator, usually NULL if they are supposed to return a pointer, or -1 if they return an integer (exception: the PyArg_* functions return 1 for success and 0 for failure).

創(chuàng)新互聯(lián)公司始終堅(jiān)持【策劃先行，效果至上】的經(jīng)營(yíng)理念，通過(guò)多達(dá)十載累計(jì)超上千家客戶的網(wǎng)站建設(shè)總結(jié)了一套系統(tǒng)有效的全網(wǎng)整合營(yíng)銷(xiāo)推廣解決方案，現(xiàn)已廣泛運(yùn)用于各行各業(yè)的客戶，其中包括：成都攪拌罐車(chē)等企業(yè)，備受客戶認(rèn)可。

具體地說(shuō)，錯(cuò)誤指示器由三個(gè)對(duì)象指針組成：異常的類(lèi)型，異常的值，和回溯對(duì)象。如果沒(méi)有錯(cuò)誤被設(shè)置，這些指針都可以是 NULL （盡管一些組合使禁止的，例如，如果異常類(lèi)型是 NULL，你不能有一個(gè)非 NULL 的回溯）。

當(dāng)一個(gè)函數(shù)由于它調(diào)用的某個(gè)函數(shù)失敗而必須失敗時(shí)，通常不會(huì)設(shè)置錯(cuò)誤指示器；它調(diào)用的那個(gè)函數(shù)已經(jīng)設(shè)置了它。而它負(fù)責(zé)處理錯(cuò)誤和清理異常，或在清除其擁有的所有資源后返回（如對(duì)象應(yīng)用或內(nèi)存分配）。如果不準(zhǔn)備處理異常，則 不 應(yīng)該正常地繼續(xù)。如果是由于一個(gè)錯(cuò)誤返回，那么一定要向調(diào)用者表明已經(jīng)設(shè)置了錯(cuò)誤。如果錯(cuò)誤沒(méi)有得到處理或小心傳播，對(duì) Python/C API的其它調(diào)用可能不會(huì)有預(yù)期的行為，并且可能會(huì)以某種神秘的方式失敗。

備注

錯(cuò)誤指示器 不是 sys.exc_info() 的執(zhí)行結(jié)果。前者對(duì)應(yīng)尚未捕獲的異常（異常還在傳播），而后者在捕獲異常后返回這個(gè)異常（異常已經(jīng)停止傳播）。

打印和清理

void PyErr_Clear()

Part of the Stable ABI.

清除錯(cuò)誤指示器。如果沒(méi)有設(shè)置錯(cuò)誤指示器，則不會(huì)有作用。

void PyErr_PrintEx(int set_sys_last_vars)

Part of the Stable ABI.

將標(biāo)準(zhǔn)回溯打印到 sys.stderr 并清除錯(cuò)誤指示器。除非 錯(cuò)誤是 SystemExit，這種情況下不會(huì)打印回溯進(jìn)程，且會(huì)退出 Python 進(jìn)程，并顯示 SystemExit 實(shí)例指定的錯(cuò)誤代碼。

只有在錯(cuò)誤指示器被設(shè)置時(shí)才需要調(diào)用這個(gè)函數(shù)，否則這會(huì)導(dǎo)致錯(cuò)誤！

如果 set_sys_last_vars 非零，則變量 sys.last_type，sys.last_value 和 sys.last_traceback 將分別設(shè)置為打印異常的類(lèi)型，值和回溯。

void PyErr_Print()

Part of the Stable ABI.

PyErr_PrintEx(1) 的別名。

void PyErr_WriteUnraisable(PyObject *obj)

Part of the Stable ABI.

使用當(dāng)前異常和 obj 參數(shù)調(diào)用 sys.unraisablehook()。

當(dāng)設(shè)置了異常，但解釋器不可能實(shí)際地觸發(fā)異常時(shí)，這個(gè)實(shí)用函數(shù)向 sys.stderr 打印一個(gè)警告信息。例如，當(dāng) __del__() 方法中發(fā)生異常時(shí)使用這個(gè)函數(shù)。

該函數(shù)使用單個(gè)參數(shù) obj 進(jìn)行調(diào)用，該參數(shù)標(biāo)識(shí)發(fā)生不可觸發(fā)異常的上下文。如果可能，obj 的報(bào)告將打印在警告消息中。

調(diào)用此函數(shù)時(shí)必須設(shè)置一個(gè)異常。

拋出異常

這些函數(shù)可幫助你設(shè)置當(dāng)前線程的錯(cuò)誤指示器。為了方便起見(jiàn)，一些函數(shù)將始終返回 NULL 指針，以便用于 return 語(yǔ)句。

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

Part of the Stable ABI.

這是設(shè)置錯(cuò)誤標(biāo)記最常用的方式。 第一個(gè)參數(shù)指定異常類(lèi)型；它通常為某個(gè)標(biāo)準(zhǔn)異常，例如 PyExc_RuntimeError。 你不需要增加它的引用計(jì)數(shù)。 第二個(gè)參數(shù)是錯(cuò)誤消息；它是用 'utf-8' 解碼的。

void PyErr_SetObject(PyObject *type, PyObject *value)

Part of the Stable ABI.

此函數(shù)類(lèi)似于 PyErr_SetString()，但是允許你為異常的“值”指定任意一個(gè) Python 對(duì)象。

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

Return value: Always NULL. Part of the Stable ABI.

這個(gè)函數(shù)設(shè)置了一個(gè)錯(cuò)誤指示器并且返回了 NULL，exception 應(yīng)當(dāng)是一個(gè) Python 中的異常類(lèi)。format 和隨后的形參會(huì)幫助格式化這個(gè)錯(cuò)誤的信息；它們與 PyUnicode_FromFormat() 有著相同的含義和值。format 是一個(gè)ASCII編碼的字符串。

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

Return value: Always NULL. Part of the Stable ABI since version 3.5.

和 PyErr_Format() 相同，但它接受一個(gè) va_list 類(lèi)型的參數(shù)而不是可變數(shù)量的參數(shù)集。

3.5 新版功能.

void PyErr_SetNone(PyObject *type)

Part of the Stable ABI.

這是 PyErr_SetObject(type, Py_None) 的簡(jiǎn)寫(xiě)。

int PyErr_BadArgument()

Part of the Stable ABI.

這是 PyErr_SetString(PyExc_TypeError, message) 的簡(jiǎn)寫(xiě)，其中 message 指出使用了非法參數(shù)調(diào)用內(nèi)置操作。它主要用于內(nèi)部使用。

PyObject *PyErr_NoMemory()

Return value: Always NULL. Part of the Stable ABI.

這是 PyErr_SetNone(PyExc_MemoryError) 的簡(jiǎn)寫(xiě)；它返回 NULL ，以便當(dāng)內(nèi)存耗盡時(shí)，對(duì)象分配函數(shù)可以寫(xiě) return PyErr_NoMemory(); 。

PyObject *PyErr_SetFromErrno(PyObject *type)

Return value: Always NULL. Part of the Stable ABI.

這是個(gè)便捷函數(shù)，當(dāng) C 庫(kù)函數(shù)返回錯(cuò)誤并設(shè)置 errno 時(shí)，這個(gè)函數(shù)會(huì)觸發(fā)異常。它構(gòu)造一個(gè)元組對(duì)象，其第一項(xiàng)是整數(shù)值 errno，第二項(xiàng)是相應(yīng)的錯(cuò)誤消息（從 strerror() 獲?。?，然后調(diào)用 PyErr_SetObject(type, object)。在 Unix 上，當(dāng) errno 值是 EINTR ，即中斷的系統(tǒng)調(diào)用時(shí)，這個(gè)函數(shù)會(huì)調(diào)用 PyErr_CheckSignals() ，如果設(shè)置了錯(cuò)誤指示器，則將其設(shè)置為該值。該函數(shù)永遠(yuǎn)返回 NULL ，因此當(dāng)系統(tǒng)調(diào)用返回錯(cuò)誤時(shí)，圍繞系統(tǒng)調(diào)用的包裝函數(shù)可以寫(xiě)成 return PyErr_SetFromErrno(type);。

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

Return value: Always NULL. Part of the Stable ABI.

類(lèi)似于 PyErr_SetFromErrno() ，附加的行為是如果 filenameObject 不為 NULL ，它將作為第三個(gè)參數(shù)傳遞給 type 的構(gòu)造函數(shù)。舉個(gè)例子，在 OSError 異常中，filenameObject 將用來(lái)定義異常實(shí)例的 filename 屬性。

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

Return value: Always NULL. Part of the Stable ABI since version 3.7.

類(lèi)似于 PyErr_SetFromErrnoWithFilenameObject() ，但接受第二個(gè) filename 對(duì)象，用于當(dāng)一個(gè)接受兩個(gè) filename 的函數(shù)失敗時(shí)觸發(fā)錯(cuò)誤。

3.4 新版功能.

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

Return value: Always NULL. Part of the Stable ABI.

類(lèi)似于 PyErr_SetFromErrnoWithFilenameObject()，但文件名以 C 字符串形式給出。 filename 是用 filesystem encoding and error handler 解碼的。

PyObject *PyErr_SetFromWindowsErr(int ierr)

Return value: Always NULL. Part of the Stable ABI on Windows since version 3.7.

This is a convenience function to raise WindowsError. If called with ierr of 0, the error code returned by a call to GetLastError() is used instead. It calls the Win32 function FormatMessage() to retrieve the Windows description of error code given by ierr or GetLastError(), then it constructs a tuple object whose first item is the ierr value and whose second item is the corresponding error message (gotten from FormatMessage()), and then calls PyErr_SetObject(PyExc_WindowsError, object). This function always returns NULL.

可用性: Windows。

PyObject *PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)

Return value: Always NULL. Part of the Stable ABI on Windows since version 3.7.

類(lèi)似于 PyErr_SetFromWindowsErr() ，額外的參數(shù)指定要觸發(fā)的異常類(lèi)型。

可用性: Windows。

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

Return value: Always NULL. Part of the Stable ABI on Windows since version 3.7.

類(lèi)似于 PyErr_SetFromWindowsErrWithFilenameObject() ，但是 filename 是以 C 字符串形式給出的。 filename 是從文件系統(tǒng)編碼（os.fsdecode()）解碼出來(lái)的。

可用性: Windows。

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

Return value: Always NULL. Part of the Stable ABI on Windows since version 3.7.

類(lèi)似于 PyErr_SetFromWindowsErrWithFilenameObject() ，額外參數(shù)指定要觸發(fā)的異常類(lèi)型。

可用性: Windows。

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

Return value: Always NULL. Part of the Stable ABI on Windows since version 3.7.

類(lèi)似于 PyErr_SetExcFromWindowsErrWithFilenameObject() ，但是接受第二個(gè) filename 對(duì)象。

可用性: Windows。

3.4 新版功能.

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

Return value: Always NULL. Part of the Stable ABI on Windows since version 3.7.

類(lèi)似于 PyErr_SetFromWindowsErrWithFilename() ，額外參數(shù)指定要觸發(fā)的異常類(lèi)型。

可用性: Windows。

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

Return value: Always NULL. Part of the Stable ABI since version 3.7.

這是觸發(fā) ImportError 的便捷函數(shù)。 msg 將被設(shè)為異常的消息字符串。 name 和 path ，（都可以為 NULL ），將用來(lái)被設(shè)置 ImportError 對(duì)應(yīng)的屬性 name 和 path。

3.3 新版功能.

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

Return value: Always NULL. Part of the Stable ABI since version 3.6.

和 PyErr_SetImportError() 很類(lèi)似，但這個(gè)函數(shù)允許指定一個(gè) ImportError 的子類(lèi)來(lái)觸發(fā)。

3.6 新版功能.

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

設(shè)置當(dāng)前異常的文件，行和偏移信息。如果當(dāng)前異常不是 SyntaxError ，則它設(shè)置額外的屬性，使異常打印子系統(tǒng)認(rèn)為異常是 SyntaxError。

3.4 新版功能.

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

Part of the Stable ABI since version 3.7.

類(lèi)似于 PyErr_SyntaxLocationObject()，但 filename 是用 filesystem encoding and error handler 解碼的字節(jié)串。

3.2 新版功能.

void PyErr_SyntaxLocation(const char *filename, int lineno)

Part of the Stable ABI.

類(lèi)似于 PyErr_SyntaxLocationEx()，但省略了 col_offset parameter 形參。

void PyErr_BadInternalCall()

Part of the Stable ABI.

這是 PyErr_SetString(PyExc_SystemError, message) 的縮寫(xiě)，其中 message 表示使用了非法參數(shù)調(diào)用內(nèi)部操作（例如，Python/C API 函數(shù)）。它主要用于內(nèi)部使用。

發(fā)出警告

這些函數(shù)可以從 C 代碼中發(fā)出警告。它們仿照了由 Python 模塊 warnings 導(dǎo)出的那些函數(shù)。它們通常向 sys.stderr 打印一條警告信息；當(dāng)然，用戶也有可能已經(jīng)指定將警告轉(zhuǎn)換為錯(cuò)誤，在這種情況下，它們將觸發(fā)異常。也有可能由于警告機(jī)制出現(xiàn)問(wèn)題，使得函數(shù)觸發(fā)異常。如果沒(méi)有觸發(fā)異常，返回值為 0 ；如果觸發(fā)異常，返回值為 -1。（無(wú)法確定是否實(shí)際打印了警告信息，也無(wú)法確定異常觸發(fā)的原因。這是故意為之）。如果觸發(fā)了異常，調(diào)用者應(yīng)該進(jìn)行正常的異常處理（例如，Py_DECREF() 持有引用并返回一個(gè)錯(cuò)誤值）。

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

Part of the Stable ABI.

發(fā)出一個(gè)警告信息。參數(shù) category 是一個(gè)警告類(lèi)別（見(jiàn)下面）或 NULL ； message 是一個(gè) UTF-8 編碼的字符串。 stack_level 是一個(gè)給出棧幀數(shù)量的正數(shù)；警告將從該棧幀中當(dāng)前正在執(zhí)行的代碼行發(fā)出。 stack_level 為 1 的是調(diào)用 PyErr_WarnEx() 的函數(shù)，2 是在此之上的函數(shù)，以此類(lèi)推。

警告類(lèi)別必須是 PyExc_Warning 的子類(lèi)， PyExc_Warning 是 PyExc_Exception 的子類(lèi)；默認(rèn)警告類(lèi)別是 PyExc_RuntimeWarning 。標(biāo)準(zhǔn) Python 警告類(lèi)別作為全局變量可用，所有其名稱見(jiàn) 標(biāo)準(zhǔn)警告類(lèi)別 。

有關(guān)警告控制的信息，參見(jiàn)模塊文檔 warnings 和命令行文檔中的 -W 選項(xiàng)。沒(méi)有用于警告控制的 C API。

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

發(fā)出一個(gè)對(duì)所有警告屬性進(jìn)行顯式控制的警告消息。 這是位于 Python 函數(shù) warnings.warn_explicit() 外層的直接包裝；請(qǐng)查看其文檔了解詳情。 module 和 registry 參數(shù)可被設(shè)為 NULL 以得到相關(guān)文檔所描述的默認(rèn)效果。

3.4 新版功能.

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

Part of the Stable ABI.

類(lèi)似于 PyErr_WarnExplicitObject() 不過(guò) message 和 module 是 UTF-8 編碼的字符串，而 filename 是由 filesystem encoding and error handler 解碼的。

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

Part of the Stable ABI.

類(lèi)似于 PyErr_WarnEx() 的函數(shù)，但使用 PyUnicode_FromFormat() 來(lái)格式化警告消息。 format 是使用 ASCII 編碼的字符串。

3.2 新版功能.

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

Part of the Stable ABI since version 3.6.

類(lèi)似于 PyErr_WarnFormat() 的函數(shù)，但 category 是 ResourceWarning 并且它會(huì)將 source 傳給 warnings.WarningMessage()。

3.6 新版功能.

查詢錯(cuò)誤指示器

PyObject *PyErr_Occurred()

Return value: Borrowed reference. Part of the Stable ABI.

Test whether the error indicator is set. If set, return the exception type (the first argument to the last call to one of the PyErr_Set* functions or to PyErr_Restore()). If not set, return NULL. You do not own a reference to the return value, so you do not need to Py_DECREF() it.

呼叫者必須持有GIL。

備注

不要將返回值與特定的異常進(jìn)行比較；請(qǐng)改為使用 PyErr_ExceptionMatches()，如下所示。 （比較很容易失敗因?yàn)閷?duì)于類(lèi)異常來(lái)說(shuō)，異?？赡苁且粋€(gè)實(shí)例而不是類(lèi)，或者它可能是預(yù)期的異常的一個(gè)子類(lèi)。）

int PyErr_ExceptionMatches(PyObject *exc)

Part of the Stable ABI.

等價(jià)于 PyErr_GivenExceptionMatches(PyErr_Occurred(), exc)。 此函數(shù)應(yīng)當(dāng)只在實(shí)際設(shè)置了異常時(shí)才被調(diào)用；如果沒(méi)有任何異常被引發(fā)則將發(fā)生非法內(nèi)存訪問(wèn)。

int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)

Part of the Stable ABI.

如果 given 異常與 exc 中的異常類(lèi)型相匹配則返回真值。 如果 exc 是一個(gè)類(lèi)對(duì)象，則當(dāng) given 是一個(gè)子類(lèi)的實(shí)例時(shí)也將返回真值。 如果 exc 是一個(gè)元組，則該元組（以及遞歸的子元組）中的所有異常類(lèi)型都將被搜索進(jìn)行匹配。

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

Part of the Stable ABI.

將錯(cuò)誤指示符提取到三個(gè)變量中并傳遞其地址。 如果未設(shè)置錯(cuò)誤指示符，則將三個(gè)變量都設(shè)為 NULL。 如果已設(shè)置，則將其清除并且你將得到對(duì)所提取的每個(gè)對(duì)象的引用。 值和回溯對(duì)象可以為 NULL 即使類(lèi)型對(duì)象不為空。

備注

此函數(shù)通常只被需要捕獲異常的代碼或需要臨時(shí)保存和恢復(fù)錯(cuò)誤指示符的代碼所使用，例如:

 
 
 
 

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

Part of the Stable ABI.

基于三個(gè)對(duì)象設(shè)置錯(cuò)誤指示符。 如果錯(cuò)誤指示符已設(shè)置，它將首先被清除。 如果三個(gè)對(duì)象均為 NULL，錯(cuò)誤指示器將被清除。 請(qǐng)不要傳入 NULL 類(lèi)型和非 NULL 值或回溯。 異常類(lèi)型應(yīng)當(dāng)是一個(gè)類(lèi)。 請(qǐng)不要傳入無(wú)效的異常類(lèi)型或值。 （違反這些規(guī)則將導(dǎo)致微妙的后續(xù)問(wèn)題。） 此調(diào)用會(huì)帶走對(duì)每個(gè)對(duì)象的引用：你必須在調(diào)用之前擁有對(duì)每個(gè)對(duì)象的引用且在調(diào)用之后你將不再擁有這些引用。 （如果你不理解這一點(diǎn)，就不要使用此函數(shù)。 勿謂言之不預(yù)。）

備注

此函數(shù)通常只被需要臨時(shí)保存和恢復(fù)錯(cuò)誤指示符的代碼所使用。 請(qǐng)使用 PyErr_Fetch() 來(lái)保存當(dāng)前的錯(cuò)誤指示符。

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

Part of the Stable ABI.

在特定情況下，下面 PyErr_Fetch() 所返回的值可以是“非正規(guī)化的”，即 *exc 是一個(gè)類(lèi)對(duì)象而 *val 不是同一個(gè)類(lèi)的實(shí)例。 在這種情況下此函數(shù)可以被用來(lái)實(shí)例化類(lèi)。 如果值已經(jīng)是正規(guī)化的，則不做任何操作。 實(shí)現(xiàn)這種延遲正規(guī)化是為了提升性能。

備注

此函數(shù) 不會(huì) 顯式地在異常值上設(shè)置 __traceback__ 屬性。 如果想要適當(dāng)?shù)卦O(shè)置回溯，還需要以下附加代碼片段:

 
 
 
 

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

PyObject *PyErr_GetHandledException(void)

Part of the Stable ABI since version 3.11.

Retrieve the active exception instance, as would be returned by sys.exception(). This refers to an exception that was already caught, not to an exception that was freshly raised. Returns a new reference to the exception or NULL. Does not modify the interpreter’s exception state.

備注

This function is not normally used by code that wants to handle exceptions. Rather, it can be used when code needs to save and restore the exception state temporarily. Use PyErr_SetHandledException() to restore or clear the exception state.

3.11 新版功能.

void PyErr_SetHandledException(PyObject *exc)

Part of the Stable ABI since version 3.11.

Set the active exception, as known from sys.exception(). This refers to an exception that was already caught, not to an exception that was freshly raised. To clear the exception state, pass NULL.

備注

This function is not normally used by code that wants to handle exceptions. Rather, it can be used when code needs to save and restore the exception state temporarily. Use PyErr_GetHandledException() to get the exception state.

3.11 新版功能.

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

Part of the Stable ABI since version 3.7.

Retrieve the old-style representation of the exception info, as known from sys.exc_info(). This refers to an exception that was already caught, not to an exception that was freshly raised. Returns new references for the three objects, any of which may be NULL. Does not modify the exception info state. This function is kept for backwards compatibility. Prefer using PyErr_GetHandledException().

備注

此函數(shù)通常不會(huì)被需要處理異常的代碼所使用。 它被使用的場(chǎng)合是在代碼需要臨時(shí)保存并恢復(fù)異常狀態(tài)的時(shí)候。 請(qǐng)使用 PyErr_SetExcInfo() 來(lái)恢復(fù)或清除異常狀態(tài)。

3.3 新版功能.

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

Part of the Stable ABI since version 3.7.

Set the exception info, as known from sys.exc_info(). This refers to an exception that was already caught, not to an exception that was freshly raised. This function steals the references of the arguments. To clear the exception state, pass NULL for all three arguments. This function is kept for backwards compatibility. Prefer using PyErr_SetHandledException().

備注

此函數(shù)通常不會(huì)被需要處理異常的代碼所使用。 它被使用的場(chǎng)合是在代碼需要臨時(shí)保存并恢復(fù)異常狀態(tài)的情況。 請(qǐng)使用 PyErr_GetExcInfo() 來(lái)讀取異常狀態(tài)。

3.3 新版功能.

在 3.11 版更改: The type and traceback arguments are no longer used and can be NULL. The interpreter now derives them from the exception instance (the value argument). The function still steals references of all three arguments.

信號(hào)處理

int PyErr_CheckSignals()

Part of the Stable ABI.

這個(gè)函數(shù)與Python的信號(hào)處理交互。

如果在主 Python 解釋器下從主線程調(diào)用該函數(shù)，它將檢查是否向進(jìn)程發(fā)送了信號(hào)，如果是，則發(fā)起調(diào)用相應(yīng)的信號(hào)處理句柄。 如果支持 signal 模塊，則可以發(fā)起調(diào)用以 Python 編寫(xiě)的信號(hào)處理句柄。

該函數(shù)會(huì)嘗試處理所有待處理信號(hào)，然后返回 0。 但是，如果 Python 信號(hào)處理句柄引發(fā)了異常，則設(shè)置錯(cuò)誤指示符并且函數(shù)將立即返回 -1 (這樣其他待處理信號(hào)可能還沒(méi)有被處理：它們將在下次發(fā)起調(diào)用 PyErr_CheckSignals() 時(shí)被處理)。

如果函數(shù)從非主線程調(diào)用，或在非主Python解釋器下調(diào)用，則它不執(zhí)行任何操作并返回0。

這個(gè)函數(shù)可以由希望被用戶請(qǐng)求(例如按Ctrl-C)中斷的長(zhǎng)時(shí)間運(yùn)行的C代碼調(diào)用。

備注

針對(duì) SIGINT 的默認(rèn) Python 信號(hào)處理句柄會(huì)引發(fā) KeyboardInterrupt 異常。

void PyErr_SetInterrupt()

Part of the Stable ABI.

模擬一個(gè) SIGINT 信號(hào)到達(dá)的效果。 這等價(jià)于 PyErr_SetInterruptEx(SIGINT)。

備注

此函數(shù)是異步信號(hào)安全的。 它可以不帶 GIL 并由 C 信號(hào)處理句柄來(lái)調(diào)用。

int PyErr_SetInterruptEx(int signum)

Part of the Stable ABI since version 3.10.

模擬一個(gè)信號(hào)到達(dá)的效果。 當(dāng)下次 PyErr_CheckSignals() 被調(diào)用時(shí)，將會(huì)調(diào)用針對(duì)指定的信號(hào)編號(hào)的 Python 信號(hào)處理句柄。

此函數(shù)可由自行設(shè)置信號(hào)處理，并希望 Python 信號(hào)處理句柄會(huì)在請(qǐng)求中斷時(shí)（例如當(dāng)用戶按下 Ctrl-C 來(lái)中斷操作時(shí)）按照預(yù)期被發(fā)起調(diào)用的 C 代碼來(lái)調(diào)用。

如果給定的信號(hào)不是由 Python 來(lái)處理的 (即被設(shè)為 signal.SIG_DFL 或 signal.SIG_IGN)，它將會(huì)被忽略。

如果 signum 在被允許的信號(hào)編號(hào)范圍之外，將返回 -1。 在其他情況下，則返回 0。 錯(cuò)誤指示符絕不會(huì)被此函數(shù)所修改。

備注

此函數(shù)是異步信號(hào)安全的。 它可以不帶 GIL 并由 C 信號(hào)處理句柄來(lái)調(diào)用。

3.10 新版功能.

int PySignal_SetWakeupFd(int fd)

這個(gè)工具函數(shù)指定了一個(gè)每當(dāng)收到信號(hào)時(shí)將被作為以單個(gè)字節(jié)的形式寫(xiě)入信號(hào)編號(hào)的目標(biāo)的文件描述符。 fd 必須是非阻塞的。 它將返回前一個(gè)這樣的文件描述符。

設(shè)置值 -1 將禁用該特性；這是初始狀態(tài)。 這等價(jià)于 Python 中的 signal.set_wakeup_fd()，但是沒(méi)有任何錯(cuò)誤檢查。 fd 應(yīng)當(dāng)是一個(gè)有效的文件描述符。 此函數(shù)應(yīng)當(dāng)只從主線程來(lái)調(diào)用。

在 3.5 版更改: 在 Windows 上，此函數(shù)現(xiàn)在也支持套接字處理。

Exception 類(lèi)

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

Return value: New reference. Part of the Stable ABI.

這個(gè)工具函數(shù)會(huì)創(chuàng)建并返回一個(gè)新的異常類(lèi)。 name 參數(shù)必須為新異常的名稱，是 module.classname 形式的 C 字符串。 base 和 dict 參數(shù)通常為 NULL。 這將創(chuàng)建一個(gè)派生自 Exception 的類(lèi)對(duì)象（在 C 中可以通過(guò) PyExc_Exception 訪問(wèn)）。

新類(lèi)的 __module__ 屬性將被設(shè)為 name 參數(shù)的前半部分（最后一個(gè)點(diǎn)號(hào)之前），而類(lèi)名將被設(shè)為后半部分（最后一個(gè)點(diǎn)號(hào)之后）。 base 參數(shù)可被用來(lái)指定替代基類(lèi)；它可以是一個(gè)類(lèi)或是一個(gè)由類(lèi)組成的元組。 dict 參數(shù)可被用來(lái)指定一個(gè)由類(lèi)變量和方法組成的字典。

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

Return value: New reference. Part of the Stable ABI.

和 PyErr_NewException() 一樣，除了可以輕松地給新的異常類(lèi)一個(gè)文檔字符串：如果 doc 屬性非空，它將用作異常類(lèi)的文檔字符串。

3.2 新版功能.

異常對(duì)象

PyObject *PyException_GetTraceback(PyObject *ex)

Return value: New reference. Part of the Stable ABI.

將與異常相關(guān)聯(lián)的回溯作為一個(gè)新引用返回，可以通過(guò) __traceback__ 在 Python 中訪問(wèn)。 如果沒(méi)有已關(guān)聯(lián)的回溯，則返回 NULL。

int PyException_SetTraceback(PyObject *ex, PyObject *tb)

Part of the Stable ABI.

將異常關(guān)聯(lián)的回溯設(shè)置為 tb 。使用``Py_None``清除它。

PyObject *PyException_GetContext(PyObject *ex)

Return value: New reference. Part of the Stable ABI.

將與異常相關(guān)聯(lián)的上下文（在處理 ex 的過(guò)程中引發(fā)的另一個(gè)異常實(shí)例）作為一個(gè)新引用返回，可以通過(guò) __context__ 在 Python 中訪問(wèn)。 如果沒(méi)有已關(guān)聯(lián)的上下文，則返回 NULL。

void PyException_SetContext(PyObject *ex, PyObject *ctx)

Part of the Stable ABI.

將與異常相關(guān)聯(lián)的上下文設(shè)置為 ctx。 使用 NULL 來(lái)清空它。 沒(méi)有用來(lái)確保 ctx 是一個(gè)異常實(shí)例的類(lèi)型檢查。 這將竊取一個(gè)指向 ctx 的引用。

PyObject *PyException_GetCause(PyObject *ex)

Return value: New reference. Part of the Stable ABI.

將與異常相關(guān)聯(lián)的原因（一個(gè)異常實(shí)例，或是 None，由 raise ... from ... 設(shè)置）作為一個(gè)新引用返回，可在 Python 中通過(guò) __cause__ 來(lái)訪問(wèn)。

void PyException_SetCause(PyObject *ex, PyObject *cause)

Part of the Stable ABI.

將與異常相關(guān)聯(lián)的原因設(shè)置為 cause。 使用 NULL 來(lái)清空它。 它沒(méi)有用來(lái)確保 cause 是一個(gè)異常實(shí)例或 None 的類(lèi)型檢查。 這將偷取一個(gè)指向 cause 的引用。

__suppress_context__ 會(huì)被此函數(shù)隱式地設(shè)為 True。

Unicode 異常對(duì)象

下列函數(shù)被用于創(chuàng)建和修改來(lái)自 C 的 Unicode 異常。

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

Return value: New reference. Part of the Stable ABI.

創(chuàng)建一個(gè) UnicodeDecodeError 對(duì)象并附帶 encoding, object, length, start, end 和 reason 等屬性。 encoding 和 reason 為 UTF-8 編碼的字符串。

PyObject *PyUnicodeDecodeError_GetEncoding(PyObject *exc)

PyObject *PyUnicodeEncodeError_GetEncoding(PyObject *exc)

Return value: New reference. Part of the Stable ABI.

返回給定異常對(duì)象的 encoding 屬性

PyObject *PyUnicodeDecodeError_GetObject(PyObject *exc)

PyObject *PyUnicodeEncodeError_GetObject(PyObject *exc)

PyObject *PyUnicodeTranslateError_GetObject(PyObject *exc)

Return value: New reference. Part of the Stable ABI.

返回給定異常對(duì)象的 object 屬性

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)

Part of the Stable ABI.

獲取給定異常對(duì)象的 start 屬性并將其放入 \start。 start* 必須不為 NULL。 成功時(shí)返回 0，失敗時(shí)返回 -1。

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)

Part of the Stable ABI.

將給定異常對(duì)象的 start 屬性設(shè)為 start。 成功時(shí)返回 0，失敗時(shí)返回 -1。

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)

Part of the Stable ABI.

獲取給定異常對(duì)象的 end 屬性并將其放入 \end。 end* 必須不為 NULL。 成功時(shí)返回 0，失敗時(shí)返回 -1。

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)

Part of the Stable ABI.

將給定異常對(duì)象的 end 屬性設(shè)為 end。 成功時(shí)返回 0，失敗時(shí)返回 -1。

PyObject *PyUnicodeDecodeError_GetReason(PyObject *exc)

PyObject *PyUnicodeEncodeError_GetReason(PyObject *exc)

PyObject *PyUnicodeTranslateError_GetReason(PyObject *exc)

Return value: New reference. Part of the Stable ABI.

返回給定異常對(duì)象的 reason 屬性

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

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

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

Part of the Stable ABI.

將給定異常對(duì)象的 reason 屬性設(shè)為 reason。 成功時(shí)返回 0，失敗時(shí)返回 -1。

遞歸控制

這兩個(gè)函數(shù)提供了一種在 C 層級(jí)上進(jìn)行安全的遞歸調(diào)用的方式，在核心模塊與擴(kuò)展模塊中均適用。 當(dāng)遞歸代碼不一定會(huì)發(fā)起調(diào)用 Python 代碼（后者會(huì)自動(dòng)跟蹤其遞歸深度）時(shí)就需要用到它們。 它們對(duì)于 tp_call 實(shí)現(xiàn)來(lái)說(shuō)也無(wú)必要因?yàn)?調(diào)用協(xié)議 會(huì)負(fù)責(zé)遞歸處理。

int Py_EnterRecursiveCall(const char *where)

Part of the Stable ABI since version 3.9.

標(biāo)記一個(gè)遞歸的 C 層級(jí)調(diào)用即將被執(zhí)行的點(diǎn)位。

如果定義了 USE_STACKCHECK，此函數(shù)會(huì)使用 PyOS_CheckStack() 來(lái)檢查操作系統(tǒng)堆棧是否溢出。 在這種情況下，它將設(shè)置一個(gè) MemoryError 并返回非零值。

隨后此函數(shù)將檢查是否達(dá)到遞歸限制。 如果是的話，將設(shè)置一個(gè) RecursionError 并返回一個(gè)非零值。 在其他情況下，則返回零。

where 應(yīng)為一個(gè) UTF-8 編碼的字符串如 " in instance check"，它將與由遞歸深度限制所導(dǎo)致的 RecursionError 消息相拼接。

在 3.9 版更改: 此函數(shù)現(xiàn)在也在受限 API 中可用。

void Py_LeaveRecursiveCall(void)

Part of the Stable ABI since version 3.9.

結(jié)束一個(gè) Py_EnterRecursiveCall()。 必須針對(duì) Py_EnterRecursiveCall() 的每個(gè) 成功的 發(fā)起調(diào)用操作執(zhí)行一次調(diào)用。

在 3.9 版更改: 此函數(shù)現(xiàn)在也在受限 API 中可用。

正確地針對(duì)容器類(lèi)型實(shí)現(xiàn) tp_repr 需要特別的遞歸處理。 在保護(hù)棧之外，tp_repr 還需要追蹤對(duì)象以防止出現(xiàn)循環(huán)。 以下兩個(gè)函數(shù)將幫助完成此功能。 從實(shí)際效果來(lái)說(shuō)，這兩個(gè)函數(shù)是 C 中對(duì)應(yīng) reprlib.recursive_repr() 的等價(jià)物。

int Py_ReprEnter(PyObject *object)

Part of the Stable ABI.

在 tp_repr 實(shí)現(xiàn)的開(kāi)頭被調(diào)用以檢測(cè)循環(huán)。

如果對(duì)象已經(jīng)被處理，此函數(shù)將返回一個(gè)正整數(shù)。 在此情況下 tp_repr 實(shí)現(xiàn)應(yīng)當(dāng)返回一個(gè)指明發(fā)生循環(huán)的字符串對(duì)象。 例如，dict 對(duì)象將返回 {...} 而 list 對(duì)象將返回 [...]。

如果已達(dá)到遞歸限制則此函數(shù)將返回一個(gè)負(fù)正數(shù)。 在此情況下 tp_repr 實(shí)現(xiàn)通常應(yīng)當(dāng)返回 NULL。

在其他情況下，此函數(shù)將返回零而 tp_repr 實(shí)現(xiàn)將可正常繼續(xù)。

void Py_ReprLeave(PyObject *object)

Part of the Stable ABI.

結(jié)束一個(gè) Py_ReprEnter()。 必須針對(duì)每個(gè)返回零的 Py_ReprEnter() 的發(fā)起調(diào)用操作調(diào)用一次。

標(biāo)準(zhǔn)異常

All standard Python exceptions are available as global variables whose names are PyExc_ followed by the Python exception name. These have the type PyObject*; they are all class objects. For completeness, here are all the variables:

C 名稱	Python 名稱	備注
PyExc_BaseException	BaseException	1
PyExc_Exception	Exception	1
PyExc_ArithmeticError	ArithmeticError	1
PyExc_AssertionError	AssertionError
PyExc_AttributeError	AttributeError
PyExc_BlockingIOError	BlockingIOError
PyExc_BrokenPipeError	BrokenPipeError
PyExc_BufferError	BufferError
PyExc_ChildProcessError	ChildProcessError
PyExc_ConnectionAbortedError	ConnectionAbortedError
PyExc_ConnectionError	ConnectionError
PyExc_ConnectionRefusedError	ConnectionRefusedError
PyExc_ConnectionResetError	ConnectionResetError
PyExc_EOFError	EOFError
PyExc_FileExistsError	FileExistsError
PyExc_FileNotFoundError	FileNotFoundError
PyExc_FloatingPointError	FloatingPointError
PyExc_GeneratorExit	GeneratorExit
PyExc_ImportError	ImportError
PyExc_IndentationError	IndentationError
PyExc_IndexError	IndexError
PyExc_InterruptedError	InterruptedError
PyExc_IsADirectoryError	IsADirectoryError
PyExc_KeyError	KeyError
PyExc_KeyboardInterrupt	KeyboardInterrupt
PyExc_LookupError	LookupError	1
PyExc_MemoryError	MemoryError
PyExc_ModuleNotFoundError	ModuleNotFoundError
PyExc_NameError	NameError
PyExc_NotADirectoryError	NotADirectoryError
PyExc_NotImplementedError	NotImplementedError
PyExc_OSError	OSError	1
PyExc_OverflowError	OverflowError
PyExc_PermissionError	PermissionError
PyExc_ProcessLookupError	ProcessLookupError
PyExc_RecursionError	RecursionError
PyExc_ReferenceError	ReferenceError
PyExc_RuntimeError	RuntimeError
PyExc_StopAsyncIteration	StopAsyncIteration
PyExc_StopIteration	StopIteration
PyExc_SyntaxError	SyntaxError
PyExc_SystemError	SystemError
PyExc_SystemExit	SystemExit
PyExc_TabError	TabError
PyExc_TimeoutError	TimeoutError
PyExc_TypeError	TypeError
PyExc_UnboundLocalError	UnboundLocalError
PyExc_UnicodeDecodeError	UnicodeDecodeError
PyExc_UnicodeEncodeError	UnicodeEncodeError
PyExc_UnicodeError	UnicodeError
PyExc_UnicodeTranslateError	UnicodeTranslateError
PyExc_ValueError	ValueError
PyExc_ZeroDivisionError	ZeroDivisionError

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 and PyExc_TimeoutError 介紹如下 PEP 3151.

3.5 新版功能: PyExc_StopAsyncIteration 和 PyExc_RecursionError.

3.6 新版功能: PyExc_ModuleNotFoundError.

這些是兼容性別名 PyExc_OSError:

C 名稱	備注
PyExc_EnvironmentError
PyExc_IOError
PyExc_WindowsError	2

在 3.3 版更改: 這些別名曾經(jīng)是單獨(dú)的異常類(lèi)型。

注：

1(1,2,3,4,5)

這是其他標(biāo)準(zhǔn)異常的基類(lèi)。

2

僅在 Windows 中定義；檢測(cè)是否定義了預(yù)處理程序宏 MS_WINDOWS ，以便保護(hù)用到它的代碼。

標(biāo)準(zhǔn)警告類(lèi)別

All standard Python warning categories are available as global variables whose names are PyExc_ followed by the Python exception name. These have the type PyObject*; they are all class objects. For completeness, here are all the variables:

C 名稱	Python 名稱	備注
PyExc_Warning	Warning	3
PyExc_BytesWarning	BytesWarning
PyExc_DeprecationWarning	DeprecationWarning
PyExc_FutureWarning	FutureWarning
PyExc_ImportWarning	ImportWarning
PyExc_PendingDeprecationWarning	PendingDeprecationWarning
PyExc_ResourceWarning	ResourceWarning
PyExc_RuntimeWarning	RuntimeWarning
PyExc_SyntaxWarning	SyntaxWarning
PyExc_UnicodeWarning	UnicodeWarning
PyExc_UserWarning	UserWarning

3.2 新版功能: PyExc_ResourceWarning.

注：

3

這是其他標(biāo)準(zhǔn)警告類(lèi)別的基類(lèi)。

當(dāng)前題目：創(chuàng)新互聯(lián)Python教程：異常處理
分享路徑：http://www.5511xx.com/article/dpgchgi.html