Printing and clearing¶

voidPyErr_Clear()¶

為穩定 ABI 的一部分.

Clear the error indicator. If the error indicator is not set, there is noeffect.

voidPyErr_PrintEx(intset_sys_last_vars)¶

為穩定 ABI 的一部分.

Print a standard traceback tosys.stderr and clear the error indicator.Unless the error is aSystemExit, in that case no traceback isprinted and the Python process will exit with the error code specified bytheSystemExit instance.

Call this functiononly when the error indicator is set. Otherwise itwill cause a fatal error!

Ifset_sys_last_vars is nonzero, the variablesys.last_exc isset to the printed exception. For backwards compatibility, thedeprecated variablessys.last_type,sys.last_value andsys.last_traceback are also set to the type, value and tracebackof this exception, respectively.

在 3.12 版的變更:The setting ofsys.last_exc was added.

voidPyErr_Print()¶

為穩定 ABI 的一部分.

PyErr_PrintEx(1) 的別名。

voidPyErr_WriteUnraisable(PyObject*obj)¶

為穩定 ABI 的一部分.

Callsys.unraisablehook() using the current exception andobjargument.

This utility function prints a warning message tosys.stderr when anexception has been set but it is impossible for the interpreter to actuallyraise the exception. It is used, for example, when an exception occurs in an__del__() method.

The function is called with a single argumentobj that identifies the contextin which the unraisable exception occurred. If possible,the repr ofobj will be printed in the warning message.Ifobj isNULL, only the traceback is printed.

An exception must be set when calling this function.

在 3.4 版的變更:Print a traceback. Print only traceback ifobj isNULL.

在 3.8 版的變更:使用sys.unraisablehook()。

voidPyErr_FormatUnraisable(constchar*format,...)¶

Similar toPyErr_WriteUnraisable(), but theformat and subsequentparameters help format the warning message; they have the same meaning andvalues as inPyUnicode_FromFormat().PyErr_WriteUnraisable(obj) is roughly equivalent toPyErr_FormatUnraisable("Exceptionignoredin:%R",obj).Ifformat isNULL, only the traceback is printed.

在 3.13 版被加入.

voidPyErr_DisplayException(PyObject*exc)¶

為穩定 ABI 的一部分 自 3.12 版本開始.

Print the standard traceback display ofexc tosys.stderr, includingchained exceptions and notes.

在 3.12 版被加入.

Raising exceptions¶

These functions help you set the current thread's error indicator.For convenience, some of these functions will always return aNULL pointer for use in areturn statement.

voidPyErr_SetString(PyObject*type,constchar*message)¶

為穩定 ABI 的一部分.

This is the most common way to set the error indicator. The first argumentspecifies the exception type; it is normally one of the standard exceptions,e.g.PyExc_RuntimeError. You need not create a newstrong reference to it (e.g. withPy_INCREF()).The second argument is an error message; it is decoded from'utf-8'.

voidPyErr_SetObject(PyObject*type,PyObject*value)¶

為穩定 ABI 的一部分.

This function is similar toPyErr_SetString() but lets you specify anarbitrary Python object for the "value" of the exception.

PyObject*PyErr_Format(PyObject*exception,constchar*format,...)¶

回傳值：總是為 NULL。 為穩定 ABI 的一部分.

This function sets the error indicator and returnsNULL.exceptionshould be a Python exception class. Theformat and subsequentparameters help format the error message; they have the same meaning andvalues as inPyUnicode_FromFormat().format is an ASCII-encodedstring.

PyObject*PyErr_FormatV(PyObject*exception,constchar*format,va_listvargs)¶

回傳值：總是為 NULL。 為穩定 ABI 的一部分 自 3.5 版本開始.

Same asPyErr_Format(), but taking ava_list argument ratherthan a variable number of arguments.

在 3.5 版被加入.

voidPyErr_SetNone(PyObject*type)¶

為穩定 ABI 的一部分.

This is a shorthand forPyErr_SetObject(type,Py_None).

intPyErr_BadArgument()¶

