打印和清除

void PyErr_Clear（）

清除错误指示器。如果没有设置错误指示，则没有效果.

void PyErr_PrintEx（ int  set_sys_last_vars）

打印标准回溯至sys.stderr并清除错误指示。仅在设置错误指示时才调用此功能。（否则会导致致命错误！）

如果set_sys_last_vars非零，则变量sys.last_type,sys.last_value和sys.last_traceback将设置为type，value和traceback打印的例外，分别为

void PyErr_Print（）

别名为PyErr_PrintEx(1).

void PyErr_WriteUnraisable（ PyObject  *obj）

当设置了异常但是解释器无法实际获取异常时，该实用程序函数会向sys.stderr输出警告消息。例如，在__del__()方法中发生异常时使用它

使用单个参数obj调用该函数，该参数用于标识发生不可注意的异常的上下文。如果可能的话，obj的代表将打印在警告信息中.

提升异常

这些函数可以帮助你设置当前线程的错误指示器。为方便起见，这些函数中的一些将始终返回aNULL指针，以便在return语句中使用.

void PyErr_SetString（ PyObject  *type，const char  *message）

这是设置错误指示符的最常用方法。第一个参数指定了异常类型;它通常是标准例外之一，例如。PyExc_RuntimeError。您不需要增加其引用计数。第二个参数是错误消息;它是从"utf-8‘解码

void PyErr_SetObject（ PyObject  *type，PyObject  *value）

这个函数类似于PyErr_SetString()但是你可以为异常的“值”指定一个任意的Python对象.

PyObject* PyErr_Format（ PyObject  *exception，const char  *format, …）

Return value: Always NULL.

这个函数设置错误指示符并返回NULL. exception应该是一个Python异常类。format和后续参数有助于格式化错误消息;它们具有与PyUnicode_FromFormat(). format中相同的含义和值，是ASCII-encodedstring.

PyObject * PyErr_FormatV（ PyObject  *exception，const char  *format，va_list  vargs）

Return value: Always NULL.

和PyErr_Format()相同，但是va_list参数而不是可变数量的参数.

版本3.5中的新功能

无效PyErr_SetNone（的PyObject  *type）

这是PyErr_SetObject(type, Py_None).

int PyErr_BadArgument（）

这是PyErr_SetString(PyExc_TypeError, message)，其中message表示使用非法规范调用内置操作。它主要供内部使用.

PyObject* PyErr_NoMemory（）

Return value: Always NULL.

这是PyErr_SetNone(PyExc_MemoryError)的简写;它返回NULL所以一个对象分配函数可以在内存不足时写return PyErr_NoMemory();.

PyObject* PyErr_SetFromErrno（ PyObject  *type）

Return value: Always NULL.

这是一个方便函数，用于在C库函数返回错误并设置C变量errno时引发异常。它构造了atuple对象，其第一项是整数errnovalue和其中第二项是相应的错误信息（来自strerror()），然后调用PyErr_SetObject(type, object)。在Unix上，当errno值是EINTR，表示系统调用中断，调用PyErr_CheckSignals()，如果设置了错误指示，则将其设置为。函数总是返回NULL，所以当系统调用返回错误时，系统调用周围的包装函数可以写return PyErr_SetFromErrno(type);

PyObject* PyErr_SetFromErrnoWithFilenameObject（ PyObject  *type，PyObject  *filenameObject）

Return value: Always NULL.

类似于PyErr_SetFromErrno()，附加行为如果filenameObject不是NULL，它被传递给type的构造函数作为第三个参数。在OSError异常的情况下，这用于定义异常实例的filename属性.

PyObject* PyErr_SetFromErrnoWithFilenameObjects（PyObject  *type，PyObject  *filenameObject，PyObject  *filenameObject2）

Return value: Always NULL.

类似于PyErr_SetFromErrnoWithFilenameObject()，但是接受一个secondfilename对象，用于在带有两个filenamesfails的函数

新版本3.4.

PyObject* PyErr_SetFromErrnoWithFilename（ PyObject  *type，const char  *filename）

Return value: Always NULL.

类似于PyErr_SetFromErrnoWithFilenameObject()，但文件名是C字符串。filename是从文件系统编码解码的（os.fsdecode()).

PyObject * PyErr_SetFromWindowsErr（ int  ierr）

Return value: Always NULL.

