異常處理¶
本章描述的函式將允許你處理和引發 Python 異常。理解 Python 異常處理的一些基礎知識很重要。它有點像 POSIX 的 errno 變數：有一個全域性指標（每個執行緒）指示最後發生的錯誤。大多數 C API 函式在成功時不會清除它，但會在失敗時設定它以指示錯誤的原因。大多數 C API 函式也會返回一個錯誤指示符，如果它們應該返回一個指標，通常是 NULL，或者如果它們返回一個整數，則是 -1 (例外：PyArg_* 函式成功時返回 1，失敗時返回 0)。
具體來說，錯誤指示符由三個物件指標組成：異常的型別、異常的值和追溯物件。如果未設定，這些指標中的任何一個都可以是 NULL（儘管某些組合是被禁止的，例如，如果異常型別是 NULL，則不能有非 NULL 的追溯）。
當一個函式必須失敗因為它呼叫的某個函式失敗時，它通常不會設定錯誤指示符；它呼叫的函式已經設定了它。它負責處理錯誤並清除異常，或者在清理它所持有的任何資源（例如物件引用或記憶體分配）後返回；如果它未準備好處理錯誤，它不應正常繼續。如果因錯誤而返回，重要的是要向呼叫者指示已設定了錯誤。如果錯誤未被處理或仔細傳播，對 Python/C API 的額外呼叫可能不會按預期行為，並可能以神秘的方式失敗。
備註
錯誤指示符 不是 sys.exc_info() 的結果。前者對應於尚未捕獲（因此仍在傳播）的異常，而後者在捕獲異常（因此已停止傳播）後返回異常。
列印和清除¶
-
void PyErr_PrintEx(int set_sys_last_vars)¶
- 作為 穩定 ABI 的一部分。
向
sys.stderr列印標準追溯並清除錯誤指示符。 除非 錯誤是SystemExit，在這種情況下不會列印追溯，Python 程序將以SystemExit例項指定的錯誤程式碼退出。僅當 錯誤指示符已設定時才呼叫此函式。否則將導致致命錯誤！
如果 set_sys_last_vars 非零，則變數
sys.last_exc將設定為列印的異常。為了向後相容，已棄用的變數sys.last_type、sys.last_value和sys.last_traceback也分別設定為此異常的型別、值和追溯。版本 3.12 中已更改: 添加了
sys.last_exc的設定。
-
void PyErr_WriteUnraisable(PyObject *obj)¶
- 作為 穩定 ABI 的一部分。
使用當前異常和 obj 引數呼叫
sys.unraisablehook()。當已設定異常但直譯器實際上無法引發異常時，此實用函式會向
sys.stderr列印警告訊息。例如，當__del__()方法中發生異常時，就會使用它。呼叫此函式時帶有一個引數 obj，它標識了不可引發異常發生的上下文。如果可能，obj 的 repr 將在警告訊息中列印。如果 obj 是
NULL，則只打印追溯。呼叫此函式時必須設定異常。
版本 3.4 中已更改: 列印追溯。如果 obj 為
NULL，則只打印追溯。版本 3.8 中已更改: 使用
sys.unraisablehook()。
-
void PyErr_FormatUnraisable(const char *format, ...)¶
類似於
PyErr_WriteUnraisable()，但 format 和後續引數有助於格式化警告訊息；它們與PyUnicode_FromFormat()中的含義和值相同。PyErr_WriteUnraisable(obj)大致等同於PyErr_FormatUnraisable("Exception ignored in: %R", obj)。如果 format 為NULL，則只打印追溯。在 3.13 版本加入。
引發異常¶
這些函式有助於設定當前執行緒的錯誤指示符。為方便起見，其中一些函式將始終返回一個 NULL 指標，用於 return 語句。
-
void PyErr_SetString(PyObject *type, const char *message)¶
- 作為 穩定 ABI 的一部分。
這是設定錯誤指示符最常用的方式。第一個引數指定異常型別；它通常是標準異常之一，例如
PyExc_RuntimeError。你無需建立對它的新強引用（例如，使用Py_INCREF()）。第二個引數是錯誤訊息；它從'utf-8'解碼。
-
void PyErr_SetObject(PyObject *type, PyObject *value)¶
- 作為 穩定 ABI 的一部分。
此函式類似於
PyErr_SetString()，但允許你為異常的“值”指定任意 Python 物件。
-
PyObject *PyErr_Format(PyObject *exception, const char *format, ...)¶
- 返回值: 總是 NULL。 穩定 ABI 的一部分。
此函式設定錯誤指示符並返回
NULL。exception 應該是 Python 異常類。format 和後續引數有助於格式化錯誤訊息；它們與PyUnicode_FromFormat()中的含義和值相同。format 是一個 ASCII 編碼的字串。
-
PyObject *PyErr_FormatV(PyObject *exception, const char *format, va_list vargs)¶
- 返回值: 總是 NULL。 自 3.5 版本起成為 穩定 ABI 的一部分。
與
PyErr_Format()相同，但接受va_list引數而不是可變數量的引數。在 3.5 版本加入。
-
int PyErr_BadArgument()¶
- 作為 穩定 ABI 的一部分。
這是
PyErr_SetString(PyExc_TypeError, message)的簡寫，其中 message 指示內建操作呼叫時使用了非法引數。它主要用於內部使用。
-
PyObject *PyErr_NoMemory()¶
- 返回值: 總是 NULL。 穩定 ABI 的一部分。
這是
PyErr_SetNone(PyExc_MemoryError)的簡寫；它返回NULL，因此物件分配函式在記憶體不足時可以寫入return PyErr_NoMemory();。
-
PyObject *PyErr_SetFromErrno(PyObject *type)¶
- 返回值: 總是 NULL。 穩定 ABI 的一部分。
這是一個方便的函式，用於在 C 庫函式返回錯誤並設定 C 變數
errno時引發異常。它構造一個元組物件，其第一項是整數errno值，第二項是相應的錯誤訊息（從strerror()獲取），然後呼叫PyErr_SetObject(type, object)。在 Unix 上，當errno值為EINTR時，表示系統呼叫被中斷，這會呼叫PyErr_CheckSignals()，如果它設定了錯誤指示符，則保持其設定。該函式始終返回NULL，因此係統呼叫的包裝函式可以在系統呼叫返回錯誤時寫入return PyErr_SetFromErrno(type);。
-
PyObject *PyErr_SetFromErrnoWithFilenameObject(PyObject *type, PyObject *filenameObject)¶
- 返回值: 總是 NULL。 穩定 ABI 的一部分。
類似於
PyErr_SetFromErrno()，但如果 filenameObject 不是NULL，它會作為第三個引數傳遞給 type 的建構函式。在OSError異常的情況下，這用於定義異常例項的filename屬性。
-
PyObject *PyErr_SetFromErrnoWithFilenameObjects(PyObject *type, PyObject *filenameObject, PyObject *filenameObject2)¶
- 返回值: 總是 NULL。 自 3.7 版本起成為 穩定 ABI 的一部分。
類似於
PyErr_SetFromErrnoWithFilenameObject()，但接受第二個檔名物件，用於在接受兩個檔名的函式失敗時引發錯誤。在 3.4 版本加入。
-
PyObject *PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename)¶
- 返回值: 總是 NULL。 穩定 ABI 的一部分。
類似於
PyErr_SetFromErrnoWithFilenameObject()，但檔名以 C 字串形式給出。filename 從 檔案系統編碼和錯誤處理程式 解碼。
-
PyObject *PyErr_SetFromWindowsErr(int ierr)¶
- 返回值: 總是 NULL。 自 3.7 版本起成為 Windows 上 穩定 ABI 的一部分。
這是一個方便的函式，用於引發
OSError。如果呼叫時 ierr 為0，則使用呼叫GetLastError()返回的錯誤程式碼。它呼叫 Win32 函式FormatMessage()來檢索由 ierr 或GetLastError()給出的錯誤程式碼的 Windows 描述，然後構造一個OSError物件，其winerror屬性設定為錯誤程式碼，strerror屬性設定為相應的錯誤訊息（從FormatMessage()獲取），然後呼叫PyErr_SetObject(PyExc_OSError, object)。此函式始終返回NULL。可用性：Windows。
-
PyObject *PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)¶
- 返回值: 總是 NULL。 自 3.7 版本起成為 Windows 上 穩定 ABI 的一部分。
類似於
PyErr_SetFromWindowsErr()，並帶有一個額外的引數，指定要引發的異常型別。可用性：Windows。
-
PyObject *PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)¶
- 返回值: 總是 NULL。 自 3.7 版本起成為 Windows 上 穩定 ABI 的一部分。
類似於
PyErr_SetFromWindowsErr()，但具有額外的行為，如果 filename 不是NULL，它將從檔案系統編碼 (os.fsdecode()) 解碼，並作為第三個引數傳遞給OSError的建構函式，用於定義異常例項的filename屬性。可用性：Windows。
-
PyObject *PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject *type, int ierr, PyObject *filename)¶
- 返回值: 總是 NULL。 自 3.7 版本起成為 Windows 上 穩定 ABI 的一部分。
類似於
PyErr_SetExcFromWindowsErr()，但具有額外的行為，如果 filename 不是NULL，它將作為第三個引數傳遞給OSError的建構函式，用於定義異常例項的filename屬性。可用性：Windows。
-
PyObject *PyErr_SetExcFromWindowsErrWithFilenameObjects(PyObject *type, int ierr, PyObject *filename, PyObject *filename2)¶
- 返回值: 總是 NULL。 自 3.7 版本起成為 Windows 上 穩定 ABI 的一部分。
類似於
PyErr_SetExcFromWindowsErrWithFilenameObject()，但接受第二個檔名物件。可用性：Windows。
在 3.4 版本加入。
-
PyObject *PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, const char *filename)¶
- 返回值: 總是 NULL。 自 3.7 版本起成為 Windows 上 穩定 ABI 的一部分。
類似於
PyErr_SetFromWindowsErrWithFilename()，並帶有一個額外的引數，指定要引發的異常型別。可用性：Windows。
-
PyObject *PyErr_SetImportError(PyObject *msg, PyObject *name, PyObject *path)¶
- 返回值: 總是 NULL。 自 3.7 版本起成為 穩定 ABI 的一部分。
這是一個方便的函式，用於引發
ImportError。msg 將設定為異常的訊息字串。name 和 path（兩者都可以是NULL）將分別設定為ImportError的name和path屬性。在 3.3 版本加入。
-
PyObject *PyErr_SetImportErrorSubclass(PyObject *exception, PyObject *msg, PyObject *name, PyObject *path)¶
- 返回值: 總是 NULL。 自 3.6 版本起成為 穩定 ABI 的一部分。
與
PyErr_SetImportError()非常相似，但此函式允許指定要引發的ImportError的子類。在 3.6 版本加入。
-
void PyErr_SyntaxLocationObject(PyObject *filename, int lineno, int col_offset)¶
為當前異常設定檔案、行和偏移量資訊。如果當前異常不是
SyntaxError，則它會設定附加屬性，使異常列印子系統認為該異常是SyntaxError。在 3.4 版本加入。
-
void PyErr_SyntaxLocationEx(const char *filename, int lineno, int col_offset)¶
- 自 3.7 版本起成為 穩定ABI 的一部分。
與
PyErr_SyntaxLocationObject()類似，但 filename 是從 檔案系統編碼和錯誤處理程式 解碼的位元組字串。在 3.2 版本加入。
-
void PyErr_SyntaxLocation(const char *filename, int lineno)¶
- 作為 穩定 ABI 的一部分。
與
PyErr_SyntaxLocationEx()類似，但省略了 col_offset 引數。
發出警告¶
使用這些函式從 C 程式碼發出警告。它們映象了 Python warnings 模組匯出的類似函式。它們通常會將警告訊息列印到 sys.stderr；但是，使用者也可能已指定將警告轉換為錯誤，在這種情況下它們將引發異常。還可能由於警告機制的問題而引發異常。如果未引發異常，則返回值為 0，如果引發異常，則返回值為 -1。（無法確定是否實際列印了警告訊息，也無法確定異常的原因；這是有意的。）如果引發異常，呼叫者應執行其正常的異常處理（例如，Py_DECREF() 持有的引用並返回錯誤值）。
-
int PyErr_WarnEx(PyObject *category, const char *message, Py_ssize_t stack_level)¶
- 作為 穩定 ABI 的一部分。
發出警告訊息。category 引數是警告類別（見下文）或
NULL；message 引數是一個 UTF-8 編碼的字串。stack_level 是一個正數，表示堆疊幀的數量；警告將從該堆疊幀中當前執行的程式碼行發出。stack_level 為 1 是呼叫PyErr_WarnEx()的函式，2 是其上方的函式，依此類推。警告類別必須是
PyExc_Warning的子類；PyExc_Warning是PyExc_Exception的子類；預設警告類別是PyExc_RuntimeWarning。標準 Python 警告類別作為全域性變數可用，其名稱在 警告型別 中列出。
-
int PyErr_WarnExplicitObject(PyObject *category, PyObject *message, PyObject *filename, int lineno, PyObject *module, PyObject *registry)¶
發出警告訊息，並對所有警告屬性進行顯式控制。這是 Python 函式
warnings.warn_explicit()的直接包裝；有關更多資訊，請參閱該處。module 和 registry 引數可以設定為NULL以獲得那裡描述的預設效果。在 3.4 版本加入。
-
int PyErr_WarnExplicit(PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry)¶
- 作為 穩定 ABI 的一部分。
類似於
PyErr_WarnExplicitObject()，不同之處在於 message 和 module 是 UTF-8 編碼的字串，而 filename 從 檔案系統編碼和錯誤處理程式 解碼。
-
int PyErr_WarnFormat(PyObject *category, Py_ssize_t stack_level, const char *format, ...)¶
- 作為 穩定 ABI 的一部分。
函式類似於
PyErr_WarnEx()，但使用PyUnicode_FromFormat()格式化警告訊息。format 是一個 ASCII 編碼的字串。在 3.2 版本加入。
-
int PyErr_ResourceWarning(PyObject *source, Py_ssize_t stack_level, const char *format, ...)¶
- 自 3.6 版本起成為 穩定 ABI 的一部分。
函式類似於
PyErr_WarnFormat()，但 category 是ResourceWarning，並且它將 source 傳遞給warnings.WarningMessage。在 3.6 版本加入。
查詢錯誤指示符¶
-
PyObject *PyErr_Occurred()¶
- 返回值: 借用引用。 穩定ABI 的一部分。
測試錯誤指示符是否已設定。如果已設定，則返回異常 type（上次呼叫
PyErr_Set*函式之一或PyErr_Restore()的第一個引數）。如果未設定，則返回NULL。你未擁有返回值的引用，因此無需Py_DECREF()它。呼叫者必須具有 已附加的執行緒狀態。
備註
不要將返回值與特定異常進行比較；請改用
PyErr_ExceptionMatches()，如下所示。（比較很容易失敗，因為在類異常的情況下，異常可能是例項而不是類，或者它可能是預期異常的子類。）
-
int PyErr_ExceptionMatches(PyObject *exc)¶
- 作為 穩定 ABI 的一部分。
等同於
PyErr_GivenExceptionMatches(PyErr_Occurred(), exc)。這應該只在實際設定異常時呼叫；如果未引發異常，將發生記憶體訪問衝突。
-
int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)¶
- 作為 穩定 ABI 的一部分。
如果 given 異常與 exc 中的異常型別匹配，則返回 true。如果 exc 是一個類物件，當 given 是一個子類的例項時，這也返回 true。如果 exc 是一個元組，則在元組中（以及遞迴地在子元組中）搜尋所有異常型別以進行匹配。
-
PyObject *PyErr_GetRaisedException(void)¶
- 返回值: 新引用。 自 3.12 版本起成為 穩定 ABI 的一部分。
返回當前正在引發的異常，同時清除錯誤指示符。如果錯誤指示符未設定，則返回
NULL。此函式用於需要捕獲異常的程式碼，或需要臨時儲存和恢復錯誤指示符的程式碼。
例如:
{ PyObject *exc = PyErr_GetRaisedException(); /* ... code that might produce other errors ... */ PyErr_SetRaisedException(exc); }
參見
PyErr_GetHandledException()，用於儲存當前正在處理的異常。3.12 新版功能.
-
void PyErr_SetRaisedException(PyObject *exc)¶
- 自 3.12 版本起成為 穩定 ABI 的一部分。
將 exc 設定為當前正在引發的異常，如果已設定現有異常，則清除它。
警告
此呼叫竊取 exc 的引用，該引用必須是一個有效的異常。
3.12 新版功能.
-
void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)¶
- 作為 穩定 ABI 的一部分。
自版本 3.12 棄用: 請改用
PyErr_GetRaisedException()。將錯誤指示符檢索到傳遞其地址的三個變數中。如果錯誤指示符未設定，則將所有三個變數設定為
NULL。如果已設定，它將被清除，並且你擁有檢索到的每個物件的引用。即使型別物件不為NULL，值和追溯物件也可能為NULL。備註
此函式通常僅由需要捕獲異常或臨時儲存和恢復錯誤指示符的舊程式碼使用。
例如:
{ 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)¶
- 作為 穩定 ABI 的一部分。
自版本 3.12 棄用: 請改用
PyErr_SetRaisedException()。根據三個物件 type、value 和 traceback 設定錯誤指示符，如果已設定現有異常，則清除它。如果物件為
NULL，則清除錯誤指示符。不要傳遞NULL型別和非NULL值或追溯。異常型別應該是一個類。不要傳遞無效的異常型別或值。（違反這些規則稍後會導致微妙的問題。）此呼叫會移除對每個物件的引用：你在呼叫前必須擁有對每個物件的引用，呼叫後你不再擁有這些引用。（如果你不理解這一點，請不要使用此函式。我警告過你。）備註
此函式通常僅由需要臨時儲存和恢復錯誤指示符的舊程式碼使用。使用
PyErr_Fetch()儲存當前錯誤指示符。
-
void PyErr_NormalizeException(PyObject **exc, PyObject **val, PyObject **tb)¶
- 作為 穩定 ABI 的一部分。
自版本 3.12 棄用: 請改用
PyErr_GetRaisedException()，以避免任何可能的去規範化。在某些情況下，
PyErr_Fetch()返回的值可能是“未規範化”的，這意味著*exc是一個類物件，但*val不是同一類的例項。在這種情況下，此函式可用於例項化該類。如果值已經規範化，則不執行任何操作。延遲規範化是為了提高效能。備註
此函式 不會 隱式設定異常值的
__traceback__屬性。如果希望適當地設定追溯，則需要以下附加片段if (tb != NULL) { PyException_SetTraceback(val, tb); }
-
PyObject *PyErr_GetHandledException(void)¶
- 自 3.11 版本起成為 穩定 ABI 的一部分。
檢索活動異常例項，就像
sys.exception()返回的那樣。這指的是 已經捕獲到 的異常，而不是剛剛引發的異常。返回異常的新引用或NULL。不修改直譯器的異常狀態。備註
此函式通常不用於希望處理異常的程式碼。相反，它可以在程式碼需要臨時儲存和恢復異常狀態時使用。使用
PyErr_SetHandledException()來恢復或清除異常狀態。在 3.11 版本中新增。
-
void PyErr_SetHandledException(PyObject *exc)¶
- 自 3.11 版本起成為 穩定 ABI 的一部分。
設定活動異常，如
sys.exception()所知。這指的是 已經捕獲到 的異常，而不是剛剛引發的異常。要清除異常狀態，請傳遞NULL。備註
此函式通常不用於希望處理異常的程式碼。相反，它可以在程式碼需要臨時儲存和恢復異常狀態時使用。使用
PyErr_GetHandledException()獲取異常狀態。在 3.11 版本中新增。
-
void PyErr_GetExcInfo(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)¶
- 自 3.7 版本起成為 穩定ABI 的一部分。
檢索異常資訊的舊式表示，如同
sys.exc_info()所知。這指的是一個已經被捕獲的異常，而不是一個剛剛被引發的異常。返回三個物件的新引用，其中任何一個都可以是NULL。不修改異常資訊狀態。此函式為了向後相容而保留。優先使用PyErr_GetHandledException()。備註
此函式通常不被想要處理異常的程式碼使用。相反，當代碼需要臨時儲存和恢復異常狀態時，可以使用它。使用
PyErr_SetExcInfo()來恢復或清除異常狀態。在 3.3 版本加入。
-
void PyErr_SetExcInfo(PyObject *type, PyObject *value, PyObject *traceback)¶
- 自 3.7 版本起成為 穩定ABI 的一部分。
設定異常資訊，如同
sys.exc_info()所知。這指的是一個已經被捕獲的異常，而不是一個剛剛被引發的異常。此函式竊取引數的引用。要清除異常狀態，為所有三個引數傳遞NULL。此函式為了向後相容而保留。優先使用PyErr_SetHandledException()。備註
此函式通常不被想要處理異常的程式碼使用。相反，當代碼需要臨時儲存和恢復異常狀態時，可以使用它。使用
PyErr_GetExcInfo()來讀取異常狀態。在 3.3 版本加入。
3.11 版本變更:
type和traceback引數不再使用，可以為 NULL。直譯器現在從異常例項（value引數）派生它們。該函式仍然竊取所有三個引數的引用。
訊號處理¶
-
int PyErr_CheckSignals()¶
- 作為 穩定 ABI 的一部分。
此函式與 Python 的訊號處理互動。
如果該函式從主執行緒和主 Python 直譯器下呼叫，它會檢查是否已向程序傳送訊號，如果是，則呼叫相應的訊號處理程式。如果支援
signal模組，這可以呼叫用 Python 編寫的訊號處理程式。該函式嘗試處理所有掛起的訊號，然後返回
0。然而，如果一個 Python 訊號處理程式引發一個異常，則設定錯誤指示器並立即返回-1（這樣其他掛起的訊號可能尚未處理：它們將在下一次PyErr_CheckSignals()呼叫時處理）。如果該函式從非主執行緒或非主 Python 直譯器下呼叫，它不做任何事情並返回
0。長時間執行的 C 程式碼如果希望能夠被使用者請求（例如透過按 Ctrl-C）中斷，可以呼叫此函式。
備註
SIGINT的預設 Python 訊號處理程式會引發KeyboardInterrupt異常。
-
void PyErr_SetInterrupt()¶
- 作為 穩定 ABI 的一部分。
模擬
SIGINT訊號到達的效果。這相當於PyErr_SetInterruptEx(SIGINT)。備註
此函式是非同步訊號安全的。它可以在沒有附加執行緒狀態的情況下和從 C 訊號處理程式中呼叫。
-
int PyErr_SetInterruptEx(int signum)¶
- 自 3.10 版本以來，作為 穩定 ABI 的一部分。
模擬訊號到達的效果。下次呼叫
PyErr_CheckSignals()時，將呼叫給定訊號編號的 Python 訊號處理程式。此函式可以由設定自己的訊號處理的 C 程式碼呼叫，並希望在請求中斷時（例如當用戶按下 Ctrl-C 中斷操作時）按預期呼叫 Python 訊號處理程式。
如果給定訊號未由 Python 處理（它被設定為
signal.SIG_DFL或signal.SIG_IGN），它將被忽略。如果 signum 超出允許的訊號編號範圍，則返回
-1。否則，返回0。此函式從不更改錯誤指示器。備註
此函式是非同步訊號安全的。它可以在沒有附加執行緒狀態的情況下和從 C 訊號處理程式中呼叫。
在 3.10 版本加入。
-
int PySignal_SetWakeupFd(int fd)¶
此實用函式指定一個檔案描述符，每當接收到訊號時，訊號編號將以單個位元組的形式寫入該檔案描述符。fd 必須是非阻塞的。它返回之前的檔案描述符。
值
-1停用該功能；這是初始狀態。這等同於 Python 中的signal.set_wakeup_fd()，但沒有任何錯誤檢查。fd 應該是一個有效的檔案描述符。該函式只能從主執行緒呼叫。3.5 版本變更: 在 Windows 上，該函式現在也支援套接字控制代碼。
異常類¶
-
PyObject *PyErr_NewException(const char *name, PyObject *base, PyObject *dict)¶
- 返回值: 新引用。 穩定ABI 的一部分。
此實用函式建立並返回一個新的異常類。name 引數必須是新異常的名稱，一個形式為
module.classname的 C 字串。base 和 dict 引數通常為NULL。這會建立一個派生自Exception（在 C 中可訪問為PyExc_Exception）的類物件。新類的
__module__屬性被設定為 name 引數的第一部分（直到最後一個點），類名被設定為最後一部分（最後一個點之後）。base 引數可用於指定備用基類；它可以是單個類或類的元組。dict 引數可用於指定類變數和方法的字典。
異常物件¶
-
PyObject *PyException_GetTraceback(PyObject *ex)¶
- 返回值: 新引用。 穩定ABI 的一部分。
返回與異常關聯的追溯物件作為新引用，可透過 Python 中的
__traceback__屬性訪問。如果沒有關聯的追溯物件，則返回NULL。
-
int PyException_SetTraceback(PyObject *ex, PyObject *tb)¶
- 作為 穩定 ABI 的一部分。
將與異常關聯的追溯設定為 tb。使用
Py_None清除它。
-
PyObject *PyException_GetContext(PyObject *ex)¶
- 返回值: 新引用。 穩定ABI 的一部分。
返回與異常相關聯的上下文（在處理 ex 時引發的另一個異常例項）作為新引用，可透過 Python 中的
__context__屬性訪問。如果沒有關聯的上下文，則返回NULL。
-
void PyException_SetContext(PyObject *ex, PyObject *ctx)¶
- 作為 穩定 ABI 的一部分。
將與異常關聯的上下文設定為 ctx。使用
NULL清除它。沒有型別檢查來確保 ctx 是一個異常例項。這將竊取 ctx 的引用。
-
PyObject *PyException_GetCause(PyObject *ex)¶
- 返回值: 新引用。 穩定ABI 的一部分。
返回與異常關聯的原因（由
raise ... from ...設定的異常例項或None）作為新引用，可透過 Python 中的__cause__屬性訪問。
-
void PyException_SetCause(PyObject *ex, PyObject *cause)¶
- 作為 穩定 ABI 的一部分。
將與異常關聯的原因設定為 cause。使用
NULL清除它。沒有型別檢查來確保 cause 是一個異常例項或None。這將竊取 cause 的引用。此函式隱式將
__suppress_context__屬性設定為True。
-
void PyException_SetArgs(PyObject *ex, PyObject *args)¶
- 自 3.12 版本起成為 穩定 ABI 的一部分。
將異常 ex 的
args設定為 args。
-
PyObject *PyUnstable_Exc_PrepReraiseStar(PyObject *orig, PyObject *excs)¶
- 這是一個不穩定 API。它可能會在次要版本中未經警告而更改。
實現直譯器
except*的一部分。orig 是捕獲的原始異常，而 excs 是需要引發的異常列表。此列表包含 orig 中未處理的部分（如果有），以及從except*子句中引發的異常（因此它們的追溯與 orig 不同）和重新引發的異常（它們的追溯與 orig 相同）。返回最終需要重新引發的ExceptionGroup，如果沒有要重新引發的內容，則返回None。3.12 新版功能.
Unicode 異常物件¶
以下函式用於從 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)¶
- 返回值: 新引用。 穩定ABI 的一部分。
建立一個
UnicodeDecodeError物件，其屬性包括 encoding, object, length, start, end 和 reason。encoding 和 reason 是 UTF-8 編碼的字串。
-
PyObject *PyUnicodeDecodeError_GetEncoding(PyObject *exc)¶
-
PyObject *PyUnicodeEncodeError_GetEncoding(PyObject *exc)¶
- 返回值: 新引用。 穩定ABI 的一部分。
返回給定異常物件的 encoding 屬性。
-
PyObject *PyUnicodeDecodeError_GetObject(PyObject *exc)¶
-
PyObject *PyUnicodeEncodeError_GetObject(PyObject *exc)¶
-
PyObject *PyUnicodeTranslateError_GetObject(PyObject *exc)¶
- 返回值: 新引用。 穩定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)¶
- 作為 穩定 ABI 的一部分。
獲取給定異常物件的 start 屬性並將其放入 *start 中。start 不得為
NULL。成功時返回0，失敗時返回-1。如果
UnicodeError.object是一個空序列，則結果 start 為0。否則，它將被裁剪到[0, len(object) - 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)¶
- 作為 穩定 ABI 的一部分。
將給定異常物件的 start 屬性設定為 start。成功時返回
0，失敗時返回-1。備註
雖然傳遞負的 start 不會引發異常，但相應的 getter 不會將其視為相對偏移。
-
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)¶
- 作為 穩定 ABI 的一部分。
獲取給定異常物件的 end 屬性並將其放入 *end 中。end 不得為
NULL。成功時返回0，失敗時返回-1。如果
UnicodeError.object是一個空序列，則結果 end 為0。否則，它將被裁剪到[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)¶
- 作為 穩定 ABI 的一部分。
將給定異常物件的 end 屬性設定為 end。成功時返回
0，失敗時返回-1。
遞迴控制¶
這兩個函式提供了一種在 C 級別（核心和擴充套件模組中）執行安全遞迴呼叫的方法。如果遞迴程式碼不一定呼叫 Python 程式碼（它會自動跟蹤其遞迴深度），則需要它們。對於 tp_call 的實現也不需要它們，因為 呼叫協議 會處理遞迴處理。
-
int Py_EnterRecursiveCall(const char *where)¶
- 自 3.9 版本以來成為 穩定 ABI 的一部分。
標記即將執行遞迴 C 級別呼叫的點。
然後函式檢查是否達到棧限制。如果是，則設定
RecursionError並返回非零值。否則，返回零。where 應該是一個 UTF-8 編碼的字串，例如
" in instance check"，用於連線到由遞迴深度限制引起的RecursionError訊息。3.9 版本變更: 此函式現在也可在 Limited API 中使用。
-
void Py_LeaveRecursiveCall(void)¶
- 自 3.9 版本以來成為 穩定 ABI 的一部分。
結束一次
Py_EnterRecursiveCall()。對於每次 成功 呼叫Py_EnterRecursiveCall()，都必須呼叫一次。3.9 版本變更: 此函式現在也可在 Limited API 中使用。
正確實現容器型別的 tp_repr 需要特殊的遞迴處理。除了保護棧，tp_repr 還需要跟蹤物件以防止迴圈。以下兩個函式有助於實現此功能。實際上，它們是 reprlib.recursive_repr() 的 C 等價物。
-
int Py_ReprEnter(PyObject *object)¶
- 作為 穩定 ABI 的一部分。
在
tp_repr實現的開頭呼叫以檢測迴圈。如果物件已經被處理，函式返回一個正整數。在這種情況下，
tp_repr實現應該返回一個表示迴圈的字串物件。例如，dict物件返回{...}，list物件返回[...]。如果達到遞迴限制，函式將返回一個負整數。在這種情況下，
tp_repr實現通常應返回NULL。否則，函式返回零，
tp_repr實現可以正常繼續。
-
void Py_ReprLeave(PyObject *object)¶
- 作為 穩定 ABI 的一部分。
結束
Py_ReprEnter()。對於每個返回零的Py_ReprEnter()呼叫，都必須呼叫一次。
異常和警告型別¶
所有標準 Python 異常和警告類別都作為全域性變數提供，其名稱為 PyExc_ 後跟 Python 異常名稱。這些變數的型別為 PyObject*；它們都是類物件。
為了完整性，以下是所有變數
異常型別¶
C 名稱 |
Python 名稱 |
|---|---|
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 和 PyExc_TimeoutError 是根據 PEP 3151 引入的。
3.5 版本加入: PyExc_StopAsyncIteration 和 PyExc_RecursionError。
3.6 版本加入: PyExc_ModuleNotFoundError。
3.11 版本加入: PyExc_BaseExceptionGroup。
OSError 別名¶
以下是 PyExc_OSError 的相容性別名。
3.3 版本中的變化：這些別名曾是獨立的異常型別。
C 名稱 |
Python 名稱 |
備註 |
|---|---|---|
備註
PyExc_WindowsError 僅在 Windows 上定義；透過測試預處理器宏 MS_WINDOWS 是否已定義來保護使用此程式碼。
警告型別¶
C 名稱 |
Python 名稱 |
|---|---|
3.2 版本新增：PyExc_ResourceWarning。
3.10 版本新增：PyExc_EncodingWarning。