為穩定 ABI 的一部分.

This is a shorthand forPyErr_SetString(PyExc_TypeError,message), wheremessage indicates that a built-in operation was invoked with an illegalargument. It is mostly for internal use.

PyObject*PyErr_NoMemory()¶

回傳值：總是為 NULL。 為穩定 ABI 的一部分.

This is a shorthand forPyErr_SetNone(PyExc_MemoryError); it returnsNULLso an object allocation function can writereturnPyErr_NoMemory(); when itruns out of memory.

PyObject*PyErr_SetFromErrno(PyObject*type)¶

回傳值：總是為 NULL。 為穩定 ABI 的一部分.

This is a convenience function to raise an exception when a C library functionhas returned an error and set the C variableerrno. It constructs atuple object whose first item is the integererrno value and whosesecond item is the corresponding error message (gotten fromstrerror()),and then callsPyErr_SetObject(type,object). On Unix, when theerrno value isEINTR, indicating an interrupted system call,this callsPyErr_CheckSignals(), and if that set the error indicator,leaves it set to that. The function always returnsNULL, so a wrapperfunction around a system call can writereturnPyErr_SetFromErrno(type);when the system call returns an error.

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

回傳值：總是為 NULL。 為穩定 ABI 的一部分.

Similar toPyErr_SetFromErrno(), with the additional behavior that iffilenameObject is notNULL, it is passed to the constructor oftype asa third parameter. In the case ofOSError exception,this is used to define thefilename attribute of theexception instance.

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

回傳值：總是為 NULL。 為穩定 ABI 的一部分 自 3.7 版本開始.

Similar toPyErr_SetFromErrnoWithFilenameObject(), but takes a secondfilename object, for raising errors when a function that takes two filenamesfails.

在 3.4 版被加入.

PyObject*PyErr_SetFromErrnoWithFilename(PyObject*type,constchar*filename)¶

回傳值：總是為 NULL。 為穩定 ABI 的一部分.

Similar toPyErr_SetFromErrnoWithFilenameObject(), but the filenameis given as a C string.filename is decoded from thefilesystemencoding and error handler.

PyObject*PyErr_SetFromWindowsErr(intierr)¶

回傳值：總是為 NULL。 為穩定 ABI 的一部分 on Windows 自 3.7 版本開始.

This is a convenience function to raiseOSError. If called withierr of0, the error code returned by a call toGetLastError()is used instead. It calls the Win32 functionFormatMessage() to retrievethe Windows description of error code given byierr orGetLastError(),then it constructs aOSError object with thewinerrorattribute set to the error code, thestrerror attributeset to the corresponding error message (gotten fromFormatMessage()), and then callsPyErr_SetObject(PyExc_OSError,object). This function always returnsNULL.

適用: Windows.

PyObject*PyErr_SetExcFromWindowsErr(PyObject*type,intierr)¶

回傳值：總是為 NULL。 為穩定 ABI 的一部分 on Windows 自 3.7 版本開始.

Similar toPyErr_SetFromWindowsErr(), with an additional parameterspecifying the exception type to be raised.

適用: Windows.

PyObject*PyErr_SetFromWindowsErrWithFilename(intierr,constchar*filename)¶

回傳值：總是為 NULL。 為穩定 ABI 的一部分 on Windows 自 3.7 版本開始.

Similar toPyErr_SetFromWindowsErr(), with the additional behaviorthat iffilename is notNULL, it is decoded from the filesystemencoding (os.fsdecode()) and passed to the constructor ofOSError as a third parameter to be used to define thefilename attribute of the exception instance.

適用: Windows.

PyObject*PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject*type,intierr,PyObject*filename)¶

回傳值：總是為 NULL。 為穩定 ABI 的一部分 on Windows 自 3.7 版本開始.

Similar toPyErr_SetExcFromWindowsErr(), with the additional behaviorthat iffilename is notNULL, it is passed to the constructor ofOSError as a third parameter to be used to define thefilename attribute of the exception instance.

適用: Windows.

