異常處理

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)公司始終堅持【策劃先行，效果至上】的經(jīng)營理念，通過多達十載累計超上千家客戶的網(wǎng)站建設總結(jié)了一套系統(tǒng)有效的全網(wǎng)整合營銷推廣解決方案，現(xiàn)已廣泛運用于各行各業(yè)的客戶，其中包括：成都攪拌罐車等企業(yè)，備受客戶認可。

具體地說，錯誤指示器由三個對象指針組成：異常的類型，異常的值，和回溯對象。如果沒有錯誤被設置，這些指針都可以是 NULL （盡管一些組合使禁止的，例如，如果異常類型是 NULL，你不能有一個非 NULL 的回溯）。

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

備注

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

打印和清理

void PyErr_Clear()

Part of the Stable ABI.

清除錯誤指示器。如果沒有設置錯誤指示器，則不會有作用。

void PyErr_PrintEx(int set_sys_last_vars)

Part of the Stable ABI.

將標準回溯打印到 sys.stderr 并清除錯誤指示器。除非 錯誤是 SystemExit，這種情況下不會打印回溯進程，且會退出 Python 進程，并顯示 SystemExit 實例指定的錯誤代碼。

只有在錯誤指示器被設置時才需要調(diào)用這個函數(shù)，否則這會導致錯誤！

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

void PyErr_Print()

Part of the Stable ABI.

PyErr_PrintEx(1) 的別名。

void PyErr_WriteUnraisable(PyObject *obj)

Part of the Stable ABI.

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

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

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

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

拋出異常

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

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

Part of the Stable ABI.

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

void PyErr_SetObject(PyObject *type, PyObject *value)

Part of the Stable ABI.

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

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

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

這個函數(shù)設置了一個錯誤指示器并且返回了 NULL，exception 應當是一個 Python 中的異常類。format 和隨后的形參會幫助格式化這個錯誤的信息；它們與 PyUnicode_FromFormat() 有著相同的含義和值。format 是一個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() 相同，但它接受一個 va_list 類型的參數(shù)而不是可變數(shù)量的參數(shù)集。

3.5 新版功能.

void PyErr_SetNone(PyObject *type)

Part of the Stable ABI.

這是 PyErr_SetObject(type, Py_None) 的簡寫。

int PyErr_BadArgument()

Part of the Stable ABI.

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

PyObject *PyErr_NoMemory()

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

這是 PyErr_SetNone(PyExc_MemoryError) 的簡寫；它返回 NULL ，以便當內(nèi)存耗盡時，對象分配函數(shù)可以寫 return PyErr_NoMemory(); 。

PyObject *PyErr_SetFromErrno(PyObject *type)

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

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

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

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

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

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

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

類似于 PyErr_SetFromErrnoWithFilenameObject() ，但接受第二個 filename 對象，用于當一個接受兩個 filename 的函數(shù)失敗時觸發(fā)錯誤。

3.4 新版功能.

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

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

類似于 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.

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

可用性: Windows。

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

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

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

可用性: 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.

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

可用性: 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.

類似于 PyErr_SetExcFromWindowsErrWithFilenameObject() ，但是接受第二個 filename 對象。

可用性: 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.

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

可用性: 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 將被設為異常的消息字符串。 name 和 path ，（都可以為 NULL ），將用來被設置 ImportError 對應的屬性 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() 很類似，但這個函數(shù)允許指定一個 ImportError 的子類來觸發(fā)。

3.6 新版功能.

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

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

3.4 新版功能.

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

Part of the Stable ABI since version 3.7.

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

3.2 新版功能.

void PyErr_SyntaxLocation(const char *filename, int lineno)

Part of the Stable ABI.

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

void PyErr_BadInternalCall()

Part of the Stable ABI.

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

發(fā)出警告

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

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

Part of the Stable ABI.

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

警告類別必須是 PyExc_Warning 的子類， PyExc_Warning 是 PyExc_Exception 的子類；默認警告類別是 PyExc_RuntimeWarning 。標準 Python 警告類別作為全局變量可用，所有其名稱見 標準警告類別 。

有關警告控制的信息，參見模塊文檔 warnings 和命令行文檔中的 -W 選項。沒有用于警告控制的 C API。

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

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

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.

類似于 PyErr_WarnExplicitObject() 不過 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.

類似于 PyErr_WarnEx() 的函數(shù)，但使用 PyUnicode_FromFormat() 來格式化警告消息。 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.

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

3.6 新版功能.

查詢錯誤指示器

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。

備注

不要將返回值與特定的異常進行比較；請改為使用 PyErr_ExceptionMatches()，如下所示。 （比較很容易失敗因為對于類異常來說，異?？赡苁且粋€實例而不是類，或者它可能是預期的異常的一個子類。）