这是一个提升WindowsError的便利功能。如果用ierr 0调用，则使用调用GetLastError()返回的错误代码。它调用Win32函数FormatMessage()来检索ierr或GetLastError()给出的错误代码的Windows描述，然后构造一个元组对象，其第一项是ierr value和其中第二项是相应的错误信息（来自FormatMessage()），然后调用PyErr_SetObject(PyExc_WindowsError,object)。这个函数总是返回NULL.

可用性：Windows.

PyObject* PyErr_SetExcFromWindowsErr（ PyObject  *type，int ierr）

Return value: Always NULL.

类似于PyErr_SetFromWindowsErr()，附加参数指定要引发的异常类型.

Availability：Windows.

PyObject * PyErr_SetFromWindowsErrWithFilename（ int  ierr，const char  *filename）

Return value: Always NULL.

类似于PyErr_SetFromWindowsErrWithFilenameObject()，但是文件名是作为C字符串给出的。filename是从filesystemencoding解码的（os.fsdecode()).

Availability：Windows.

PyObject* PyErr_SetExcFromWindowsErrWithFilenameObject（ PyObject  *type，int  ierr，PyObject  *filename）

Return value: Always NULL.

类似于PyErr_SetFromWindowsErrWithFilenameObject()，用附加参数指定要引发的异常类型.

Availability：Windows.

PyObject* PyErr_SetExcFromWindowsErrWithFilenameObjects（ PyObject *type，int  ierr，PyObject  *filename，PyObject  *filename2）

Return value: Always NULL.

类似于PyErr_SetExcFromWindowsErrWithFilenameObject()，但接受第二个文件名对象.

Availability：Windows.

新版本3.4.

PyObject* PyErr_SetExcFromWindowsErrWithFilename（ PyObject  *type，int  ierr，const char  *filename）

Return value: Always NULL.

类似于PyErr_SetFromWindowsErrWithFilename()，附加参数指定要引发的异常类型.

Availability：Windows.

PyObject* PyErr_SetImportError（ PyObject  *msg，PyObject  *name，PyObject  *path）

Return value: Always NULL.

这是一个方便的函数来引发ImportError. msg将被设置为异常的消息字符串。name和path，这两个都可以NULL，分别设置为ImportError name和path属性

新版本3.3.

void PyErr_SyntaxLocationObject（ PyObject  *filename，int  lineno，int col_offset）

设置当前异常的文件，行和偏移量信息。如果当前的例外不是SyntaxError，然后设置additionalattributes，这使异常打印子系统认为异常是SyntaxError.

版本3.4.

void PyErr_SyntaxLocationEx（ const char  *filename,int  lineno，int  col_offset）

就像PyErr_SyntaxLocationObject()，但filename是一个从文件系统编码中解码的字节字符串（os.fsdecode()).

新版本3.2.

voidPyErr_SyntaxLocation（ const char  *filename，int  lineno）

喜欢PyErr_SyntaxLocationEx()，但是col_offset参数isomitted.

void PyErr_BadInternalCall（）

这是PyErr_SetString(PyExc_SystemError, message)的简写，其中message表示使用非法参数调用内部操作（例如Python / C API函数）。它主要用于内部使用.

发出警告

使用这些函数从C代码发出警告。它们反映了Python warnings模块导出的类似函数。他们通常会在sys.stderr;但是，用户也可能已指定将警告转换为错误，在这种情况下，它们将引发异常。由于警告机制出现问题，函数也可能引发异常。如果没有引发异常，则返回值为0，如果引发异常则返回-1。（无法确定是否实际打印了警告消息，也无法确定异常的原因;这是有意的。）如果引发异常，调用者应该进行其规范处理（例如，Py_DECREF()拥有引用和返回错误值）.

int PyErr_WarnEx（ PyObject  *category，const char  *message,Py_ssize_t  stack_level）

发出警告信息。category参数是一个警告类别（见下文）或NULL;message参数是一个UTF-8编码的字符串。stack_level是一个给出多个堆栈帧的正数;警告将从该堆栈帧中当前正在执行的代码行发出。一个 stack_level1是调用PyErr_WarnEx()的函数，2是上面的函数，等等.

警告类别必须是PyExc_Warning的子类; PyExc_Warning是一个PyExc_Exception的子类;默认警告类别是PyExc_RuntimeWarning。standardPython警告类别可用作全局变量，其名称枚举在标准警告类别.