PyObject*PyErr_SetExcFromWindowsErrWithFilenameObjects(PyObject*type,intierr,PyObject*filename,PyObject*filename2)¶

回傳值：總是為 NULL。 為穩定 ABI 的一部分 on Windows 自 3.7 版本開始.

Similar toPyErr_SetExcFromWindowsErrWithFilenameObject(),but accepts a second filename object.

適用: Windows.

在 3.4 版被加入.

PyObject*PyErr_SetExcFromWindowsErrWithFilename(PyObject*type,intierr,constchar*filename)¶

回傳值：總是為 NULL。 為穩定 ABI 的一部分 on Windows 自 3.7 版本開始.

Similar toPyErr_SetFromWindowsErrWithFilename(), with an additionalparameter specifying the exception type to be raised.

適用: Windows.

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

回傳值：總是為 NULL。 為穩定 ABI 的一部分 自 3.7 版本開始.

This is a convenience function to raiseImportError.msg will beset as the exception's message string.name andpath, both of which canbeNULL, will be set as theImportError's respectivenameandpath attributes.

在 3.3 版被加入.

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

回傳值：總是為 NULL。 為穩定 ABI 的一部分 自 3.6 版本開始.

Much likePyErr_SetImportError() but this function allows forspecifying a subclass ofImportError to raise.

在 3.6 版被加入.

voidPyErr_SyntaxLocationObject(PyObject*filename,intlineno,intcol_offset)¶

Set file, line, and offset information for the current exception. If thecurrent exception is not aSyntaxError, then it sets additionalattributes, which make the exception printing subsystem think the exceptionis aSyntaxError.

在 3.4 版被加入.

voidPyErr_SyntaxLocationEx(constchar*filename,intlineno,intcol_offset)¶

為穩定 ABI 的一部分 自 3.7 版本開始.

LikePyErr_SyntaxLocationObject(), butfilename is a byte stringdecoded from thefilesystem encoding and error handler.

在 3.2 版被加入.

voidPyErr_SyntaxLocation(constchar*filename,intlineno)¶

為穩定 ABI 的一部分.

LikePyErr_SyntaxLocationEx(), but thecol_offset parameter isomitted.

voidPyErr_BadInternalCall()¶

為穩定 ABI 的一部分.

This is a shorthand forPyErr_SetString(PyExc_SystemError,message),wheremessage indicates that an internal operation (e.g. a Python/C APIfunction) was invoked with an illegal argument. It is mostly for internaluse.

Issuing warnings¶

Use these functions to issue warnings from C code. They mirror similarfunctions exported by the Pythonwarnings module. They normallyprint a warning message tosys.stderr; however, it isalso possible that the user has specified that warnings are to be turned intoerrors, and in that case they will raise an exception. It is also possible thatthe functions raise an exception because of a problem with the warning machinery.The return value is0 if no exception is raised, or-1 if an exceptionis raised. (It is not possible to determine whether a warning message isactually printed, nor what the reason is for the exception; this isintentional.) If an exception is raised, the caller should do its normalexception handling (for example,Py_DECREF() owned references and returnan error value).

intPyErr_WarnEx(PyObject*category,constchar*message,Py_ssize_tstack_level)¶

為穩定 ABI 的一部分.

Issue a warning message. Thecategory argument is a warning category (seebelow) orNULL; themessage argument is a UTF-8 encoded string.stack_level is apositive number giving a number of stack frames; the warning will be issued fromthe currently executing line of code in that stack frame. Astack_level of 1is the function callingPyErr_WarnEx(), 2 is the function above that,and so forth.

Warning categories must be subclasses ofPyExc_Warning;PyExc_Warning is a subclass ofPyExc_Exception;the default warning category isPyExc_RuntimeWarning. The standardPython warning categories are available as global variables whose names areenumerated atStandard Warning Categories.

For information about warning control, see the documentation for thewarnings module and the-W option in the command linedocumentation. There is no C API for warning control.

intPyErr_WarnExplicitObject(PyObject*category,PyObject*message,PyObject*filename,intlineno,PyObject*module,PyObject*registry)¶

