Exception Handling

本章中描述的Function将使您能够处理和引发 Python 异常。了解 Python 异常处理的一些基础知识很重要。它的工作原理类似于 Unix errno变量：全局指示器(每个线程)指示最近发生的错误。大多数Function不会在成功时清除此错误，但会设置它以指示失败时错误的原因。大多数函数还会返回错误指示符，如果应该返回指针，则通常为* NULL *；如果返回整数，则通常为-1(exceptions：PyArg_*()函数返回1表示成功，0表示失败)。

当某个函数由于某个函数调用失败而必须失败时，通常不会设置错误指示符。它调用的Function已经设置好了。它负责处理错误并清除异常，或者负责清除其拥有的任何资源(例如对象引用或内存分配)后返回；如果它没有准备好处理错误，则应该不continue 正常运行。如果由于错误而返回，则重要的是向呼叫者表明已设置了错误。如果未处理或未认真传播错误，则对 Python/C API 的其他调用可能无法正常运行，并且可能会以神秘方式失败。

错误指示符由与 Python 变量sys.exc_type，sys.exc_value和sys.exc_traceback对应的三个 Python 对象组成。存在 API 函数以各种方式与错误指示符进行交互。每个线程都有一个单独的错误指示器。

• 无效PyErr_PrintEx(int * set_sys_last_vars *)
  • 将标准回溯打印到sys.stderr，然后清除错误指示符。 除非 ，否则错误是SystemExit。在这种情况下，将不打印回溯，并且 Python 进程将退出，并返回SystemExit实例指定的错误代码。

设置错误指示器后，仅**调用此函数。否则会导致致命错误！

如果* set_sys_last_vars *不为零，则变量sys.last_type，sys.last_value和sys.last_traceback将分别设置为打印异常的类型，值和回溯。

• 无效PyErr_Print()

  • PyErr_PrintEx(1)的别名。

• PyObject* PyErr_Occurred ( )

  • *返回值：借用参考。

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

• int PyErr_ExceptionMatches(PyObject ** exc *)

  • 等效于PyErr_GivenExceptionMatches(PyErr_Occurred(), exc)。仅当实际设置了异常时才应调用此方法。如果没有引发异常，则会发生内存访问冲突。

• int PyErr_GivenExceptionMatches(PyObject 已提供，PyObject* exc *)

  • 如果* given 异常与 exc 中的异常匹配，则返回 true。如果 exc 是类对象，则当 given 是子类的实例时，它也会返回 true。如果 exc *是一个 Tuples，则将搜索该 Tuples 中的所有异常(并以递归方式在子 Tuples 中)以查找匹配项。

• 无效PyErr_NormalizeException(PyObject exc，PyObject val，PyObject ** tb)

  • 在某些情况下，下面的PyErr_Fetch()返回的值可以是“未规范化的”，这意味着*exc是一个类对象，而*val不是同一类的实例。在这种情况下，可以使用该函数实例化该类。如果值已经标准化，则什么也不会发生。实施延迟归一化以提高性能。

• 无效PyErr_Clear()

  • 清除错误指示器。如果未设置错误指示器，则无效。

• 无效PyErr_Fetch(PyObject *** ptype ，PyObject* * pvalue *，PyObject *** ptraceback *)

  • 将错误指示符检索为三个已传递地址的变量。如果未设置错误指示符，请将所有三个变量设置为* NULL 。如果已设置，它将被清除，并且您拥有对检索到的每个对象的引用。即使类型对象不是，值和 traceback 对象也可能是 NULL *。

• 无效PyErr_Restore(PyObject 类型，PyObject* 值*，PyObject *回溯)
  • 从三个对象设置错误指示器。如果错误指示器已经设置，则首先将其清除。如果对象为* NULL ，则清除错误指示符。不要传递 NULL 类型和非 NULL *值或回溯。异常类型应该是一个类。不要传递无效的异常类型或值。 (违反这些规则将在以后引起一些细微的问题.)此调用取消了对每个对象的引用：在调用之前，您必须拥有对每个对象的引用，而在调用之后，您将不再拥有这些引用。 (如果您不了解此Function，请不要使用此Function.我警告过您.)

