1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
|
from .object cimport PyObject
cdef extern from "Python.h":
#####################################################################
# 3. Exception Handling
#####################################################################
# 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 Unix errno variable: there is a global indicator (per
# thread) of the last error that occurred. Most functions don't
# clear this on success, but will set it to indicate the cause of
# the error on failure. Most 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).
# When a function must fail because some function it called
# failed, it generally doesn't set the error indicator; the
# function it called already set it. It is responsible for either
# handling the error and clearing the exception or returning after
# cleaning up any resources it holds (such as object references or
# memory allocations); it should not continue normally if it is
# not prepared to handle the error. If returning due to an error,
# it is important to indicate to the caller that an error has been
# set. If the error is not handled or carefully propagated,
# additional calls into the Python/C API may not behave as
# intended and may fail in mysterious ways.
# The error indicator consists of three Python objects
# corresponding to the Python variables sys.exc_type,
# sys.exc_value and sys.exc_traceback. API functions exist to
# interact with the error indicator in various ways. There is a
# separate error indicator for each thread.
void PyErr_Print()
# Print a standard traceback to sys.stderr and clear the error
# indicator. Call this function only when the error indicator is
# set. (Otherwise it will cause a fatal error!)
PyObject* PyErr_Occurred()
# Return value: Borrowed reference.
# 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. Note: Do not compare the
# return value to a specific exception; use
# PyErr_ExceptionMatches() instead, shown below. (The comparison
# could easily fail since the exception may be an instance instead
# of a class, in the case of a class exception, or it may be a
# subclass of the expected exception.)
bint PyErr_ExceptionMatches(object exc)
# Equivalent to "PyErr_GivenExceptionMatches(PyErr_Occurred(),
# exc)". This should only be called when an exception is actually
# set; a memory access violation will occur if no exception has
# been raised.
bint PyErr_GivenExceptionMatches(object given, object exc)
# Return true if the given exception matches the exception in
# exc. If exc is a class object, this also returns true when given
# is an instance of a subclass. If exc is a tuple, all exceptions
# in the tuple (and recursively in subtuples) are searched for a
# match. If given is NULL, a memory access violation will occur.
void PyErr_NormalizeException(PyObject** exc, PyObject** val, PyObject** tb)
# Under certain circumstances, the values returned by
# PyErr_Fetch() below can be ``unnormalized'', meaning that *exc
# is a class object but *val is not an instance of the same
# class. This function can be used to instantiate the class in
# that case. If the values are already normalized, nothing
# happens. The delayed normalization is implemented to improve
# performance.
void PyErr_Clear()
# Clear the error indicator. If the error indicator is not set, there is no effect.
void PyErr_Fetch(PyObject** ptype, PyObject** pvalue, PyObject** ptraceback)
# Retrieve the error indicator into three variables whose
# addresses are passed. If the error indicator is not set, set all
# three variables to NULL. If it is set, it will be cleared and
# you own a reference to each object retrieved. The value and
# traceback object may be NULL even when the type object is
# not. Note: This function is normally only used by code that
# needs to handle exceptions or by code that needs to save and
# restore the error indicator temporarily.
void PyErr_Restore(PyObject* type, PyObject* value, PyObject* traceback)
# Set the error indicator from the three objects. If the error
# indicator is already set, it is cleared first. If the objects
# are NULL, the error indicator is cleared. Do not pass a NULL
# type and non-NULL value or traceback. The exception type should
# be a class. Do not pass an invalid exception type or
# value. (Violating these rules will cause subtle problems later.)
# This call takes away a reference to each object: you must own a
# reference to each object before the call and after the call you
# no longer own these references. (If you don't understand this,
# don't use this function. I warned you.) Note: This function is
# normally only used by code that needs to save and restore the
# error indicator temporarily; use PyErr_Fetch() to save the
# current exception state.
void PyErr_SetString(object type, char *message)
# This is the most common way to set the error indicator. The
# first argument specifies the exception type; it is normally one
# of the standard exceptions, e.g. PyExc_RuntimeError. You need
# not increment its reference count. The second argument is an
# error message; it is converted to a string object.
void PyErr_SetObject(object type, object value)
# This function is similar to PyErr_SetString() but lets you
# specify an arbitrary Python object for the ``value'' of the
# exception.
PyObject* PyErr_Format(object exception, char *format, ...) except NULL
# Return value: Always NULL.
# This function sets the error indicator and returns
# NULL. exception should be a Python exception (class, not an
# instance). format should be a string, containing format codes,
# similar to printf(). The width.precision before a format code is
# parsed, but the width part is ignored.
void PyErr_SetNone(object type)
# This is a shorthand for "PyErr_SetObject(type, Py_None)".
int PyErr_BadArgument() except 0
# This is a shorthand for "PyErr_SetString(PyExc_TypeError,
# message)", where message indicates that a built-in operation was
# invoked with an illegal argument. It is mostly for internal use.
PyObject* PyErr_NoMemory() except NULL
# Return value: Always NULL.
# This is a shorthand for "PyErr_SetNone(PyExc_MemoryError)"; it
# returns NULL so an object allocation function can write "return
# PyErr_NoMemory();" when it runs out of memory.
PyObject* PyErr_SetFromErrno(object type) except NULL
# Return value: Always NULL.
# This is a convenience function to raise an exception when a C
# library function has returned an error and set the C variable
# errno. It constructs a tuple object whose first item is the
# integer errno value and whose second item is the corresponding
# error message (gotten from strerror()), and then calls
# "PyErr_SetObject(type, object)". On Unix, when the errno value
# is EINTR, indicating an interrupted system call, this calls
# PyErr_CheckSignals(), and if that set the error indicator,
# leaves it set to that. The function always returns NULL, so a
# wrapper function around a system call can write "return
# PyErr_SetFromErrno(type);" when the system call returns an
# error.
PyObject* PyErr_SetFromErrnoWithFilenameObject(object type, object filenameObject) except NULL
# Similar to PyErr_SetFromErrno(), with the additional behavior
# that if filenameObject is not NULL, it is passed to the
# constructor of type as a third parameter.
# In the case of OSError exception, this is used to define
# the filename attribute of the exception instance.
PyObject* PyErr_SetFromErrnoWithFilename(object type, char *filename) except NULL
# Return value: Always NULL. Similar to PyErr_SetFromErrno(),
# with the additional behavior that if filename is not NULL, it is
# passed to the constructor of type as a third parameter. In the
# case of exceptions such as IOError and OSError, this is used to
# define the filename attribute of the exception instance.
PyObject* PyErr_SetFromWindowsErr(int ierr) except NULL
# Return value: Always NULL. 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. Availability: Windows.
PyObject* PyErr_SetExcFromWindowsErr(object type, int ierr) except NULL
# Return value: Always NULL. Similar to
# PyErr_SetFromWindowsErr(), with an additional parameter
# specifying the exception type to be raised. Availability:
# Windows. New in version 2.3.
PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, char *filename) except NULL
# Return value: Always NULL. Similar to
# PyErr_SetFromWindowsErr(), with the additional behavior that if
# filename is not NULL, it is passed to the constructor of
# WindowsError as a third parameter. Availability: Windows.
PyObject* PyErr_SetExcFromWindowsErrWithFilename(object type, int ierr, char *filename) except NULL
# Return value: Always NULL.
# Similar to PyErr_SetFromWindowsErrWithFilename(), with an
# additional parameter specifying the exception type to be
# raised. Availability: Windows.
void PyErr_BadInternalCall()
# This is a shorthand for "PyErr_SetString(PyExc_TypeError,
# message)", where message indicates that an internal operation
# (e.g. a Python/C API function) was invoked with an illegal
# argument. It is mostly for internal use.
int PyErr_WarnEx(object category, char *message, int stacklevel) except -1
# Issue a warning message. The category argument is a warning
# category (see below) or NULL; the message argument is a message
# string. stacklevel is a positive number giving a number of stack
# frames; the warning will be issued from the currently executing
# line of code in that stack frame. A stacklevel of 1 is the
# function calling PyErr_WarnEx(), 2 is the function above that,
# and so forth.
int PyErr_WarnExplicit(object category, char *message, char *filename, int lineno, char *module, object registry) except -1
# Issue a warning message with explicit control over all warning
# attributes. This is a straightforward wrapper around the Python
# function warnings.warn_explicit(), see there for more
# information. The module and registry arguments may be set to
# NULL to get the default effect described there.
int PyErr_CheckSignals() except -1
# This function interacts with Python's signal handling. It checks
# whether a signal has been sent to the processes and if so,
# invokes the corresponding signal handler. If the signal module
# is supported, this can invoke a signal handler written in
# Python. In all cases, the default effect for SIGINT is to raise
# the KeyboardInterrupt exception. If an exception is raised the
# error indicator is set and the function returns 1; otherwise the
# function returns 0. The error indicator may or may not be
# cleared if it was previously set.
void PyErr_SetInterrupt() nogil
# This function simulates the effect of a SIGINT signal arriving
# -- the next time PyErr_CheckSignals() is called,
# KeyboardInterrupt will be raised. It may be called without
# holding the interpreter lock.
object PyErr_NewException(char *name, object base, object dict)
# Return value: New reference.
# This utility function creates and returns a new exception
# object. The name argument must be the name of the new exception,
# a C string of the form module.class. The base and dict arguments
# are normally NULL. This creates a class object derived from
# Exception (accessible in C as PyExc_Exception).
void PyErr_WriteUnraisable(object obj)
# This utility function prints a warning message to sys.stderr
# when an exception has been set but it is impossible for the
# interpreter to actually raise the exception. It is used, for
# example, when an exception occurs in an __del__() method.
#
# The function is called with a single argument obj that
# identifies the context in which the unraisable exception
# occurred. The repr of obj will be printed in the warning
# message.
|