Issue a warning message with explicit control over all warning attributes. Thisis a straightforward wrapper around the Python functionwarnings.warn_explicit(); see there for more information. Themoduleandregistry arguments may be set toNULL to get the default effectdescribed there.

在 3.4 版被加入.

intPyErr_WarnExplicit(PyObject*category,constchar*message,constchar*filename,intlineno,constchar*module,PyObject*registry)¶

為穩定 ABI 的一部分.

Similar toPyErr_WarnExplicitObject() except thatmessage andmodule are UTF-8 encoded strings, andfilename is decoded from thefilesystem encoding and error handler.

intPyErr_WarnFormat(PyObject*category,Py_ssize_tstack_level,constchar*format,...)¶

為穩定 ABI 的一部分.

Function similar toPyErr_WarnEx(), but usePyUnicode_FromFormat() to format the warning message.format isan ASCII-encoded string.

在 3.2 版被加入.

intPyErr_ResourceWarning(PyObject*source,Py_ssize_tstack_level,constchar*format,...)¶

為穩定 ABI 的一部分 自 3.6 版本開始.

Function similar toPyErr_WarnFormat(), butcategory isResourceWarning and it passessource towarnings.WarningMessage.

在 3.6 版被加入.

Querying the error indicator¶

PyObject*PyErr_Occurred()¶

回傳值：借用參照。 為穩定 ABI 的一部分.

Test whether the error indicator is set. If set, return the exceptiontype(the first argument to the last call to one of thePyErr_Set*functions or toPyErr_Restore()). If not set, returnNULL. You do notown a reference to the return value, so you do not need toPy_DECREF()it.

The caller must hold the GIL.

備註

Do not compare the return value to a specific exception; usePyErr_ExceptionMatches() instead, shown below. (The comparison couldeasily fail since the exception may be an instance instead of a class, in thecase of a class exception, or it may be a subclass of the expected exception.)

intPyErr_ExceptionMatches(PyObject*exc)¶

為穩定 ABI 的一部分.

Equivalent toPyErr_GivenExceptionMatches(PyErr_Occurred(),exc). Thisshould only be called when an exception is actually set; a memory accessviolation will occur if no exception has been raised.

intPyErr_GivenExceptionMatches(PyObject*given,PyObject*exc)¶

為穩定 ABI 的一部分.

Return true if thegiven exception matches the exception type inexc. Ifexc is a class object, this also returns true whengiven is an instanceof a subclass. Ifexc is a tuple, all exception types in the tuple (andrecursively in subtuples) are searched for a match.

PyObject*PyErr_GetRaisedException(void)¶

回傳值：新的參照。 為穩定 ABI 的一部分 自 3.12 版本開始.

Return the exception currently being raised, clearing the error indicator atthe same time. ReturnNULL if the error indicator is not set.

This function is used by code that needs to catch exceptions,or code that needs to save and restore the error indicator temporarily.

舉例來說：

{PyObject*exc=PyErr_GetRaisedException();/* ... code that might produce other errors ... */PyErr_SetRaisedException(exc);}

也參考

PyErr_GetHandledException(),to save the exception currently being handled.

在 3.12 版被加入.

voidPyErr_SetRaisedException(PyObject*exc)¶

為穩定 ABI 的一部分 自 3.12 版本開始.

Setexc as the exception currently being raised,clearing the existing exception if one is set.

警告

This call steals a reference toexc, which must be a valid exception.

在 3.12 版被加入.

voidPyErr_Fetch(PyObject**ptype,PyObject**pvalue,PyObject**ptraceback)¶

為穩定 ABI 的一部分.

在 3.12 版之後被棄用:UsePyErr_GetRaisedException() instead.

Retrieve the error indicator into three variables whose addresses are passed.If the error indicator is not set, set all three variables toNULL. If it isset, it will be cleared and you own a reference to each object retrieved. Thevalue and traceback object may beNULL even when the type object is not.

備註

This function is normally only used by legacy code that needs to catchexceptions or save and restore the error indicator temporarily.