• 无效PyErr_SetString(PyObject *type ，const char message *)

  • 这是设置错误指示符的最常见方法。第一个参数指定异常类型；它通常是标准 exception 之一，例如PyExc_RuntimeError。您无需增加其引用计数。第二个参数是错误消息；它被转换为字符串对象。

• 无效PyErr_SetObject(PyObject 类型，PyObject* 值*)

  • 此函数类似于PyErr_SetString()，但允许您为异常的“值”指定任意 Python 对象。

• PyObject * PyErr_Format(PyObject *exception ，const char format *，...)

  • 返回值：始终为 NULL.

此函数设置错误指示符并返回* NULL *。 * exception *应该是 Python 异常类。 * format *和后续参数有助于格式化错误消息；它们的含义和值与PyString_FromFormat()相同。

• 无效PyErr_SetNone(PyObject *类型)

  • 这是PyErr_SetObject(type, Py_None)的简写。

• int PyErr_BadArgument()

  • 这是PyErr_SetString(PyExc_TypeError, message)的简写，其中* message *表示使用非法参数调用了内置操作。它主要供内部使用。

• PyObject* PyErr_NoMemory ( )

  • 返回值：始终为 NULL.

这是PyErr_SetNone(PyExc_MemoryError)的简写；它返回* NULL *，因此对象分配函数在内存不足时可以写入return PyErr_NoMemory();。

• PyObject * PyErr_SetFromErrno(PyObject *类型)
  • 返回值：始终为 NULL.

这是一个便利函数，可在 C 库函数返回错误并设置 C 变量errno时引发异常。它构造一个 Tuples 对象，其第一项是整数errno值，而第二项是相应的错误消息(从strerror()得到)，然后调用PyErr_SetObject(type, object)。在 Unix 上，当errno值为EINTR时(表示系统调用已break)，它将调用PyErr_CheckSignals()，如果设置了错误指示符，则将其设置为该值。该函数始终返回* NULL *，因此当系统调用返回错误时，围绕系统调用的包装器函数可以写入return PyErr_SetFromErrno(type);。

• PyObject * PyErr_SetFromErrnoWithFilenameObject(PyObject 类型，PyObject* 文件名对象*)

  • 与PyErr_SetFromErrno()相似，另外的行为是，如果* filenameObject 不是 NULL ，它将作为第三个参数传递给 type *的构造函数。对于诸如IOError和OSError之类的异常，它用于定义异常实例的filename属性。

• PyObject * PyErr_SetFromErrnoWithFilename(PyObject *type ，const char filename *)

  • 返回值：始终为 NULL.

与PyErr_SetFromErrnoWithFilenameObject()相似，但文件名以 C 字符串形式给出。

• PyObject * PyErr_SetFromWindowsErr(int * ierr *)
  • 返回值：始终为 NULL.

这是提高WindowsError的便捷Function。如果以0的* ierr 进行调用，则会使用GetLastError()的调用返回的错误代码。它调用 Win32 函数FormatMessage()来检索 ierr 或GetLastError()给定的错误代码的 Windows 描述，然后构造一个 Tuples 对象，其第一项为 ierr 值，第二项为相应的错误消息(从FormatMessage()得到)，然后调用PyErr_SetObject(PyExc_WindowsError, object)。此函数始终返回 NULL *。可用性：Windows。

• PyObject * PyErr_SetExcFromWindowsErr(PyObject ** type *，int * ierr *)
  • 返回值：始终为 NULL.

与PyErr_SetFromWindowsErr()相似，带有一个附加参数，指定要引发的异常类型。可用性：Windows。

2.3 版的新Function。

• PyObject * PyErr_SetFromWindowsErrWithFilenameObject(int * ierr *，PyObject ** filenameObject *)

  • 与PyErr_SetFromWindowsErr()相似，另外的行为是，如果* filenameObject 不是 NULL *，它将作为第三个参数传递给WindowsError的构造函数。可用性：Windows。

• PyObject * PyErr_SetFromWindowsErrWithFilename(int * ierr *，const char ** filename *)

  • 返回值：始终为 NULL.