有关警告控制的信息，请参阅warnings模块的文档和-W命令行文章中的选项。没有C API用于警告控制.

PyObject* PyErr_SetImportErrorSubclass（ PyObject  *msg，PyObject  *name，PyObject  *path）

Return value: Always NULL.

很像PyErr_SetImportError()但这个函数允许指定ImportError的子类来提升

在3.6版本中新增了

 int PyErr_WarnExplicitObject（ PyObject  *category，PyObject  *message，PyObject  *filename，int  lineno，PyObject  *module,PyObject  *registry）

发出警告消息，明确控制所有警告属性。这是一个简单的Python函数包装warnings.warn_explicit()，请参阅那里了解更多信息。module和registry参数可以设置为NULL以获得默认效果.

新版本3.4.

intPyErr_WarnExplicit（的PyObject  *category，const char  *message，const char  *filename，int  lineno，const char  *module，PyObject  *registry）

类似于PyErr_WarnExplicitObject()，除了message和module是UTF-8编码的字符串，和filename从文件系统编码解码（os.fsdecode()).

int PyErr_WarnFormat（ PyObject  *category，Py_ssize_t  stack_level，const char  *format, …）

功能类似于PyErr_WarnEx()，但使用PyUnicode_FromFormat()格式化警告消息。formatisan ASCII编码的字符串.

版本3.2.

int PyErr_ResourceWarning（的PyObject  *source，Py_ssize_t  stack_level，const char  *format, …）

功能类似于PyErr_WarnFormat()，但是category是ResourceWarning并通过source至 warnings.WarningMessage().

版本3.6.

查询错误指示器

PyObject * PyErr_Occurred（）

Return value: Borrowed reference.

测试是否设置了错误指示器。如果设置，则返回异常type（最后一次调用PyErr_Set*()函数之一或PyErr_Restore()的第一个参数）。如果没有设置，请返回NULL。你没有引用返回值，所以你不需要Py_DECREF()它。

注意

不要将返回值与特定异常进行比较;使用PyErr_ExceptionMatches()相反，如下所示。（比较可能会失败，因为异常可能是一个实例而不是一个类，在类异常的情况下，或者它可能是预期异常的子类。）

int PyErr_ExceptionMatches（ PyObject  *exc）

相当于PyErr_GivenExceptionMatches(PyErr_Occurred(), exc)。这只应在实际设置异常时调用;如果没有异常，就会发生内存访问.

int PyErr_GivenExceptionMatches（的PyObject  *given，PyObject  *exc）

如果given异常匹配exc。如果exc是一个类对象，当given是子类的实例。如果exc是一个元组，则搜索元组中的所有异常类型（并在子元组中递归）搜索匹配.

void PyErr_Fetch（ PyObject  **ptype,PyObject  **pvalue，PyObject  **ptraceback）

将错误指示器检索为三个传递地址的变量。如果没有设置错误指示，则将所有三个变量设置为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）

设置三个对象的错误指示器。如果已经设置了错误指示符，则首先清除它。如果对象是NULL，则清除errorindicator。不要传递NULL类型和非NULL价值ortraceback。异常类型应该是一个类。不要传递invalidexception类型或值。（违反这些规则将导致细微的问题。）此调用会删除对每个对象的引用：在调用之前和调用之后，您必须拥有对每个对象的引用，您不再拥有这些引用。（如果您不明白这一点，请不要使用此功能。请警告您。）

注意

此功能通常仅用于需要临时保存和恢复错误指示的代码。使用PyErr_Fetch()保存当前错误指示器.

void PyErr_NormalizeException（ PyObject ** exc，PyObject ** val，PyObject ** tb ）

在某些情况下，PyErr_Fetch()返回的值可以是“非标准化”，这意味着*exc是一个类对象但是*val不是同一个类的实例。在这种情况下，此函数可用于实例化类。如果值已经标准化，则没有任何反应。实现延迟归一化以提高性能.

注意

这个函数does not隐式设置__traceback__属性关于异常值。如果需要适当地设置回溯，则需要以下附加片段：

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

void PyErr_GetExcInfo（ PyObject  **ptype，PyObject  **pvalue，PyObject  **ptraceback）

检索异常信息，如sys.exc_info()所知。这指的是already caught的异常，而不是异常提出的异常。返回三个对象的新引用，其中任何一个都可以是NULL。不修改异常信息状态.

注意