舉例來說：

{PyObject*type,*value,*traceback;PyErr_Fetch(&type,&value,&traceback);/* ... code that might produce other errors ... */PyErr_Restore(type,value,traceback);}

voidPyErr_Restore(PyObject*type,PyObject*value,PyObject*traceback)¶

為穩定 ABI 的一部分.

在 3.12 版之後被棄用:UsePyErr_SetRaisedException() instead.

Set the error indicator from the three objects,type,value, andtraceback,clearing the existing exception if one is set.If the objects areNULL, the errorindicator is cleared. Do not pass aNULL type and non-NULL value ortraceback. The exception type should be a class. Do not pass an invalidexception type or value. (Violating these rules will cause subtle problemslater.) This call takes away a reference to each object: you must own areference to each object before the call and after the call you no longer ownthese references. (If you don't understand this, don't use this function. Iwarned you.)

備註

This function is normally only used by legacy code that needs tosave and restore the error indicator temporarily.UsePyErr_Fetch() to save the current error indicator.

voidPyErr_NormalizeException(PyObject**exc,PyObject**val,PyObject**tb)¶

為穩定 ABI 的一部分.

在 3.12 版之後被棄用:UsePyErr_GetRaisedException() instead,to avoid any possible de-normalization.

Under certain circumstances, the values returned byPyErr_Fetch() belowcan be "unnormalized", meaning that*exc is a class object but*val isnot an instance of the same class. This function can be used to instantiatethe class in that case. If the values are already normalized, nothing happens.The delayed normalization is implemented to improve performance.

備註

This functiondoes not implicitly set the__traceback__attribute on the exception value. If setting the tracebackappropriately is desired, the following additional snippet is needed:

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

PyObject*PyErr_GetHandledException(void)¶

為穩定 ABI 的一部分 自 3.11 版本開始.

Retrieve the active exception instance, as would be returned bysys.exception().This refers to an exception that wasalready caught, not to an exception that wasfreshly raised. Returns a new reference to the exception orNULL.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 exceptionstate temporarily. UsePyErr_SetHandledException() to restore orclear the exception state.

在 3.11 版被加入.

voidPyErr_SetHandledException(PyObject*exc)¶

為穩定 ABI 的一部分 自 3.11 版本開始.

Set the active exception, as known fromsys.exception(). This refersto an exception that wasalready caught, not to an exception that wasfreshly raised.To clear the exception state, passNULL.

備註

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 exceptionstate temporarily. UsePyErr_GetHandledException() to get the exceptionstate.

在 3.11 版被加入.

voidPyErr_GetExcInfo(PyObject**ptype,PyObject**pvalue,PyObject**ptraceback)¶

為穩定 ABI 的一部分 自 3.7 版本開始.

Retrieve the old-style representation of the exception info, as known fromsys.exc_info(). This refers to an exception that wasalready caught,not to an exception that was freshly raised. Returns new references for thethree objects, any of which may beNULL. Does not modify the exceptioninfo state. This function is kept for backwards compatibility. Prefer usingPyErr_GetHandledException().

備註

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 exceptionstate temporarily. UsePyErr_SetExcInfo() to restore or clear theexception state.

在 3.3 版被加入.

voidPyErr_SetExcInfo(PyObject*type,PyObject*value,PyObject*traceback)¶

為穩定 ABI 的一部分 自 3.7 版本開始.

Set the exception info, as known fromsys.exc_info(). This refersto an exception that wasalready caught, not to an exception that wasfreshly raised. This function steals the references of the arguments.To clear the exception state, passNULL for all three arguments.This function is kept for backwards compatibility. Prefer usingPyErr_SetHandledException().

備註

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 exceptionstate temporarily. UsePyErr_GetExcInfo() to read the exceptionstate.

在 3.3 版被加入.

在 3.11 版的變更:Thetype andtraceback arguments are no longer used andcan be NULL. The interpreter now derives them from the exceptioninstance (thevalue argument). The function still stealsreferences of all three arguments.