与PyErr_SetFromWindowsErrWithFilenameObject()相似，但文件名以 C 字符串形式给出。可用性：Windows。

• PyObject * PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject **type ，int * ierr ，PyObject filename *)
  • 与PyErr_SetFromWindowsErrWithFilenameObject()相似，带有一个附加参数，指定要引发的异常类型。可用性：Windows。

2.3 版的新Function。

• PyObject * PyErr_SetExcFromWindowsErrWithFilename(PyObject **type ，int * ierr ，const char filename *)
  • 返回值：始终为 NULL.

与PyErr_SetFromWindowsErrWithFilename()相似，带有一个附加参数，指定要引发的异常类型。可用性：Windows。

2.3 版的新Function。

• 无效PyErr_BadInternalCall()

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

• int PyErr_WarnEx(PyObject *category ，char message *，int * stacklevel *)

  • 发出警告消息。 * category 参数是警告类别(请参见下文)或 NULL *； * message *参数是一个消息字符串。 * stacklevel *是一个正数，给出了许多堆栈帧；该警告将从该堆栈帧中当前正在执行的代码行发出。 * stacklevel *为 1 是调用PyErr_WarnEx()的函数，2 是其之上的函数，依此类推。

此Function通常将警告消息打印到* sys.stderr *；但是，用户也可能已指定警告将变为错误，在这种情况下，这将引发异常。由于警告机制存在问题，该函数还可能引发异常(该实现会导入warnings模块来执行繁重的工作)。如果未引发异常，则返回值为0；如果引发异常，则返回值为-1。 (无法确定是否实际打印警告消息，也不知道异常的原因；这是有意的.)如果引发异常，则调用方应执行其常规异常处理(例如，Py_DECREF()拥有的引用)并返回错误值)。

警告类别必须是PyExc_Warning的子类； PyExc_Warning是PyExc_Exception的子类；默认警告类别为PyExc_RuntimeWarning。标准的 Python 警告类别可用作全局变量，其名称在标准警告类别处枚举。

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

• int PyErr_Warn(PyObject 类别，char* 消息*)
  • 发出警告消息。 * category 参数是警告类别(请参见下文)或 NULL *； * message 参数是一个消息字符串。该警告似乎是由调用PyErr_Warn()的函数发出的，等效于 stacklevel *为 1 的调用PyErr_WarnEx()。

不推荐使用；请改用PyErr_WarnEx()。

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

  • 发出警告消息，并明确控制所有警告属性。这是 Python 函数warnings.warn_explicit()的直接包装，请参见那里的更多信息。 * module 和 registry 参数可以设置为 NULL *以获得此处描述的默认效果。

• int PyErr_WarnPy3k(char ** message *，int * stacklevel *)

  • 如果启用了Py_Py3kWarningFlag标志，则使用给定的* message 和 stacklevel *发出DeprecationWarning。

2.6 版的新Function。

• int PyErr_CheckSignals()
  • 此函数与 Python 的 signal 处理交互。它检查是否已将 signal 发送到进程，如果已发送，则调用相应的 signal 处理程序。如果支持signal模块，则可以调用用 Python 编写的 signal 处理程序。在所有情况下，SIGINT的默认效果是引发KeyboardInterrupt异常。如果引发异常，则设置错误指示符，并且该函数返回-1；否则函数返回0。如果错误指示器是先前设置的，则可能会清除，也可能不会清除。

• 无效PyErr_SetInterrupt()
  • 此函数模拟SIGINTsignal 到达的效果-下次调用PyErr_CheckSignals()时，将引发KeyboardInterrupt。可以在不按住解释器锁的情况下调用它。

• int PySignal_SetWakeupFd(int * fd *)
  • 该 Util 函数指定一个文件 Descriptors，每当接收到 signal 时，便会将'\0'字节写入该文件 Descriptors。它返回先前的此类文件 Descriptors。值-1禁用该Function；这是初始状态。这等效于 Python 中的signal.set_wakeup_fd()，但没有任何错误检查。 * fd *应该是有效的文件 Descriptors。该函数只能从主线程调用。

2.6 版的新Function。

• PyObject * PyErr_NewException(char *name ，PyObject base *，PyObject ** dict *)
  • 返回值：新参考.

