Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | .. highlightlang:: c |
| 2 | |
| 3 | |
| 4 | .. _exceptionhandling: |
| 5 | |
| 6 | ****************** |
| 7 | Exception Handling |
| 8 | ****************** |
| 9 | |
| 10 | The functions described in this chapter will let you handle and raise Python |
| 11 | exceptions. It is important to understand some of the basics of Python |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 12 | exception handling. It works somewhat like the Unix :c:data:`errno` variable: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 13 | there is a global indicator (per thread) of the last error that occurred. Most |
| 14 | functions don't clear this on success, but will set it to indicate the cause of |
| 15 | the error on failure. Most functions also return an error indicator, usually |
| 16 | *NULL* if they are supposed to return a pointer, or ``-1`` if they return an |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 17 | integer (exception: the :c:func:`PyArg_\*` functions return ``1`` for success and |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 18 | ``0`` for failure). |
| 19 | |
| 20 | When a function must fail because some function it called failed, it generally |
| 21 | doesn't set the error indicator; the function it called already set it. It is |
| 22 | responsible for either handling the error and clearing the exception or |
| 23 | returning after cleaning up any resources it holds (such as object references or |
| 24 | memory allocations); it should *not* continue normally if it is not prepared to |
| 25 | handle the error. If returning due to an error, it is important to indicate to |
| 26 | the caller that an error has been set. If the error is not handled or carefully |
| 27 | propagated, additional calls into the Python/C API may not behave as intended |
| 28 | and may fail in mysterious ways. |
| 29 | |
| 30 | The error indicator consists of three Python objects corresponding to the result |
| 31 | of ``sys.exc_info()``. API functions exist to interact with the error indicator |
| 32 | in various ways. There is a separate error indicator for each thread. |
| 33 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 34 | .. XXX Order of these should be more thoughtful. |
| 35 | Either alphabetical or some kind of structure. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 36 | |
| 37 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 38 | .. c:function:: void PyErr_PrintEx(int set_sys_last_vars) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 39 | |
| 40 | Print a standard traceback to ``sys.stderr`` and clear the error indicator. |
| 41 | Call this function only when the error indicator is set. (Otherwise it will |
| 42 | cause a fatal error!) |
| 43 | |
Georg Brandl | 115fb35 | 2009-02-05 10:56:37 +0000 | [diff] [blame] | 44 | If *set_sys_last_vars* is nonzero, the variables :data:`sys.last_type`, |
| 45 | :data:`sys.last_value` and :data:`sys.last_traceback` will be set to the |
| 46 | type, value and traceback of the printed exception, respectively. |
| 47 | |
| 48 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 49 | .. c:function:: void PyErr_Print() |
Georg Brandl | 115fb35 | 2009-02-05 10:56:37 +0000 | [diff] [blame] | 50 | |
| 51 | Alias for ``PyErr_PrintEx(1)``. |
| 52 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 53 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 54 | .. c:function:: PyObject* PyErr_Occurred() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 55 | |
| 56 | Test whether the error indicator is set. If set, return the exception *type* |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 57 | (the first argument to the last call to one of the :c:func:`PyErr_Set\*` |
| 58 | functions or to :c:func:`PyErr_Restore`). If not set, return *NULL*. You do not |
| 59 | own a reference to the return value, so you do not need to :c:func:`Py_DECREF` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 60 | it. |
| 61 | |
| 62 | .. note:: |
| 63 | |
| 64 | Do not compare the return value to a specific exception; use |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 65 | :c:func:`PyErr_ExceptionMatches` instead, shown below. (The comparison could |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 66 | easily fail since the exception may be an instance instead of a class, in the |
| 67 | case of a class exception, or it may the a subclass of the expected exception.) |
| 68 | |
| 69 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 70 | .. c:function:: int PyErr_ExceptionMatches(PyObject *exc) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 71 | |
| 72 | Equivalent to ``PyErr_GivenExceptionMatches(PyErr_Occurred(), exc)``. This |
| 73 | should only be called when an exception is actually set; a memory access |
| 74 | violation will occur if no exception has been raised. |
| 75 | |
| 76 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 77 | .. c:function:: int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 78 | |
Benjamin Peterson | da10d3b | 2009-01-01 00:23:30 +0000 | [diff] [blame] | 79 | Return true if the *given* exception matches the exception in *exc*. If |
| 80 | *exc* is a class object, this also returns true when *given* is an instance |
| 81 | of a subclass. If *exc* is a tuple, all exceptions in the tuple (and |
| 82 | recursively in subtuples) are searched for a match. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 83 | |
| 84 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 85 | .. c:function:: void PyErr_NormalizeException(PyObject**exc, PyObject**val, PyObject**tb) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 86 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 87 | Under certain circumstances, the values returned by :c:func:`PyErr_Fetch` below |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 88 | can be "unnormalized", meaning that ``*exc`` is a class object but ``*val`` is |
| 89 | not an instance of the same class. This function can be used to instantiate |
| 90 | the class in that case. If the values are already normalized, nothing happens. |
| 91 | The delayed normalization is implemented to improve performance. |
| 92 | |
| 93 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 94 | .. c:function:: void PyErr_Clear() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 95 | |
| 96 | Clear the error indicator. If the error indicator is not set, there is no |
| 97 | effect. |
| 98 | |
| 99 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 100 | .. c:function:: void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 101 | |
| 102 | Retrieve the error indicator into three variables whose addresses are passed. |
| 103 | If the error indicator is not set, set all three variables to *NULL*. If it is |
| 104 | set, it will be cleared and you own a reference to each object retrieved. The |
| 105 | value and traceback object may be *NULL* even when the type object is not. |
| 106 | |
| 107 | .. note:: |
| 108 | |
| 109 | This function is normally only used by code that needs to handle exceptions or |
| 110 | by code that needs to save and restore the error indicator temporarily. |
| 111 | |
| 112 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 113 | .. c:function:: void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 114 | |
| 115 | Set the error indicator from the three objects. If the error indicator is |
| 116 | already set, it is cleared first. If the objects are *NULL*, the error |
| 117 | indicator is cleared. Do not pass a *NULL* type and non-*NULL* value or |
| 118 | traceback. The exception type should be a class. Do not pass an invalid |
| 119 | exception type or value. (Violating these rules will cause subtle problems |
| 120 | later.) This call takes away a reference to each object: you must own a |
| 121 | reference to each object before the call and after the call you no longer own |
| 122 | these references. (If you don't understand this, don't use this function. I |
| 123 | warned you.) |
| 124 | |
| 125 | .. note:: |
| 126 | |
| 127 | This function is normally only used by code that needs to save and restore the |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 128 | error indicator temporarily; use :c:func:`PyErr_Fetch` to save the current |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 129 | exception state. |
| 130 | |
| 131 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 132 | .. c:function:: void PyErr_SetString(PyObject *type, const char *message) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 133 | |
| 134 | This is the most common way to set the error indicator. The first argument |
| 135 | specifies the exception type; it is normally one of the standard exceptions, |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 136 | e.g. :c:data:`PyExc_RuntimeError`. You need not increment its reference count. |
Victor Stinner | 257d38f | 2010-10-09 10:12:11 +0000 | [diff] [blame] | 137 | The second argument is an error message; it is decoded from ``'utf-8``'. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 138 | |
| 139 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 140 | .. c:function:: void PyErr_SetObject(PyObject *type, PyObject *value) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 141 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 142 | This function is similar to :c:func:`PyErr_SetString` but lets you specify an |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 143 | arbitrary Python object for the "value" of the exception. |
| 144 | |
| 145 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 146 | .. c:function:: PyObject* PyErr_Format(PyObject *exception, const char *format, ...) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 147 | |
Antoine Pitrou | a66e029 | 2010-11-27 20:40:43 +0000 | [diff] [blame] | 148 | This function sets the error indicator and returns *NULL*. *exception* |
| 149 | should be a Python exception class. The *format* and subsequent |
| 150 | parameters help format the error message; they have the same meaning and |
Victor Stinner | b1dbd10 | 2010-12-28 11:02:46 +0000 | [diff] [blame] | 151 | values as in :c:func:`PyUnicode_FromFormat`. *format* is an ASCII-encoded |
Victor Stinner | 555a24f | 2010-12-27 01:49:26 +0000 | [diff] [blame] | 152 | string. |
Mark Dickinson | 6ce4a9a | 2009-11-16 17:00:11 +0000 | [diff] [blame] | 153 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 154 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 155 | .. c:function:: void PyErr_SetNone(PyObject *type) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 156 | |
| 157 | This is a shorthand for ``PyErr_SetObject(type, Py_None)``. |
| 158 | |
| 159 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 160 | .. c:function:: int PyErr_BadArgument() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 161 | |
| 162 | This is a shorthand for ``PyErr_SetString(PyExc_TypeError, message)``, where |
| 163 | *message* indicates that a built-in operation was invoked with an illegal |
| 164 | argument. It is mostly for internal use. |
| 165 | |
| 166 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 167 | .. c:function:: PyObject* PyErr_NoMemory() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 168 | |
| 169 | This is a shorthand for ``PyErr_SetNone(PyExc_MemoryError)``; it returns *NULL* |
| 170 | so an object allocation function can write ``return PyErr_NoMemory();`` when it |
| 171 | runs out of memory. |
| 172 | |
| 173 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 174 | .. c:function:: PyObject* PyErr_SetFromErrno(PyObject *type) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 175 | |
| 176 | .. index:: single: strerror() |
| 177 | |
| 178 | This is a convenience function to raise an exception when a C library function |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 179 | has returned an error and set the C variable :c:data:`errno`. It constructs a |
| 180 | tuple object whose first item is the integer :c:data:`errno` value and whose |
| 181 | second item is the corresponding error message (gotten from :c:func:`strerror`), |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 182 | and then calls ``PyErr_SetObject(type, object)``. On Unix, when the |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 183 | :c:data:`errno` value is :const:`EINTR`, indicating an interrupted system call, |
| 184 | this calls :c:func:`PyErr_CheckSignals`, and if that set the error indicator, |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 185 | leaves it set to that. The function always returns *NULL*, so a wrapper |
| 186 | function around a system call can write ``return PyErr_SetFromErrno(type);`` |
| 187 | when the system call returns an error. |
| 188 | |
| 189 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 190 | .. c:function:: PyObject* PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 191 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 192 | Similar to :c:func:`PyErr_SetFromErrno`, with the additional behavior that if |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 193 | *filename* is not *NULL*, it is passed to the constructor of *type* as a third |
| 194 | parameter. In the case of exceptions such as :exc:`IOError` and :exc:`OSError`, |
| 195 | this is used to define the :attr:`filename` attribute of the exception instance. |
Victor Stinner | 257d38f | 2010-10-09 10:12:11 +0000 | [diff] [blame] | 196 | *filename* is decoded from the filesystem encoding |
| 197 | (:func:`sys.getfilesystemencoding`). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 198 | |
| 199 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 200 | .. c:function:: PyObject* PyErr_SetFromWindowsErr(int ierr) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 201 | |
| 202 | This is a convenience function to raise :exc:`WindowsError`. If called with |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 203 | *ierr* of :c:data:`0`, the error code returned by a call to :c:func:`GetLastError` |
| 204 | is used instead. It calls the Win32 function :c:func:`FormatMessage` to retrieve |
| 205 | the Windows description of error code given by *ierr* or :c:func:`GetLastError`, |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 206 | then it constructs a tuple object whose first item is the *ierr* value and whose |
| 207 | second item is the corresponding error message (gotten from |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 208 | :c:func:`FormatMessage`), and then calls ``PyErr_SetObject(PyExc_WindowsError, |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 209 | object)``. This function always returns *NULL*. Availability: Windows. |
| 210 | |
| 211 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 212 | .. c:function:: PyObject* PyErr_SetExcFromWindowsErr(PyObject *type, int ierr) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 213 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 214 | Similar to :c:func:`PyErr_SetFromWindowsErr`, with an additional parameter |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 215 | specifying the exception type to be raised. Availability: Windows. |
| 216 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 217 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 218 | .. c:function:: PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 219 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 220 | Similar to :c:func:`PyErr_SetFromWindowsErr`, with the additional behavior that |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 221 | if *filename* is not *NULL*, it is passed to the constructor of |
Victor Stinner | 92be939 | 2010-12-28 00:28:21 +0000 | [diff] [blame] | 222 | :exc:`WindowsError` as a third parameter. *filename* is decoded from the |
| 223 | filesystem encoding (:func:`sys.getfilesystemencoding`). Availability: |
| 224 | Windows. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 225 | |
| 226 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 227 | .. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, char *filename) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 228 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 229 | Similar to :c:func:`PyErr_SetFromWindowsErrWithFilename`, with an additional |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 230 | parameter specifying the exception type to be raised. Availability: Windows. |
| 231 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 232 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 233 | .. c:function:: void PyErr_SyntaxLocationEx(char *filename, int lineno, int col_offset) |
Benjamin Peterson | 2c53971 | 2010-09-20 22:42:10 +0000 | [diff] [blame] | 234 | |
| 235 | Set file, line, and offset information for the current exception. If the |
| 236 | current exception is not a :exc:`SyntaxError`, then it sets additional |
| 237 | attributes, which make the exception printing subsystem think the exception |
Victor Stinner | 555a24f | 2010-12-27 01:49:26 +0000 | [diff] [blame] | 238 | is a :exc:`SyntaxError`. *filename* is decoded from the filesystem encoding |
| 239 | (:func:`sys.getfilesystemencoding`). |
Benjamin Peterson | 2c53971 | 2010-09-20 22:42:10 +0000 | [diff] [blame] | 240 | |
Benjamin Peterson | b5d23b4 | 2010-09-21 21:29:26 +0000 | [diff] [blame] | 241 | .. versionadded:: 3.2 |
| 242 | |
Benjamin Peterson | 2c53971 | 2010-09-20 22:42:10 +0000 | [diff] [blame] | 243 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 244 | .. c:function:: void PyErr_SyntaxLocation(char *filename, int lineno) |
Benjamin Peterson | 2c53971 | 2010-09-20 22:42:10 +0000 | [diff] [blame] | 245 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 246 | Like :c:func:`PyErr_SyntaxLocationExc`, but the col_offset parameter is |
Benjamin Peterson | 2c53971 | 2010-09-20 22:42:10 +0000 | [diff] [blame] | 247 | omitted. |
| 248 | |
| 249 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 250 | .. c:function:: void PyErr_BadInternalCall() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 251 | |
Benjamin Peterson | 5c6d787 | 2009-02-06 02:40:07 +0000 | [diff] [blame] | 252 | This is a shorthand for ``PyErr_SetString(PyExc_SystemError, message)``, |
| 253 | where *message* indicates that an internal operation (e.g. a Python/C API |
| 254 | function) was invoked with an illegal argument. It is mostly for internal |
| 255 | use. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 256 | |
| 257 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 258 | .. c:function:: int PyErr_WarnEx(PyObject *category, char *message, int stack_level) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 259 | |
| 260 | Issue a warning message. The *category* argument is a warning category (see |
Victor Stinner | 555a24f | 2010-12-27 01:49:26 +0000 | [diff] [blame] | 261 | below) or *NULL*; the *message* argument is an UTF-8 encoded string. *stack_level* is a |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 262 | positive number giving a number of stack frames; the warning will be issued from |
Victor Stinner | 4a2b7a1 | 2010-08-13 14:03:48 +0000 | [diff] [blame] | 263 | the currently executing line of code in that stack frame. A *stack_level* of 1 |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 264 | is the function calling :c:func:`PyErr_WarnEx`, 2 is the function above that, |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 265 | and so forth. |
| 266 | |
| 267 | This function normally prints a warning message to *sys.stderr*; however, it is |
| 268 | also possible that the user has specified that warnings are to be turned into |
| 269 | errors, and in that case this will raise an exception. It is also possible that |
| 270 | the function raises an exception because of a problem with the warning machinery |
| 271 | (the implementation imports the :mod:`warnings` module to do the heavy lifting). |
| 272 | The return value is ``0`` if no exception is raised, or ``-1`` if an exception |
| 273 | is raised. (It is not possible to determine whether a warning message is |
| 274 | actually printed, nor what the reason is for the exception; this is |
| 275 | intentional.) If an exception is raised, the caller should do its normal |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 276 | exception handling (for example, :c:func:`Py_DECREF` owned references and return |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 277 | an error value). |
| 278 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 279 | Warning categories must be subclasses of :c:data:`Warning`; the default warning |
| 280 | category is :c:data:`RuntimeWarning`. The standard Python warning categories are |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 281 | available as global variables whose names are ``PyExc_`` followed by the Python |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 282 | exception name. These have the type :c:type:`PyObject\*`; they are all class |
| 283 | objects. Their names are :c:data:`PyExc_Warning`, :c:data:`PyExc_UserWarning`, |
| 284 | :c:data:`PyExc_UnicodeWarning`, :c:data:`PyExc_DeprecationWarning`, |
| 285 | :c:data:`PyExc_SyntaxWarning`, :c:data:`PyExc_RuntimeWarning`, and |
| 286 | :c:data:`PyExc_FutureWarning`. :c:data:`PyExc_Warning` is a subclass of |
| 287 | :c:data:`PyExc_Exception`; the other warning categories are subclasses of |
| 288 | :c:data:`PyExc_Warning`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 289 | |
| 290 | For information about warning control, see the documentation for the |
| 291 | :mod:`warnings` module and the :option:`-W` option in the command line |
| 292 | documentation. There is no C API for warning control. |
| 293 | |
| 294 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 295 | .. c:function:: int PyErr_WarnExplicit(PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 296 | |
| 297 | Issue a warning message with explicit control over all warning attributes. This |
| 298 | is a straightforward wrapper around the Python function |
| 299 | :func:`warnings.warn_explicit`, see there for more information. The *module* |
| 300 | and *registry* arguments may be set to *NULL* to get the default effect |
Victor Stinner | cb428f0 | 2010-12-27 20:10:36 +0000 | [diff] [blame] | 301 | described there. *message* and *module* are UTF-8 encoded strings, |
| 302 | *filename* is decoded from the filesystem encoding |
| 303 | (:func:`sys.getfilesystemencoding`). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 304 | |
| 305 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 306 | .. c:function:: int PyErr_WarnFormat(PyObject *category, Py_ssize_t stack_level, const char *format, ...) |
Victor Stinner | 4a2b7a1 | 2010-08-13 14:03:48 +0000 | [diff] [blame] | 307 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 308 | Function similar to :c:func:`PyErr_WarnEx`, but use |
Victor Stinner | 555a24f | 2010-12-27 01:49:26 +0000 | [diff] [blame] | 309 | :c:func:`PyUnicode_FromFormat` to format the warning message. *format* is |
| 310 | an ASCII-encoded string. |
Victor Stinner | 4a2b7a1 | 2010-08-13 14:03:48 +0000 | [diff] [blame] | 311 | |
| 312 | .. versionadded:: 3.2 |
| 313 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 314 | .. c:function:: int PyErr_CheckSignals() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 315 | |
| 316 | .. index:: |
| 317 | module: signal |
| 318 | single: SIGINT |
| 319 | single: KeyboardInterrupt (built-in exception) |
| 320 | |
| 321 | This function interacts with Python's signal handling. It checks whether a |
| 322 | signal has been sent to the processes and if so, invokes the corresponding |
| 323 | signal handler. If the :mod:`signal` module is supported, this can invoke a |
| 324 | signal handler written in Python. In all cases, the default effect for |
| 325 | :const:`SIGINT` is to raise the :exc:`KeyboardInterrupt` exception. If an |
| 326 | exception is raised the error indicator is set and the function returns ``-1``; |
| 327 | otherwise the function returns ``0``. The error indicator may or may not be |
| 328 | cleared if it was previously set. |
| 329 | |
| 330 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 331 | .. c:function:: void PyErr_SetInterrupt() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 332 | |
| 333 | .. index:: |
| 334 | single: SIGINT |
| 335 | single: KeyboardInterrupt (built-in exception) |
| 336 | |
| 337 | This function simulates the effect of a :const:`SIGINT` signal arriving --- the |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 338 | next time :c:func:`PyErr_CheckSignals` is called, :exc:`KeyboardInterrupt` will |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 339 | be raised. It may be called without holding the interpreter lock. |
| 340 | |
| 341 | .. % XXX This was described as obsolete, but is used in |
Georg Brandl | 2067bfd | 2008-05-25 13:05:15 +0000 | [diff] [blame] | 342 | .. % _thread.interrupt_main() (used from IDLE), so it's still needed. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 343 | |
| 344 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 345 | .. c:function:: int PySignal_SetWakeupFd(int fd) |
Christian Heimes | 5fb7c2a | 2007-12-24 08:52:31 +0000 | [diff] [blame] | 346 | |
| 347 | This utility function specifies a file descriptor to which a ``'\0'`` byte will |
| 348 | be written whenever a signal is received. It returns the previous such file |
| 349 | descriptor. The value ``-1`` disables the feature; this is the initial state. |
| 350 | This is equivalent to :func:`signal.set_wakeup_fd` in Python, but without any |
| 351 | error checking. *fd* should be a valid file descriptor. The function should |
| 352 | only be called from the main thread. |
| 353 | |
| 354 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 355 | .. c:function:: PyObject* PyErr_NewException(char *name, PyObject *base, PyObject *dict) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 356 | |
| 357 | This utility function creates and returns a new exception object. The *name* |
| 358 | argument must be the name of the new exception, a C string of the form |
| 359 | ``module.class``. The *base* and *dict* arguments are normally *NULL*. This |
| 360 | creates a class object derived from :exc:`Exception` (accessible in C as |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 361 | :c:data:`PyExc_Exception`). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 362 | |
| 363 | The :attr:`__module__` attribute of the new class is set to the first part (up |
| 364 | to the last dot) of the *name* argument, and the class name is set to the last |
| 365 | part (after the last dot). The *base* argument can be used to specify alternate |
| 366 | base classes; it can either be only one class or a tuple of classes. The *dict* |
| 367 | argument can be used to specify a dictionary of class variables and methods. |
| 368 | |
| 369 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 370 | .. c:function:: PyObject* PyErr_NewExceptionWithDoc(char *name, char *doc, PyObject *base, PyObject *dict) |
Georg Brandl | 1e28a27 | 2009-12-28 08:41:01 +0000 | [diff] [blame] | 371 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 372 | Same as :c:func:`PyErr_NewException`, except that the new exception class can |
Georg Brandl | 1e28a27 | 2009-12-28 08:41:01 +0000 | [diff] [blame] | 373 | easily be given a docstring: If *doc* is non-*NULL*, it will be used as the |
| 374 | docstring for the exception class. |
| 375 | |
| 376 | .. versionadded:: 3.2 |
| 377 | |
| 378 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 379 | .. c:function:: void PyErr_WriteUnraisable(PyObject *obj) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 380 | |
| 381 | This utility function prints a warning message to ``sys.stderr`` when an |
| 382 | exception has been set but it is impossible for the interpreter to actually |
| 383 | raise the exception. It is used, for example, when an exception occurs in an |
| 384 | :meth:`__del__` method. |
| 385 | |
| 386 | The function is called with a single argument *obj* that identifies the context |
| 387 | in which the unraisable exception occurred. The repr of *obj* will be printed in |
| 388 | the warning message. |
| 389 | |
| 390 | |
Georg Brandl | ab6f2f6 | 2009-03-31 04:16:10 +0000 | [diff] [blame] | 391 | Exception Objects |
| 392 | ================= |
| 393 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 394 | .. c:function:: PyObject* PyException_GetTraceback(PyObject *ex) |
Georg Brandl | ab6f2f6 | 2009-03-31 04:16:10 +0000 | [diff] [blame] | 395 | |
| 396 | Return the traceback associated with the exception as a new reference, as |
| 397 | accessible from Python through :attr:`__traceback__`. If there is no |
| 398 | traceback associated, this returns *NULL*. |
| 399 | |
| 400 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 401 | .. c:function:: int PyException_SetTraceback(PyObject *ex, PyObject *tb) |
Georg Brandl | ab6f2f6 | 2009-03-31 04:16:10 +0000 | [diff] [blame] | 402 | |
| 403 | Set the traceback associated with the exception to *tb*. Use ``Py_None`` to |
| 404 | clear it. |
| 405 | |
| 406 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 407 | .. c:function:: PyObject* PyException_GetContext(PyObject *ex) |
Georg Brandl | ab6f2f6 | 2009-03-31 04:16:10 +0000 | [diff] [blame] | 408 | |
| 409 | Return the context (another exception instance during whose handling *ex* was |
| 410 | raised) associated with the exception as a new reference, as accessible from |
| 411 | Python through :attr:`__context__`. If there is no context associated, this |
| 412 | returns *NULL*. |
| 413 | |
| 414 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 415 | .. c:function:: void PyException_SetContext(PyObject *ex, PyObject *ctx) |
Georg Brandl | ab6f2f6 | 2009-03-31 04:16:10 +0000 | [diff] [blame] | 416 | |
| 417 | Set the context associated with the exception to *ctx*. Use *NULL* to clear |
| 418 | it. There is no type check to make sure that *ctx* is an exception instance. |
| 419 | This steals a reference to *ctx*. |
| 420 | |
| 421 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 422 | .. c:function:: PyObject* PyException_GetCause(PyObject *ex) |
Georg Brandl | ab6f2f6 | 2009-03-31 04:16:10 +0000 | [diff] [blame] | 423 | |
| 424 | Return the cause (another exception instance set by ``raise ... from ...``) |
| 425 | associated with the exception as a new reference, as accessible from Python |
| 426 | through :attr:`__cause__`. If there is no cause associated, this returns |
| 427 | *NULL*. |
| 428 | |
| 429 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 430 | .. c:function:: void PyException_SetCause(PyObject *ex, PyObject *ctx) |
Georg Brandl | ab6f2f6 | 2009-03-31 04:16:10 +0000 | [diff] [blame] | 431 | |
| 432 | Set the cause associated with the exception to *ctx*. Use *NULL* to clear |
| 433 | it. There is no type check to make sure that *ctx* is an exception instance. |
| 434 | This steals a reference to *ctx*. |
| 435 | |
| 436 | |
Georg Brandl | 5a93265 | 2010-11-23 07:54:19 +0000 | [diff] [blame] | 437 | .. _unicodeexceptions: |
| 438 | |
| 439 | Unicode Exception Objects |
| 440 | ========================= |
| 441 | |
| 442 | The following functions are used to create and modify Unicode exceptions from C. |
| 443 | |
| 444 | .. c:function:: PyObject* PyUnicodeDecodeError_Create(const char *encoding, const char *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason) |
| 445 | |
| 446 | Create a :class:`UnicodeDecodeError` object with the attributes *encoding*, |
Victor Stinner | 555a24f | 2010-12-27 01:49:26 +0000 | [diff] [blame] | 447 | *object*, *length*, *start*, *end* and *reason*. *encoding* and *reason* are |
| 448 | UTF-8 encoded strings. |
Georg Brandl | 5a93265 | 2010-11-23 07:54:19 +0000 | [diff] [blame] | 449 | |
| 450 | .. c:function:: 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) |
| 451 | |
| 452 | Create a :class:`UnicodeEncodeError` object with the attributes *encoding*, |
Victor Stinner | 555a24f | 2010-12-27 01:49:26 +0000 | [diff] [blame] | 453 | *object*, *length*, *start*, *end* and *reason*. *encoding* and *reason* are |
| 454 | UTF-8 encoded strings. |
Georg Brandl | 5a93265 | 2010-11-23 07:54:19 +0000 | [diff] [blame] | 455 | |
| 456 | .. c:function:: PyObject* PyUnicodeTranslateError_Create(const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason) |
| 457 | |
| 458 | Create a :class:`UnicodeTranslateError` object with the attributes *object*, |
Victor Stinner | 555a24f | 2010-12-27 01:49:26 +0000 | [diff] [blame] | 459 | *length*, *start*, *end* and *reason*. *reason* is an UTF-8 encoded string. |
Georg Brandl | 5a93265 | 2010-11-23 07:54:19 +0000 | [diff] [blame] | 460 | |
| 461 | .. c:function:: PyObject* PyUnicodeDecodeError_GetEncoding(PyObject *exc) |
| 462 | PyObject* PyUnicodeEncodeError_GetEncoding(PyObject *exc) |
| 463 | |
| 464 | Return the *encoding* attribute of the given exception object. |
| 465 | |
| 466 | .. c:function:: PyObject* PyUnicodeDecodeError_GetObject(PyObject *exc) |
| 467 | PyObject* PyUnicodeEncodeError_GetObject(PyObject *exc) |
| 468 | PyObject* PyUnicodeTranslateError_GetObject(PyObject *exc) |
| 469 | |
| 470 | Return the *object* attribute of the given exception object. |
| 471 | |
| 472 | .. c:function:: int PyUnicodeDecodeError_GetStart(PyObject *exc, Py_ssize_t *start) |
| 473 | int PyUnicodeEncodeError_GetStart(PyObject *exc, Py_ssize_t *start) |
| 474 | int PyUnicodeTranslateError_GetStart(PyObject *exc, Py_ssize_t *start) |
| 475 | |
| 476 | Get the *start* attribute of the given exception object and place it into |
| 477 | *\*start*. *start* must not be *NULL*. Return ``0`` on success, ``-1`` on |
| 478 | failure. |
| 479 | |
| 480 | .. c:function:: int PyUnicodeDecodeError_SetStart(PyObject *exc, Py_ssize_t start) |
| 481 | int PyUnicodeEncodeError_SetStart(PyObject *exc, Py_ssize_t start) |
| 482 | int PyUnicodeTranslateError_SetStart(PyObject *exc, Py_ssize_t start) |
| 483 | |
| 484 | Set the *start* attribute of the given exception object to *start*. Return |
| 485 | ``0`` on success, ``-1`` on failure. |
| 486 | |
| 487 | .. c:function:: int PyUnicodeDecodeError_GetEnd(PyObject *exc, Py_ssize_t *end) |
| 488 | int PyUnicodeEncodeError_GetEnd(PyObject *exc, Py_ssize_t *end) |
| 489 | int PyUnicodeTranslateError_GetEnd(PyObject *exc, Py_ssize_t *end) |
| 490 | |
| 491 | Get the *end* attribute of the given exception object and place it into |
| 492 | *\*end*. *end* must not be *NULL*. Return ``0`` on success, ``-1`` on |
| 493 | failure. |
| 494 | |
| 495 | .. c:function:: int PyUnicodeDecodeError_SetEnd(PyObject *exc, Py_ssize_t end) |
| 496 | int PyUnicodeEncodeError_SetEnd(PyObject *exc, Py_ssize_t end) |
| 497 | int PyUnicodeTranslateError_SetEnd(PyObject *exc, Py_ssize_t end) |
| 498 | |
| 499 | Set the *end* attribute of the given exception object to *end*. Return ``0`` |
| 500 | on success, ``-1`` on failure. |
| 501 | |
| 502 | .. c:function:: PyObject* PyUnicodeDecodeError_GetReason(PyObject *exc) |
| 503 | PyObject* PyUnicodeEncodeError_GetReason(PyObject *exc) |
| 504 | PyObject* PyUnicodeTranslateError_GetReason(PyObject *exc) |
| 505 | |
| 506 | Return the *reason* attribute of the given exception object. |
| 507 | |
| 508 | .. c:function:: int PyUnicodeDecodeError_SetReason(PyObject *exc, const char *reason) |
| 509 | int PyUnicodeEncodeError_SetReason(PyObject *exc, const char *reason) |
| 510 | int PyUnicodeTranslateError_SetReason(PyObject *exc, const char *reason) |
| 511 | |
| 512 | Set the *reason* attribute of the given exception object to *reason*. Return |
| 513 | ``0`` on success, ``-1`` on failure. |
| 514 | |
| 515 | |
Georg Brandl | 93dc9eb | 2010-03-14 10:56:14 +0000 | [diff] [blame] | 516 | Recursion Control |
| 517 | ================= |
| 518 | |
| 519 | These two functions provide a way to perform safe recursive calls at the C |
| 520 | level, both in the core and in extension modules. They are needed if the |
| 521 | recursive code does not necessarily invoke Python code (which tracks its |
| 522 | recursion depth automatically). |
| 523 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 524 | .. c:function:: int Py_EnterRecursiveCall(char *where) |
Georg Brandl | 93dc9eb | 2010-03-14 10:56:14 +0000 | [diff] [blame] | 525 | |
| 526 | Marks a point where a recursive C-level call is about to be performed. |
| 527 | |
| 528 | If :const:`USE_STACKCHECK` is defined, this function checks if the the OS |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 529 | stack overflowed using :c:func:`PyOS_CheckStack`. In this is the case, it |
Georg Brandl | 93dc9eb | 2010-03-14 10:56:14 +0000 | [diff] [blame] | 530 | sets a :exc:`MemoryError` and returns a nonzero value. |
| 531 | |
| 532 | The function then checks if the recursion limit is reached. If this is the |
| 533 | case, a :exc:`RuntimeError` is set and a nonzero value is returned. |
| 534 | Otherwise, zero is returned. |
| 535 | |
| 536 | *where* should be a string such as ``" in instance check"`` to be |
| 537 | concatenated to the :exc:`RuntimeError` message caused by the recursion depth |
| 538 | limit. |
| 539 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 540 | .. c:function:: void Py_LeaveRecursiveCall() |
Georg Brandl | 93dc9eb | 2010-03-14 10:56:14 +0000 | [diff] [blame] | 541 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 542 | Ends a :c:func:`Py_EnterRecursiveCall`. Must be called once for each |
| 543 | *successful* invocation of :c:func:`Py_EnterRecursiveCall`. |
Georg Brandl | 93dc9eb | 2010-03-14 10:56:14 +0000 | [diff] [blame] | 544 | |
Daniel Stutzbach | 7cb3051 | 2010-12-17 16:31:32 +0000 | [diff] [blame] | 545 | Properly implementing :attr:`tp_repr` for container types requires |
| 546 | special recursion handling. In addition to protecting the stack, |
| 547 | :attr:`tp_repr` also needs to track objects to prevent cycles. The |
| 548 | following two functions facilitate this functionality. Effectively, |
| 549 | these are the C equivalent to :func:`reprlib.recursive_repr`. |
| 550 | |
Daniel Stutzbach | c5895dc | 2010-12-17 22:28:07 +0000 | [diff] [blame] | 551 | .. c:function:: int Py_ReprEnter(PyObject *object) |
Daniel Stutzbach | 7cb3051 | 2010-12-17 16:31:32 +0000 | [diff] [blame] | 552 | |
| 553 | Called at the beginning of the :attr:`tp_repr` implementation to |
| 554 | detect cycles. |
| 555 | |
| 556 | If the object has already been processed, the function returns a |
| 557 | positive integer. In that case the :attr:`tp_repr` implementation |
| 558 | should return a string object indicating a cycle. As examples, |
| 559 | :class:`dict` objects return ``{...}`` and :class:`list` objects |
| 560 | return ``[...]``. |
| 561 | |
| 562 | The function will return a negative integer if the recursion limit |
| 563 | is reached. In that case the :attr:`tp_repr` implementation should |
| 564 | typically return ``NULL``. |
| 565 | |
| 566 | Otherwise, the function returns zero and the :attr:`tp_repr` |
| 567 | implementation can continue normally. |
| 568 | |
| 569 | .. c:function:: void Py_ReprLeave(PyObject *object) |
| 570 | |
Daniel Stutzbach | c5895dc | 2010-12-17 22:28:07 +0000 | [diff] [blame] | 571 | Ends a :c:func:`Py_ReprEnter`. Must be called once for each |
| 572 | invocation of :c:func:`Py_ReprEnter` that returns zero. |
Daniel Stutzbach | 7cb3051 | 2010-12-17 16:31:32 +0000 | [diff] [blame] | 573 | |
Georg Brandl | 93dc9eb | 2010-03-14 10:56:14 +0000 | [diff] [blame] | 574 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 575 | .. _standardexceptions: |
| 576 | |
| 577 | Standard Exceptions |
| 578 | =================== |
| 579 | |
| 580 | All standard Python exceptions are available as global variables whose names are |
| 581 | ``PyExc_`` followed by the Python exception name. These have the type |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 582 | :c:type:`PyObject\*`; they are all class objects. For completeness, here are all |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 583 | the variables: |
| 584 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 585 | +-------------------------------------+----------------------------+----------+ |
| 586 | | C Name | Python Name | Notes | |
| 587 | +=====================================+============================+==========+ |
| 588 | | :c:data:`PyExc_BaseException` | :exc:`BaseException` | \(1) | |
| 589 | +-------------------------------------+----------------------------+----------+ |
| 590 | | :c:data:`PyExc_Exception` | :exc:`Exception` | \(1) | |
| 591 | +-------------------------------------+----------------------------+----------+ |
| 592 | | :c:data:`PyExc_ArithmeticError` | :exc:`ArithmeticError` | \(1) | |
| 593 | +-------------------------------------+----------------------------+----------+ |
| 594 | | :c:data:`PyExc_LookupError` | :exc:`LookupError` | \(1) | |
| 595 | +-------------------------------------+----------------------------+----------+ |
| 596 | | :c:data:`PyExc_AssertionError` | :exc:`AssertionError` | | |
| 597 | +-------------------------------------+----------------------------+----------+ |
| 598 | | :c:data:`PyExc_AttributeError` | :exc:`AttributeError` | | |
| 599 | +-------------------------------------+----------------------------+----------+ |
| 600 | | :c:data:`PyExc_EOFError` | :exc:`EOFError` | | |
| 601 | +-------------------------------------+----------------------------+----------+ |
| 602 | | :c:data:`PyExc_EnvironmentError` | :exc:`EnvironmentError` | \(1) | |
| 603 | +-------------------------------------+----------------------------+----------+ |
| 604 | | :c:data:`PyExc_FloatingPointError` | :exc:`FloatingPointError` | | |
| 605 | +-------------------------------------+----------------------------+----------+ |
| 606 | | :c:data:`PyExc_IOError` | :exc:`IOError` | | |
| 607 | +-------------------------------------+----------------------------+----------+ |
| 608 | | :c:data:`PyExc_ImportError` | :exc:`ImportError` | | |
| 609 | +-------------------------------------+----------------------------+----------+ |
| 610 | | :c:data:`PyExc_IndexError` | :exc:`IndexError` | | |
| 611 | +-------------------------------------+----------------------------+----------+ |
| 612 | | :c:data:`PyExc_KeyError` | :exc:`KeyError` | | |
| 613 | +-------------------------------------+----------------------------+----------+ |
| 614 | | :c:data:`PyExc_KeyboardInterrupt` | :exc:`KeyboardInterrupt` | | |
| 615 | +-------------------------------------+----------------------------+----------+ |
| 616 | | :c:data:`PyExc_MemoryError` | :exc:`MemoryError` | | |
| 617 | +-------------------------------------+----------------------------+----------+ |
| 618 | | :c:data:`PyExc_NameError` | :exc:`NameError` | | |
| 619 | +-------------------------------------+----------------------------+----------+ |
| 620 | | :c:data:`PyExc_NotImplementedError` | :exc:`NotImplementedError` | | |
| 621 | +-------------------------------------+----------------------------+----------+ |
| 622 | | :c:data:`PyExc_OSError` | :exc:`OSError` | | |
| 623 | +-------------------------------------+----------------------------+----------+ |
| 624 | | :c:data:`PyExc_OverflowError` | :exc:`OverflowError` | | |
| 625 | +-------------------------------------+----------------------------+----------+ |
| 626 | | :c:data:`PyExc_ReferenceError` | :exc:`ReferenceError` | \(2) | |
| 627 | +-------------------------------------+----------------------------+----------+ |
| 628 | | :c:data:`PyExc_RuntimeError` | :exc:`RuntimeError` | | |
| 629 | +-------------------------------------+----------------------------+----------+ |
| 630 | | :c:data:`PyExc_SyntaxError` | :exc:`SyntaxError` | | |
| 631 | +-------------------------------------+----------------------------+----------+ |
| 632 | | :c:data:`PyExc_SystemError` | :exc:`SystemError` | | |
| 633 | +-------------------------------------+----------------------------+----------+ |
| 634 | | :c:data:`PyExc_SystemExit` | :exc:`SystemExit` | | |
| 635 | +-------------------------------------+----------------------------+----------+ |
| 636 | | :c:data:`PyExc_TypeError` | :exc:`TypeError` | | |
| 637 | +-------------------------------------+----------------------------+----------+ |
| 638 | | :c:data:`PyExc_ValueError` | :exc:`ValueError` | | |
| 639 | +-------------------------------------+----------------------------+----------+ |
| 640 | | :c:data:`PyExc_WindowsError` | :exc:`WindowsError` | \(3) | |
| 641 | +-------------------------------------+----------------------------+----------+ |
| 642 | | :c:data:`PyExc_ZeroDivisionError` | :exc:`ZeroDivisionError` | | |
| 643 | +-------------------------------------+----------------------------+----------+ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 644 | |
| 645 | .. index:: |
| 646 | single: PyExc_BaseException |
| 647 | single: PyExc_Exception |
| 648 | single: PyExc_ArithmeticError |
| 649 | single: PyExc_LookupError |
| 650 | single: PyExc_AssertionError |
| 651 | single: PyExc_AttributeError |
| 652 | single: PyExc_EOFError |
| 653 | single: PyExc_EnvironmentError |
| 654 | single: PyExc_FloatingPointError |
| 655 | single: PyExc_IOError |
| 656 | single: PyExc_ImportError |
| 657 | single: PyExc_IndexError |
| 658 | single: PyExc_KeyError |
| 659 | single: PyExc_KeyboardInterrupt |
| 660 | single: PyExc_MemoryError |
| 661 | single: PyExc_NameError |
| 662 | single: PyExc_NotImplementedError |
| 663 | single: PyExc_OSError |
| 664 | single: PyExc_OverflowError |
| 665 | single: PyExc_ReferenceError |
| 666 | single: PyExc_RuntimeError |
| 667 | single: PyExc_SyntaxError |
| 668 | single: PyExc_SystemError |
| 669 | single: PyExc_SystemExit |
| 670 | single: PyExc_TypeError |
| 671 | single: PyExc_ValueError |
| 672 | single: PyExc_WindowsError |
| 673 | single: PyExc_ZeroDivisionError |
| 674 | |
| 675 | Notes: |
| 676 | |
| 677 | (1) |
| 678 | This is a base class for other standard exceptions. |
| 679 | |
| 680 | (2) |
| 681 | This is the same as :exc:`weakref.ReferenceError`. |
| 682 | |
| 683 | (3) |
| 684 | Only defined on Windows; protect code that uses this by testing that the |
| 685 | preprocessor macro ``MS_WINDOWS`` is defined. |