Signal Handling¶

intPyErr_CheckSignals()¶

為穩定 ABI 的一部分.

This function interacts with Python's signal handling.

If the function is called from the main thread and under the main Pythoninterpreter, it checks whether a signal has been sent to the processesand if so, invokes the corresponding signal handler. If thesignalmodule is supported, this can invoke a signal handler written in Python.

The function attempts to handle all pending signals, and then returns0.However, if a Python signal handler raises an exception, the errorindicator is set and the function returns-1 immediately (such thatother pending signals may not have been handled yet: they will be on thenextPyErr_CheckSignals() invocation).

If the function is called from a non-main thread, or under a non-mainPython interpreter, it does nothing and returns0.

This function can be called by long-running C code that wants tobe interruptible by user requests (such as by pressing Ctrl-C).

備註

The default Python signal handler forSIGINT raises theKeyboardInterrupt exception.

voidPyErr_SetInterrupt()¶

為穩定 ABI 的一部分.

Simulate the effect of aSIGINT signal arriving.This is equivalent toPyErr_SetInterruptEx(SIGINT).

備註

This function is async-signal-safe. It can be called withouttheGIL and from a C signal handler.

intPyErr_SetInterruptEx(intsignum)¶

為穩定 ABI 的一部分 自 3.10 版本開始.

Simulate the effect of a signal arriving. The next timePyErr_CheckSignals() is called, the Python signal handler forthe given signal number will be called.

This function can be called by C code that sets up its own signal handlingand wants Python signal handlers to be invoked as expected when aninterruption is requested (for example when the user presses Ctrl-Cto interrupt an operation).

If the given signal isn't handled by Python (it was set tosignal.SIG_DFL orsignal.SIG_IGN), it will be ignored.

Ifsignum is outside of the allowed range of signal numbers,-1is returned. Otherwise,0 is returned. The error indicator isnever changed by this function.

備註

This function is async-signal-safe. It can be called withouttheGIL and from a C signal handler.

在 3.10 版被加入.

intPySignal_SetWakeupFd(intfd)¶

This utility function specifies a file descriptor to which the signal numberis written as a single byte whenever a signal is received.fd must benon-blocking. It returns the previous such file descriptor.

The value-1 disables the feature; this is the initial state.This is equivalent tosignal.set_wakeup_fd() in Python, but without anyerror checking.fd should be a valid file descriptor. The function shouldonly be called from the main thread.

在 3.5 版的變更:On Windows, the function now also supports socket handles.

例外類別¶

PyObject*PyErr_NewException(constchar*name,PyObject*base,PyObject*dict)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

This utility function creates and returns a new exception class. Thenameargument must be the name of the new exception, a C string of the formmodule.classname. Thebase anddict arguments are normallyNULL.This creates a class object derived fromException (accessible in C asPyExc_Exception).

The__module__ attribute of the new class is set to the first part (upto the last dot) of thename argument, and the class name is set to the lastpart (after the last dot). Thebase argument can be used to specify alternatebase classes; it can either be only one class or a tuple of classes. Thedictargument can be used to specify a dictionary of class variables and methods.

PyObject*PyErr_NewExceptionWithDoc(constchar*name,constchar*doc,PyObject*base,PyObject*dict)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Same asPyErr_NewException(), except that the new exception class caneasily be given a docstring: Ifdoc is non-NULL, it will be used as thedocstring for the exception class.

在 3.2 版被加入.

例外物件¶

PyObject*PyException_GetTraceback(PyObject*ex)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Return the traceback associated with the exception as a new reference, asaccessible from Python through the__traceback__attribute. If there is notraceback associated, this returnsNULL.

intPyException_SetTraceback(PyObject*ex,PyObject*tb)¶

為穩定 ABI 的一部分.

Set the traceback associated with the exception totb. UsePy_None toclear it.

PyObject*PyException_GetContext(PyObject*ex)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Return the context (another exception instance during whose handlingex wasraised) associated with the exception as a new reference, as accessible fromPython through the__context__ attribute.If there is no context associated, this returnsNULL.