这个函数通常不被想要处理异常的代码使用。当代码需要保存和恢复异常状态时可以使用它暂时。使用PyErr_SetExcInfo()恢复或清除异常状态.

3.3版本中的新功能

无效PyErr_SetExcInfo（的PyObject  *type，PyObject  *value，PyObject  *traceback）

设置例外信息，如sys.exc_info()。这指的是一个例外already caught，而不是一个明确提出的例外。这个函数窃取了参数的引用。为了清除异常状态，传递NULL关于这三个参数的一般规则，请参阅PyErr_Restore().

注意

想要处理异常的代码通常不使用此函数。当代码需要临时保存和恢复异常状态时，可以使用它。使用 PyErr_GetExcInfo()阅读例外情况.

新版本3.3.

信号处理

int PyErr_CheckSignals（）

此函数与Python的信号处理交互。它检查信号是否已发送到进程，如果是，则调用相应的信号处理程序。如果signal支持模块，这可以调用用Python编写的信号处理程序。在所有情况下，SIGINT的默认效果是提升KeyboardInterrupt例外。如果出现异常，则设置错误指示，函数返回-1;否则函数返回0。如果先前已设置错误指示可能会或可能不会显示.

无效PyErr_SetInterrupt（）

此功能模拟了SIGINT信号到达 – 下一次PyErr_CheckSignals()叫，KeyboardInterrupt会被提出来。可以在不拿着翻译锁的情况下调用它.

int PySignal_SetWakeupFd（ int  fd）

该实用程序功能指定一个文件描述符，每当接收到信号时，信号编号​​就被写为单个字节。fd必须是封锁的。它返回上一个这样的文件描述符.

价值 -1禁用该功能;这是初始状态。这相当于signal.set_wakeup_fd()在Python中，但没有任何错误检查。fd应该是有效的文件描述符。该函数只能从主线程中调用.

在版本3.5中调整：在Windows上，该函数现在也支持套接字句柄.

Exception类

PyObject * PyErr_NewException（ const char  *name，PyObject *base，PyObject  *dict）

Return value: New reference.

这个实用程序函数创建并返回一个新的异常类。name参数必须是新异常的名称，即module.classname形式的C字符串。base和dict参数通常是NULL。这会创建一个派生自Exception的类对象（在C中可以作为PyExc_Exception访问）。

新类的__module__属性设置为name参数的第一部分（最后一个点），类名设置为lastpart（在最后一个点之后）。base参数可用于指定alternatebase类;它可以只是一个类或一个类的元组。dict参数可用于指定类变量和方法的字典.

PyObject* PyErr_NewExceptionWithDoc（ const char  *name，const char  *doc，PyObject  *base，PyObject  *dict）

Return value: New reference.

和PyErr_NewException()，除了新的异常类可以给出一个docstring：if doc不是NULL，它将被用作异常类的thedocstring .

版本3.2.

异常对象

PyObject * PyException_GetTraceback（的PyObject  *ex）

Return value: New reference.

返回与异常关联的回溯作为新引用，可以从Python到__traceback__。如果没有关联，则返回NULL.

int PyException_SetTraceback（ PyObject  *ex，PyObject  *tb）

将与异常关联的回溯设置为tb。使用Py_None toclear it .

PyObject * PyException_GetContext（ PyObject  *ex）

Return value: New reference.

返回上下文（处理过程中的另一个异常实例exwasraised）与异常相关联作为一个新的引用，可以从thePython到__context__访问。如果没有关联的上下文，则返回NULL.

void PyException_SetContext（ PyObject  *ex，PyObject  *ctx）

将与异常相关的上下文设置为ctx。使用NULL来清除。没有类型检查以确保ctx是一个异常实例。这会窃取对ctx.

PyObject * PyException_GetCause（的PyObject  *ex）

Return value: New reference.

返回原因（例外情况，或None，通过设置 raise ... from ...）作为新参考与异常相关联，可以从Python到__cause__.

void PyException_SetCause（ PyObject  *ex，PyObject  *cause）

将与异常相关的原因设置为cause。使用NULL来清除。没有类型检查以确保cause是一个例外实例或None。这偷了一个引用cause.

__suppress_context__被这个函数隐式设置为True。

Unicode异常对象

以下函数用于从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）

Return value: New reference.

创建一个UnicodeDecodeError对象，其属性为encoding,object, length, start, end和reason. encoding和reason areUTF-8个编码的字符串