int PyErr_ExceptionMatches(PyObject *exc)

Part of the Stable ABI.

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

int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)

Part of the Stable ABI.

如果 given 異常與 exc 中的異常類型相匹配則返回真值。 如果 exc 是一個類對象，則當 given 是一個子類的實例時也將返回真值。 如果 exc 是一個元組，則該元組（以及遞歸的子元組）中的所有異常類型都將被搜索進行匹配。

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

Part of the Stable ABI.

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

備注

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

 
 
 
 

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

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

備注

此函數(shù)通常只被需要臨時保存和恢復錯誤指示符的代碼所使用。 請使用 PyErr_Fetch() 來保存當前的錯誤指示符。

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

Part of the Stable ABI.

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

備注

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

 
 
 
 

  
  
  
  
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ù)通常不會被需要處理異常的代碼所使用。 它被使用的場合是在代碼需要臨時保存并恢復異常狀態(tài)的時候。 請使用 PyErr_SetExcInfo() 來恢復或清除異常狀態(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ù)通常不會被需要處理異常的代碼所使用。 它被使用的場合是在代碼需要臨時保存并恢復異常狀態(tài)的情況。 請使用 PyErr_GetExcInfo() 來讀取異常狀態(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.

信號處理

int PyErr_CheckSignals()

Part of the Stable ABI.

這個函數(shù)與Python的信號處理交互。

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

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

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

這個函數(shù)可以由希望被用戶請求(例如按Ctrl-C)中斷的長時間運行的C代碼調(diào)用。

備注

針對 SIGINT 的默認 Python 信號處理句柄會引發(fā) KeyboardInterrupt 異常。

void PyErr_SetInterrupt()

Part of the Stable ABI.

模擬一個 SIGINT 信號到達的效果。 這等價于 PyErr_SetInterruptEx(SIGINT)。

備注

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

int PyErr_SetInterruptEx(int signum)

Part of the Stable ABI since version 3.10.

模擬一個信號到達的效果。 當下次 PyErr_CheckSignals() 被調(diào)用時，將會調(diào)用針對指定的信號編號的 Python 信號處理句柄。

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

如果給定的信號不是由 Python 來處理的 (即被設為 signal.SIG_DFL 或 signal.SIG_IGN)，它將會被忽略。

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

備注

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

3.10 新版功能.

int PySignal_SetWakeupFd(int fd)

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

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

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

Exception 類

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

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

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

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

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

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

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

3.2 新版功能.

異常對象

PyObject *PyException_GetTraceback(PyObject *ex)

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

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

int PyException_SetTraceback(PyObject *ex, PyObject *tb)

Part of the Stable ABI.

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

PyObject *PyException_GetContext(PyObject *ex)

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

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

void PyException_SetContext(PyObject *ex, PyObject *ctx)

Part of the Stable ABI.

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

PyObject *PyException_GetCause(PyObject *ex)

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

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

void PyException_SetCause(PyObject *ex, PyObject *cause)

Part of the Stable ABI.

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

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

Unicode 異常對象

下列函數(shù)被用于創(chuàng)建和修改來自 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)建一個 UnicodeDecodeError 對象并附帶 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.

返回給定異常對象的 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.

返回給定異常對象的 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.

獲取給定異常對象的 start 屬性并將其放入 \start。 start* 必須不為 NULL。 成功時返回 0，失敗時返回 -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.

將給定異常對象的 start 屬性設為 start。 成功時返回 0，失敗時返回 -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.

獲取給定異常對象的 end 屬性并將其放入 \end。 end* 必須不為 NULL。 成功時返回 0，失敗時返回 -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.

將給定異常對象的 end 屬性設為 end。 成功時返回 0，失敗時返回 -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.

返回給定異常對象的 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.

將給定異常對象的 reason 屬性設為 reason。 成功時返回 0，失敗時返回 -1。

遞歸控制

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

int Py_EnterRecursiveCall(const char *where)

Part of the Stable ABI since version 3.9.

標記一個遞歸的 C 層級調(diào)用即將被執(zhí)行的點位。

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

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

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

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

void Py_LeaveRecursiveCall(void)

Part of the Stable ABI since version 3.9.

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

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

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

int Py_ReprEnter(PyObject *object)

Part of the Stable ABI.

在 tp_repr 實現(xiàn)的開頭被調(diào)用以檢測循環(huán)。

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

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

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

void Py_ReprLeave(PyObject *object)

Part of the Stable ABI.

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

標準異常

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)是單獨的異常類型。

注：

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

這是其他標準異常的基類。

2

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

標準警告類別

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

這是其他標準警告類別的基類。

分享標題：創(chuàng)新互聯(lián)Python教程：異常處理
網(wǎng)頁網(wǎng)址：http://www.dlmjj.cn/article/dpgchgi.html