该 Util 函数创建并返回一个新的异常类。 * name *参数必须是新异常的名称，格式为module.classname的 C 字符串。 * base 和 dict 参数通常是 NULL *。这将创建一个从Exception派生的类对象(在 C 中可以passPyExc_Exception访问)。

新类的__module__属性设置为* name *参数的第一部分(直到最后一个点)，而类名则设置为最后一部分(在最后一个点之后)。 * base *参数可用于指定备用 Base Class；它既可以是一个类，也可以是一组 Tuples。 * dict *参数可用于指定类变量和方法的字典。

• PyObject * PyErr_NewExceptionWithDoc(char *name ，char doc *，PyObject *base ，PyObject dict *)
  • 返回值：新参考.

与PyErr_NewException()相同，不同之处在于可以轻松为新的异常类提供 docstring：如果* doc 为非 NULL *，它将用作异常类的 docstring。

2.7 版的新Function。

• 无效PyErr_WriteUnraisable(PyObject ** obj *)
  • 设置了异常后，此 Util 函数会将警告消息打印到sys.stderr，但解释器实际上无法引发该异常。例如，在del()方法中发生异常时使用。

该函数使用单个参数* obj 进行调用，该参数标识发生了无法提出的异常的上下文。如果可能， obj *的代表将打印在警告消息中。

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

  • 使用属性* encoding ， object ， length ， start ， end 和 reason *创建一个UnicodeDecodeError对象。

• 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 *)

  • 使用属性* encoding ， object ， length ， start ， end 和 reason *创建一个UnicodeEncodeError对象。

• PyObject * PyUnicodeTranslateError_Create(const Py_UNICODE **object *，Py_ssize_t * length ，Py_ssize_t * start ，Py_ssize_t * end ，const char 原因)

  • 使用属性* object ， length ， start ， end 和 reason *创建一个UnicodeTranslateError对象。

• PyObject * PyUnicodeDecodeError_GetEncoding(PyObject ** exc *)

• PyObject * PyUnicodeEncodeError_GetEncoding(PyObject ** exc *)

  • 返回给定异常对象的* encoding *属性。

• PyObject * PyUnicodeDecodeError_GetObject(PyObject ** exc *)

• PyObject * PyUnicodeEncodeError_GetObject(PyObject ** exc *)

• PyObject * PyUnicodeTranslateError_GetObject(PyObject ** exc *)

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

• 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。

• 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 *)

  • 获取给定异常对象的* 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 *)

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

• PyObject * PyUnicodeDecodeError_GetReason(PyObject ** exc *)

• PyObject * PyUnicodeEncodeError_GetReason(PyObject ** exc *)

• PyObject * PyUnicodeTranslateError_GetReason(PyObject ** exc *)

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

Recursion Control

这两个函数提供了一种在核心和扩展模块中以 C 级别执行安全递归调用的方法。如果递归代码不一定调用 Python 代码(自动跟踪其递归深度)，则需要使用它们。

• int Py_EnterRecursiveCall(const char ** where *)
  • 标记将要执行递归 C 级调用的点。

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

然后，该函数检查是否达到了递归限制。在这种情况下，将设置RuntimeError并返回非零值。否则，返回零。

• where *应该是由递归深度限制引起的字符串，例如" in instance check"要与RuntimeError消息串联。

• 无效Py_LeaveRecursiveCall()
  • 结束Py_EnterRecursiveCall()。每次对Py_EnterRecursiveCall()的“成功”调用都必须被调用一次。

Standard Exceptions

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

Notes:

• 这是其他标准异常的 Base Class。

• 这与weakref.ReferenceError相同。

• 仅在 Windows 上定义；pass测试定义了预处理程序宏MS_WINDOWS来保护使用此代码的代码。

• 2.5 版的新Function。

• 仅在 VMS 上定义；pass测试定义了预处理程序宏__VMS来保护使用此代码的代码。

标准警告类别

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

Notes:

• 这是其他标准警告类别的 Base Class。

String Exceptions

在 2.6 版中更改：引发或捕获的所有异常都必须来自BaseException。现在try引发字符串异常会引发TypeError。