PyObject* PyUnicodeEncodeError_Create（ const char  *encoding，const Py_UNICODE  *object，Py_ssize_t  length，Py_ssize_t  start，Py_ssize_t  end，const char  *reason）

Return value: New reference.

创建一个UnicodeEncodeError对象属性encoding,object, length, start, end和reason. encoding和reason areUTF-8编码的字符串.

PyObject* PyUnicodeTranslateError_Create（const Py_UNICODE  *object，Py_ssize_t  length，Py_ssize_t  start，Py_ssize_t  end，const char  *reason）

Return value: New reference.

创建一个UnicodeTranslateError带有object,length, start, end和reason. reason属性的对象是一个UTF-8编码的字符串.

PyObject * PyUnicodeDecodeError_GetEncoding（ PyObject  *exc）

PyObject * PyUnicodeEncodeError_GetEncoding（ PyObject  *exc）

Return value: New reference.

返回给定异常对象的encoding属性.

PyObject* PyUnicodeDecodeError_GetObject（ PyObject  *exc）

PyObject * PyUnicodeEncodeError_GetObject（ PyObject  *exc）

PyObject * PyUnicodeTranslateError_GetObject（ PyObject  *exc）

Return value: New reference.

返回给定异常对象的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）

得到start给定异常对象的属性并将其放入*start. start不能是NULL。成功时返回0，-1 onfailure.

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）

将给定异常对象的start属性设置为start。成功时0返回，-1失败时

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

获取给定异常对象的end属性并放置它进*end. end一定不能NULL。成功时返回0，-1 onfailure.

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）

将给定异常对象的end属性设置为end。成功返回0，-1失败时

PyObject * PyUnicodeDecodeError_GetReason（的PyObject  *exc）

PyObject * PyUnicodeEncodeError_GetReason（ PyObject  *exc）

PyObject * PyUnicodeTranslateError_GetReason（ PyObject  *exc）

Return value: New reference.

返回给定异常对象的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）

将给定异常对象的reason属性设置为reason。返回0成功时，-1失败时

递归控制

这两个函数提供了一种在核心和扩展模块中在Clevel上执行安全递归调用的方法。如果递归代码不一定会调用Python代码（自动跟踪其偏移深度），则需要它们.

int Py_EnterRecursiveCall（ const char  *where）

标记即将执行递归C级调用的点.

如果定义USE_STACKCHECK，此函数检查OSstack是否溢出使用PyOS_CheckStack()。在这种情况下，设置MemoryError并返回非零值.

该函数然后检查是否达到递归限制。如果是这样的话，RecursionError设置并返回非零值。否则返回零.

where应该是一个字符串，如" in instance check"与recursiondepth限制引起的RecursionError消息联系在一起。

void Py_LeaveRecursiveCall（）

结束Py_EnterRecursiveCall()。必须每次调用一次successful调用Py_EnterRecursiveCall().

正确执行tp_repr对于容器类型，需要特殊的递归处理。除了保护堆栈，tp_repr还需要跟踪对象以防止循环。以下两个功能有助于实现此功能。实际上，这些是C等价于reprlib.recursive_repr().

int Py_ReprEnter（ PyObject  *object）

在tp_repr实现的开头调用以检测周期.

如果对象已被处理，则该函数返回一个正整数。在那种情况下tp_repr实现应该返回一个表示循环的字符串对象。例如，dict对象返回{...}和list objectsreturn [...].

如果达到递归限制，函数将返回一个负整数。在那种情况下tp_repr实现应该通常返回NULL.

否则，函数返回零，tp_repr实现可以正常继续

void Py_ReprLeave（ PyObject  *object）

结束Py_ReprEnter()。必须为Py_ReprEnter()返回零的每个位置调用一次.

标准异常

所有标准Python异常都可用作名称为PyExc_的全局变量通过Python异常名称。它们的类型为PyObject*;它们都是类对象。为了完整，以下是所有变量：

这些是PyExc_OSError：

注意到

1. 这是其他标准例外的基类.
2. 这与weakref.ReferenceError.
3. 仅在Windows上定义;通过测试预处理器宏来保护使用它的代码MS_WINDOWS被定义为。

标准警告类别

所有标准Python警告类别都可用作全局变量，其中PyExc_后跟Python异常名称。这些有PyObject*;它们都是类对象。为了完整性，以下是所有变量：

注意：

1. 这是其他标准警告类别的基类.