voidPyException_SetContext(PyObject*ex,PyObject*ctx)¶

為穩定 ABI 的一部分.

Set the context associated with the exception toctx. UseNULL to clearit. There is no type check to make sure thatctx is an exception instance.This steals a reference toctx.

PyObject*PyException_GetCause(PyObject*ex)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Return the cause (either an exception instance, orNone,set byraise...from...) associated with the exception as a newreference, as accessible from Python through the__cause__ attribute.

voidPyException_SetCause(PyObject*ex,PyObject*cause)¶

為穩定 ABI 的一部分.

Set the cause associated with the exception tocause. UseNULL to clearit. There is no type check to make sure thatcause is either an exceptioninstance orNone. This steals a reference tocause.

The__suppress_context__ attribute is implicitly settoTrue by this function.

PyObject*PyException_GetArgs(PyObject*ex)¶

回傳值：新的參照。 為穩定 ABI 的一部分 自 3.12 版本開始.

Returnargs of exceptionex.

voidPyException_SetArgs(PyObject*ex,PyObject*args)¶

為穩定 ABI 的一部分 自 3.12 版本開始.

Setargs of exceptionex toargs.

PyObject*PyUnstable_Exc_PrepReraiseStar(PyObject*orig,PyObject*excs)¶

這是不穩定 API，它可能在小版本發布中沒有任何警告地被變更。

Implement part of the interpreter's implementation ofexcept*.orig is the original exception that was caught, andexcs is the list ofthe exceptions that need to be raised. This list contains the unhandledpart oforig, if any, as well as the exceptions that were raised from theexcept* clauses (so they have a different traceback fromorig) andthose that were reraised (and have the same traceback asorig).Return theExceptionGroup that needs to be reraised in the end, orNone if there is nothing to reraise.

在 3.12 版被加入.

Unicode Exception Objects¶

The following functions are used to create and modify Unicode exceptions from C.

PyObject*PyUnicodeDecodeError_Create(constchar*encoding,constchar*object,Py_ssize_tlength,Py_ssize_tstart,Py_ssize_tend,constchar*reason)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Create aUnicodeDecodeError object with the attributesencoding,object,length,start,end andreason.encoding andreason areUTF-8 encoded strings.

PyObject*PyUnicodeDecodeError_GetEncoding(PyObject*exc)¶

PyObject*PyUnicodeEncodeError_GetEncoding(PyObject*exc)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Return theencoding attribute of the given exception object.

PyObject*PyUnicodeDecodeError_GetObject(PyObject*exc)¶

PyObject*PyUnicodeEncodeError_GetObject(PyObject*exc)¶

PyObject*PyUnicodeTranslateError_GetObject(PyObject*exc)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Return theobject attribute of the given exception object.

intPyUnicodeDecodeError_GetStart(PyObject*exc,Py_ssize_t*start)¶

intPyUnicodeEncodeError_GetStart(PyObject*exc,Py_ssize_t*start)¶

intPyUnicodeTranslateError_GetStart(PyObject*exc,Py_ssize_t*start)¶

為穩定 ABI 的一部分.

Get thestart attribute of the given exception object and place it into*start.start must not beNULL. Return0 on success,-1 onfailure.

intPyUnicodeDecodeError_SetStart(PyObject*exc,Py_ssize_tstart)¶

intPyUnicodeEncodeError_SetStart(PyObject*exc,Py_ssize_tstart)¶

intPyUnicodeTranslateError_SetStart(PyObject*exc,Py_ssize_tstart)¶

為穩定 ABI 的一部分.

Set thestart attribute of the given exception object tostart. Return0 on success,-1 on failure.

intPyUnicodeDecodeError_GetEnd(PyObject*exc,Py_ssize_t*end)¶

intPyUnicodeEncodeError_GetEnd(PyObject*exc,Py_ssize_t*end)¶

intPyUnicodeTranslateError_GetEnd(PyObject*exc,Py_ssize_t*end)¶

為穩定 ABI 的一部分.

Get theend attribute of the given exception object and place it into*end.end must not beNULL. Return0 on success,-1 onfailure.

intPyUnicodeDecodeError_SetEnd(PyObject*exc,Py_ssize_tend)¶

intPyUnicodeEncodeError_SetEnd(PyObject*exc,Py_ssize_tend)¶

intPyUnicodeTranslateError_SetEnd(PyObject*exc,Py_ssize_tend)¶

為穩定 ABI 的一部分.

Set theend attribute of the given exception object toend. Return0on success,-1 on failure.

PyObject*PyUnicodeDecodeError_GetReason(PyObject*exc)¶

PyObject*PyUnicodeEncodeError_GetReason(PyObject*exc)¶

PyObject*PyUnicodeTranslateError_GetReason(PyObject*exc)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Return thereason attribute of the given exception object.

intPyUnicodeDecodeError_SetReason(PyObject*exc,constchar*reason)¶

intPyUnicodeEncodeError_SetReason(PyObject*exc,constchar*reason)¶

intPyUnicodeTranslateError_SetReason(PyObject*exc,constchar*reason)¶

為穩定 ABI 的一部分.

Set thereason attribute of the given exception object toreason. Return0 on success,-1 on failure.

Recursion Control¶

These two functions provide a way to perform safe recursive calls at the Clevel, both in the core and in extension modules. They are needed if therecursive code does not necessarily invoke Python code (which tracks itsrecursion depth automatically).They are also not needed fortp_call implementationsbecause thecall protocol takes care of recursion handling.

intPy_EnterRecursiveCall(constchar*where)¶

為穩定 ABI 的一部分 自 3.9 版本開始.

Marks a point where a recursive C-level call is about to be performed.

IfUSE_STACKCHECK is defined, this function checks if the OSstack overflowed usingPyOS_CheckStack(). If this is the case, itsets aMemoryError and returns a nonzero value.

The function then checks if the recursion limit is reached. If this is thecase, aRecursionError is set and a nonzero value is returned.Otherwise, zero is returned.

where should be a UTF-8 encoded string such as"ininstancecheck" tobe concatenated to theRecursionError message caused by the recursiondepth limit.

在 3.9 版的變更:This function is now also available in thelimited API.

voidPy_LeaveRecursiveCall(void)¶

為穩定 ABI 的一部分 自 3.9 版本開始.

Ends aPy_EnterRecursiveCall(). Must be called once for eachsuccessful invocation ofPy_EnterRecursiveCall().

在 3.9 版的變更:This function is now also available in thelimited API.

Properly implementingtp_repr for container types requiresspecial recursion handling. In addition to protecting the stack,tp_repr also needs to track objects to prevent cycles. Thefollowing two functions facilitate this functionality. Effectively,these are the C equivalent toreprlib.recursive_repr().

intPy_ReprEnter(PyObject*object)¶

為穩定 ABI 的一部分.

Called at the beginning of thetp_repr implementation todetect cycles.

If the object has already been processed, the function returns apositive integer. In that case thetp_repr implementationshould return a string object indicating a cycle. As examples,dict objects return{...} andlist objectsreturn[...].

The function will return a negative integer if the recursion limitis reached. In that case thetp_repr implementation shouldtypically returnNULL.

Otherwise, the function returns zero and thetp_reprimplementation can continue normally.

voidPy_ReprLeave(PyObject*object)¶

為穩定 ABI 的一部分.

Ends aPy_ReprEnter(). Must be called once for eachinvocation ofPy_ReprEnter() that returns zero.

Standard Exceptions¶

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

These are compatibility aliases toPyExc_OSError:

註解：

This is a base class for other standard exceptions.

Only defined on Windows; protect code that uses this by testing that thepreprocessor macroMS_WINDOWS is defined.

Standard Warning Categories¶

All standard Python warning categories are available as global variables whosenames arePyExc_ followed by the Python exception name. These have the typePyObject*; they are all class objects. For completeness, here are allthe variables:

註解：

This is a base class for other standard warning categories.