| 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| 2 | <html> |
| 3 | <head> |
| 4 | <link rel="STYLESHEET" href="api.css" type='text/css' /> |
| 5 | <link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" /> |
| 6 | <link rel='start' href='../index.html' title='Python Documentation Index' /> |
| 7 | <link rel="first" href="api.html" title='Python/C API Reference Manual' /> |
| 8 | <link rel='contents' href='contents.html' title="Contents" /> |
| 9 | <link rel='index' href='genindex.html' title='Index' /> |
| 10 | <link rel='last' href='about.html' title='About this document...' /> |
| 11 | <link rel='help' href='about.html' title='About this document...' /> |
| 12 | <link rel="next" href="utilities.html" /> |
| 13 | <link rel="prev" href="countingRefs.html" /> |
| 14 | <link rel="parent" href="api.html" /> |
| 15 | <link rel="next" href="standardExceptions.html" /> |
| 16 | <meta name='aesop' content='information' /> |
| 17 | <title>4. Exception Handling </title> |
| 18 | </head> |
| 19 | <body> |
| 20 | <DIV CLASS="navigation"> |
| 21 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> |
| 22 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 23 | <tr> |
| 24 | <td class='online-navigation'><a rel="prev" title="3. Reference Counting" |
| 25 | href="countingRefs.html"><img src='../icons/previous.png' |
| 26 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 27 | <td class='online-navigation'><a rel="parent" title="Python/C API Reference Manual" |
| 28 | href="api.html"><img src='../icons/up.png' |
| 29 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 30 | <td class='online-navigation'><a rel="next" title="4.1 Standard Exceptions" |
| 31 | href="standardExceptions.html"><img src='../icons/next.png' |
| 32 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 33 | <td align="center" width="100%">Python/C API Reference Manual</td> |
| 34 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 35 | href="contents.html"><img src='../icons/contents.png' |
| 36 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 37 | <td class='online-navigation'><img src='../icons/blank.png' |
| 38 | border='0' height='32' alt='' width='32' /></td> |
| 39 | <td class='online-navigation'><a rel="index" title="Index" |
| 40 | href="genindex.html"><img src='../icons/index.png' |
| 41 | border='0' height='32' alt='Index' width='32' /></A></td> |
| 42 | </tr></table> |
| 43 | <div class='online-navigation'> |
| 44 | <b class="navlabel">Previous:</b> |
| 45 | <a class="sectref" rel="prev" href="countingRefs.html">3. Reference Counting</A> |
| 46 | <b class="navlabel">Up:</b> |
| 47 | <a class="sectref" rel="parent" href="api.html">Python/C API Reference Manual</A> |
| 48 | <b class="navlabel">Next:</b> |
| 49 | <a class="sectref" rel="next" href="standardExceptions.html">4.1 Standard Exceptions</A> |
| 50 | </div> |
| 51 | <hr /></div> |
| 52 | </DIV> |
| 53 | <!--End of Navigation Panel--> |
| 54 | |
| 55 | <H1><A NAME="SECTION006000000000000000000"></A><A NAME="exceptionHandling"></A> |
| 56 | <BR> |
| 57 | 4. Exception Handling |
| 58 | </H1> |
| 59 | |
| 60 | <P> |
| 61 | The functions described in this chapter will let you handle and raise Python |
| 62 | exceptions. It is important to understand some of the basics of |
| 63 | Python exception handling. It works somewhat like the |
| 64 | <span class="Unix">Unix</span> <tt class="cdata">errno</tt> variable: there is a global indicator (per |
| 65 | thread) of the last error that occurred. Most functions don't clear |
| 66 | this on success, but will set it to indicate the cause of the error on |
| 67 | failure. Most functions also return an error indicator, usually |
| 68 | <tt class="constant">NULL</tt> if they are supposed to return a pointer, or <code>-1</code> if they |
| 69 | return an integer (exception: the <tt class="cfunction">PyArg_*()</tt> functions |
| 70 | return <code>1</code> for success and <code>0</code> for failure). |
| 71 | |
| 72 | <P> |
| 73 | When a function must fail because some function it called failed, it |
| 74 | generally doesn't set the error indicator; the function it called |
| 75 | already set it. It is responsible for either handling the error and |
| 76 | clearing the exception or returning after cleaning up any resources it |
| 77 | holds (such as object references or memory allocations); it should |
| 78 | <em>not</em> continue normally if it is not prepared to handle the |
| 79 | error. If returning due to an error, it is important to indicate to |
| 80 | the caller that an error has been set. If the error is not handled or |
| 81 | carefully propagated, additional calls into the Python/C API may not |
| 82 | behave as intended and may fail in mysterious ways. |
| 83 | |
| 84 | <P> |
| 85 | The error indicator consists of three Python objects corresponding to |
| 86 | <a id='l2h-90' xml:id='l2h-90'></a>the Python variables <code>sys.exc_type</code>, <code>sys.exc_value</code> and |
| 87 | <code>sys.exc_traceback</code>. API functions exist to interact with the |
| 88 | error indicator in various ways. There is a separate error indicator |
| 89 | for each thread. |
| 90 | |
| 91 | <P> |
| 92 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void <b><tt id='l2h-91' xml:id='l2h-91' class="cfunction">PyErr_Print</tt></b>(</nobr></td><td>)</td></tr></table></dt> |
| 93 | <dd> |
| 94 | Print a standard traceback to <code>sys.stderr</code> and clear the error |
| 95 | indicator. Call this function only when the error indicator is |
| 96 | set. (Otherwise it will cause a fatal error!) |
| 97 | </dd></dl> |
| 98 | |
| 99 | <P> |
| 100 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-92' xml:id='l2h-92' class="cfunction">PyErr_Occurred</tt></b>(</nobr></td><td>)</td></tr></table></dt> |
| 101 | <dd> |
| 102 | <div class="refcount-info"> |
| 103 | <span class="label">Return value:</span> |
| 104 | <span class="value">Borrowed reference.</span> |
| 105 | </div> |
| 106 | Test whether the error indicator is set. If set, return the |
| 107 | exception <em>type</em> (the first argument to the last call to one of |
| 108 | the <tt class="cfunction">PyErr_Set*()</tt> functions or to |
| 109 | <tt class="cfunction">PyErr_Restore()</tt>). If not set, return <tt class="constant">NULL</tt>. You do |
| 110 | not own a reference to the return value, so you do not need to |
| 111 | <tt class="cfunction">Py_DECREF()</tt> it. <span class="note"><b class="label">Note:</b> |
| 112 | Do not compare the return value |
| 113 | to a specific exception; use <tt class="cfunction">PyErr_ExceptionMatches()</tt> |
| 114 | instead, shown below. (The comparison could easily fail since the |
| 115 | exception may be an instance instead of a class, in the case of a |
| 116 | class exception, or it may the a subclass of the expected |
| 117 | exception.)</span> |
| 118 | </dd></dl> |
| 119 | |
| 120 | <P> |
| 121 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-93' xml:id='l2h-93' class="cfunction">PyErr_ExceptionMatches</tt></b>(</nobr></td><td>PyObject *<var>exc</var>)</td></tr></table></dt> |
| 122 | <dd> |
| 123 | Equivalent to "<tt class="samp">PyErr_GivenExceptionMatches(PyErr_Occurred(), |
| 124 | <var>exc</var>)</tt>". This should only be called when an exception is |
| 125 | actually set; a memory access violation will occur if no exception |
| 126 | has been raised. |
| 127 | </dd></dl> |
| 128 | |
| 129 | <P> |
| 130 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-94' xml:id='l2h-94' class="cfunction">PyErr_GivenExceptionMatches</tt></b>(</nobr></td><td>PyObject *<var>given</var>, PyObject *<var>exc</var>)</td></tr></table></dt> |
| 131 | <dd> |
| 132 | Return true if the <var>given</var> exception matches the exception in |
| 133 | <var>exc</var>. If <var>exc</var> is a class object, this also returns true |
| 134 | when <var>given</var> is an instance of a subclass. If <var>exc</var> is a |
| 135 | tuple, all exceptions in the tuple (and recursively in subtuples) |
| 136 | are searched for a match. If <var>given</var> is <tt class="constant">NULL</tt>, a memory access |
| 137 | violation will occur. |
| 138 | </dd></dl> |
| 139 | |
| 140 | <P> |
| 141 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void <b><tt id='l2h-95' xml:id='l2h-95' class="cfunction">PyErr_NormalizeException</tt></b>(</nobr></td><td>PyObject**<var>exc</var>, PyObject**<var>val</var>, PyObject**<var>tb</var>)</td></tr></table></dt> |
| 142 | <dd> |
| 143 | Under certain circumstances, the values returned by |
| 144 | <tt class="cfunction">PyErr_Fetch()</tt> below can be ``unnormalized'', meaning |
| 145 | that <code>*<var>exc</var></code> is a class object but <code>*<var>val</var></code> is |
| 146 | not an instance of the same class. This function can be used to |
| 147 | instantiate the class in that case. If the values are already |
| 148 | normalized, nothing happens. The delayed normalization is |
| 149 | implemented to improve performance. |
| 150 | </dd></dl> |
| 151 | |
| 152 | <P> |
| 153 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void <b><tt id='l2h-96' xml:id='l2h-96' class="cfunction">PyErr_Clear</tt></b>(</nobr></td><td>)</td></tr></table></dt> |
| 154 | <dd> |
| 155 | Clear the error indicator. If the error indicator is not set, there |
| 156 | is no effect. |
| 157 | </dd></dl> |
| 158 | |
| 159 | <P> |
| 160 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void <b><tt id='l2h-97' xml:id='l2h-97' class="cfunction">PyErr_Fetch</tt></b>(</nobr></td><td>PyObject **<var>ptype</var>, PyObject **<var>pvalue</var>, |
| 161 | PyObject **<var>ptraceback</var>)</td></tr></table></dt> |
| 162 | <dd> |
| 163 | Retrieve the error indicator into three variables whose addresses |
| 164 | are passed. If the error indicator is not set, set all three |
| 165 | variables to <tt class="constant">NULL</tt>. If it is set, it will be cleared and you own a |
| 166 | reference to each object retrieved. The value and traceback object |
| 167 | may be <tt class="constant">NULL</tt> even when the type object is not. <span class="note"><b class="label">Note:</b> |
| 168 | This |
| 169 | function is normally only used by code that needs to handle |
| 170 | exceptions or by code that needs to save and restore the error |
| 171 | indicator temporarily.</span> |
| 172 | </dd></dl> |
| 173 | |
| 174 | <P> |
| 175 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void <b><tt id='l2h-98' xml:id='l2h-98' class="cfunction">PyErr_Restore</tt></b>(</nobr></td><td>PyObject *<var>type</var>, PyObject *<var>value</var>, |
| 176 | PyObject *<var>traceback</var>)</td></tr></table></dt> |
| 177 | <dd> |
| 178 | Set the error indicator from the three objects. If the error |
| 179 | indicator is already set, it is cleared first. If the objects are |
| 180 | <tt class="constant">NULL</tt>, the error indicator is cleared. Do not pass a <tt class="constant">NULL</tt> type |
| 181 | and non-<tt class="constant">NULL</tt> value or traceback. The exception type should be a |
| 182 | class. Do not pass an invalid exception type or value. |
| 183 | (Violating these rules will cause subtle problems later.) This call |
| 184 | takes away a reference to each object: you must own a reference to |
| 185 | each object before the call and after the call you no longer own |
| 186 | these references. (If you don't understand this, don't use this |
| 187 | function. I warned you.) <span class="note"><b class="label">Note:</b> |
| 188 | This function is normally only used |
| 189 | by code that needs to save and restore the error indicator |
| 190 | temporarily; use <tt class="cfunction">PyErr_Fetch()</tt> to save the current |
| 191 | exception state.</span> |
| 192 | </dd></dl> |
| 193 | |
| 194 | <P> |
| 195 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void <b><tt id='l2h-99' xml:id='l2h-99' class="cfunction">PyErr_SetString</tt></b>(</nobr></td><td>PyObject *<var>type</var>, char *<var>message</var>)</td></tr></table></dt> |
| 196 | <dd> |
| 197 | This is the most common way to set the error indicator. The first |
| 198 | argument specifies the exception type; it is normally one of the |
| 199 | standard exceptions, e.g. <tt class="cdata">PyExc_RuntimeError</tt>. You need not |
| 200 | increment its reference count. The second argument is an error |
| 201 | message; it is converted to a string object. |
| 202 | </dd></dl> |
| 203 | |
| 204 | <P> |
| 205 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void <b><tt id='l2h-100' xml:id='l2h-100' class="cfunction">PyErr_SetObject</tt></b>(</nobr></td><td>PyObject *<var>type</var>, PyObject *<var>value</var>)</td></tr></table></dt> |
| 206 | <dd> |
| 207 | This function is similar to <tt class="cfunction">PyErr_SetString()</tt> but lets |
| 208 | you specify an arbitrary Python object for the ``value'' of the |
| 209 | exception. |
| 210 | </dd></dl> |
| 211 | |
| 212 | <P> |
| 213 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-101' xml:id='l2h-101' class="cfunction">PyErr_Format</tt></b>(</nobr></td><td>PyObject *<var>exception</var>, |
| 214 | const char *<var>format</var>, ...)</td></tr></table></dt> |
| 215 | <dd> |
| 216 | <div class="refcount-info"> |
| 217 | <span class="label">Return value:</span> |
| 218 | <span class="value">Always <tt class="constant">NULL</tt>.</span> |
| 219 | </div> |
| 220 | This function sets the error indicator and returns <tt class="constant">NULL</tt>. |
| 221 | <var>exception</var> should be a Python exception (class, not |
| 222 | an instance). <var>format</var> should be a string, containing format |
| 223 | codes, similar to <tt class="cfunction">printf()</tt>. The <code>width.precision</code> |
| 224 | before a format code is parsed, but the width part is ignored. |
| 225 | |
| 226 | <P> |
| 227 | <div class="center"><table class="realtable"> |
| 228 | <thead> |
| 229 | <tr> |
| 230 | <th class="center">Character</th> |
| 231 | <th class="left" >Meaning</th> |
| 232 | </tr> |
| 233 | </thead> |
| 234 | <tbody> |
| 235 | <tr><td class="center" valign="baseline"><tt class="character">c</tt></td> |
| 236 | <td class="left" >Character, as an <tt class="ctype">int</tt> parameter</td></tr> |
| 237 | <tr><td class="center" valign="baseline"><tt class="character">d</tt></td> |
| 238 | <td class="left" >Number in decimal, as an <tt class="ctype">int</tt> parameter</td></tr> |
| 239 | <tr><td class="center" valign="baseline"><tt class="character">x</tt></td> |
| 240 | <td class="left" >Number in hexadecimal, as an <tt class="ctype">int</tt> parameter</td></tr> |
| 241 | <tr><td class="center" valign="baseline"><tt class="character">s</tt></td> |
| 242 | <td class="left" >A string, as a <tt class="ctype">char *</tt> parameter</td></tr> |
| 243 | <tr><td class="center" valign="baseline"><tt class="character">p</tt></td> |
| 244 | <td class="left" >A hex pointer, as a <tt class="ctype">void *</tt> parameter</td></tr></tbody> |
| 245 | </table></div> |
| 246 | |
| 247 | <P> |
| 248 | An unrecognized format character causes all the rest of the format |
| 249 | string to be copied as-is to the result string, and any extra |
| 250 | arguments discarded. |
| 251 | </dd></dl> |
| 252 | |
| 253 | <P> |
| 254 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void <b><tt id='l2h-102' xml:id='l2h-102' class="cfunction">PyErr_SetNone</tt></b>(</nobr></td><td>PyObject *<var>type</var>)</td></tr></table></dt> |
| 255 | <dd> |
| 256 | This is a shorthand for "<tt class="samp">PyErr_SetObject(<var>type</var>, |
| 257 | Py_None)</tt>". |
| 258 | </dd></dl> |
| 259 | |
| 260 | <P> |
| 261 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-103' xml:id='l2h-103' class="cfunction">PyErr_BadArgument</tt></b>(</nobr></td><td>)</td></tr></table></dt> |
| 262 | <dd> |
| 263 | This is a shorthand for "<tt class="samp">PyErr_SetString(PyExc_TypeError, |
| 264 | <var>message</var>)</tt>", where <var>message</var> indicates that a built-in |
| 265 | operation was invoked with an illegal argument. It is mostly for |
| 266 | internal use. |
| 267 | </dd></dl> |
| 268 | |
| 269 | <P> |
| 270 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-104' xml:id='l2h-104' class="cfunction">PyErr_NoMemory</tt></b>(</nobr></td><td>)</td></tr></table></dt> |
| 271 | <dd> |
| 272 | <div class="refcount-info"> |
| 273 | <span class="label">Return value:</span> |
| 274 | <span class="value">Always <tt class="constant">NULL</tt>.</span> |
| 275 | </div> |
| 276 | This is a shorthand for "<tt class="samp">PyErr_SetNone(PyExc_MemoryError)</tt>"; it |
| 277 | returns <tt class="constant">NULL</tt> so an object allocation function can write |
| 278 | "<tt class="samp">return PyErr_NoMemory();</tt>" when it runs out of memory. |
| 279 | </dd></dl> |
| 280 | |
| 281 | <P> |
| 282 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-105' xml:id='l2h-105' class="cfunction">PyErr_SetFromErrno</tt></b>(</nobr></td><td>PyObject *<var>type</var>)</td></tr></table></dt> |
| 283 | <dd> |
| 284 | <div class="refcount-info"> |
| 285 | <span class="label">Return value:</span> |
| 286 | <span class="value">Always <tt class="constant">NULL</tt>.</span> |
| 287 | </div> |
| 288 | This is a convenience function to raise an exception when a C |
| 289 | library function has returned an error and set the C variable |
| 290 | <tt class="cdata">errno</tt>. It constructs a tuple object whose first item is the |
| 291 | integer <tt class="cdata">errno</tt> value and whose second item is the |
| 292 | corresponding error message (gotten from |
| 293 | <tt class="cfunction">strerror()</tt><a id='l2h-122' xml:id='l2h-122'></a>), and then calls |
| 294 | "<tt class="samp">PyErr_SetObject(<var>type</var>, <var>object</var>)</tt>". On <span class="Unix">Unix</span>, when |
| 295 | the <tt class="cdata">errno</tt> value is <tt class="constant">EINTR</tt>, indicating an |
| 296 | interrupted system call, this calls |
| 297 | <tt class="cfunction">PyErr_CheckSignals()</tt>, and if that set the error |
| 298 | indicator, leaves it set to that. The function always returns |
| 299 | <tt class="constant">NULL</tt>, so a wrapper function around a system call can write |
| 300 | "<tt class="samp">return PyErr_SetFromErrno(<var>type</var>);</tt>" when the system call |
| 301 | returns an error. |
| 302 | </dd></dl> |
| 303 | |
| 304 | <P> |
| 305 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-106' xml:id='l2h-106' class="cfunction">PyErr_SetFromErrnoWithFilename</tt></b>(</nobr></td><td>PyObject *<var>type</var>, |
| 306 | char *<var>filename</var>)</td></tr></table></dt> |
| 307 | <dd> |
| 308 | <div class="refcount-info"> |
| 309 | <span class="label">Return value:</span> |
| 310 | <span class="value">Always <tt class="constant">NULL</tt>.</span> |
| 311 | </div> |
| 312 | Similar to <tt class="cfunction">PyErr_SetFromErrno()</tt>, with the additional |
| 313 | behavior that if <var>filename</var> is not <tt class="constant">NULL</tt>, it is passed to the |
| 314 | constructor of <var>type</var> as a third parameter. In the case of |
| 315 | exceptions such as <tt class="exception">IOError</tt> and <tt class="exception">OSError</tt>, this |
| 316 | is used to define the <tt class="member">filename</tt> attribute of the exception |
| 317 | instance. |
| 318 | </dd></dl> |
| 319 | |
| 320 | <P> |
| 321 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-107' xml:id='l2h-107' class="cfunction">PyErr_SetFromWindowsErr</tt></b>(</nobr></td><td>int <var>ierr</var>)</td></tr></table></dt> |
| 322 | <dd> |
| 323 | <div class="refcount-info"> |
| 324 | <span class="label">Return value:</span> |
| 325 | <span class="value">Always <tt class="constant">NULL</tt>.</span> |
| 326 | </div> |
| 327 | This is a convenience function to raise <tt class="exception">WindowsError</tt>. |
| 328 | If called with <var>ierr</var> of <tt class="cdata">0</tt>, the error code returned by a |
| 329 | call to <tt class="cfunction">GetLastError()</tt> is used instead. It calls the |
| 330 | Win32 function <tt class="cfunction">FormatMessage()</tt> to retrieve the Windows |
| 331 | description of error code given by <var>ierr</var> or |
| 332 | <tt class="cfunction">GetLastError()</tt>, then it constructs a tuple object whose |
| 333 | first item is the <var>ierr</var> value and whose second item is the |
| 334 | corresponding error message (gotten from |
| 335 | <tt class="cfunction">FormatMessage()</tt>), and then calls |
| 336 | "<tt class="samp">PyErr_SetObject(<var>PyExc_WindowsError</var>, <var>object</var>)</tt>". |
| 337 | This function always returns <tt class="constant">NULL</tt>. |
| 338 | Availability: Windows. |
| 339 | </dd></dl> |
| 340 | |
| 341 | <P> |
| 342 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-108' xml:id='l2h-108' class="cfunction">PyErr_SetExcFromWindowsErr</tt></b>(</nobr></td><td>PyObject *<var>type</var>, |
| 343 | int <var>ierr</var>)</td></tr></table></dt> |
| 344 | <dd> |
| 345 | Similar to <tt class="cfunction">PyErr_SetFromWindowsErr()</tt>, with an additional |
| 346 | parameter specifying the exception type to be raised. |
| 347 | Availability: Windows. |
| 348 | |
| 349 | <span class="versionnote">New in version 2.3.</span> |
| 350 | |
| 351 | </dd></dl> |
| 352 | |
| 353 | <P> |
| 354 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-109' xml:id='l2h-109' class="cfunction">PyErr_SetFromWindowsErrWithFilename</tt></b>(</nobr></td><td>int <var>ierr</var>, |
| 355 | char *<var>filename</var>)</td></tr></table></dt> |
| 356 | <dd> |
| 357 | <div class="refcount-info"> |
| 358 | <span class="label">Return value:</span> |
| 359 | <span class="value">Always <tt class="constant">NULL</tt>.</span> |
| 360 | </div> |
| 361 | Similar to <tt class="cfunction">PyErr_SetFromWindowsErr()</tt>, with the |
| 362 | additional behavior that if <var>filename</var> is not <tt class="constant">NULL</tt>, it is |
| 363 | passed to the constructor of <tt class="exception">WindowsError</tt> as a third |
| 364 | parameter. |
| 365 | Availability: Windows. |
| 366 | </dd></dl> |
| 367 | |
| 368 | <P> |
| 369 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-110' xml:id='l2h-110' class="cfunction">PyErr_SetExcFromWindowsErrWithFilename</tt></b>(</nobr></td><td>PyObject *<var>type</var>, int <var>ierr</var>, char *<var>filename</var>)</td></tr></table></dt> |
| 370 | <dd> |
| 371 | Similar to <tt class="cfunction">PyErr_SetFromWindowsErrWithFilename()</tt>, with |
| 372 | an additional parameter specifying the exception type to be raised. |
| 373 | Availability: Windows. |
| 374 | |
| 375 | <span class="versionnote">New in version 2.3.</span> |
| 376 | |
| 377 | </dd></dl> |
| 378 | |
| 379 | <P> |
| 380 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void <b><tt id='l2h-111' xml:id='l2h-111' class="cfunction">PyErr_BadInternalCall</tt></b>(</nobr></td><td>)</td></tr></table></dt> |
| 381 | <dd> |
| 382 | This is a shorthand for "<tt class="samp">PyErr_SetString(PyExc_TypeError, |
| 383 | <var>message</var>)</tt>", where <var>message</var> indicates that an internal |
| 384 | operation (e.g. a Python/C API function) was invoked with an illegal |
| 385 | argument. It is mostly for internal use. |
| 386 | </dd></dl> |
| 387 | |
| 388 | <P> |
| 389 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-112' xml:id='l2h-112' class="cfunction">PyErr_Warn</tt></b>(</nobr></td><td>PyObject *<var>category</var>, char *<var>message</var>)</td></tr></table></dt> |
| 390 | <dd> |
| 391 | Issue a warning message. The <var>category</var> argument is a warning |
| 392 | category (see below) or <tt class="constant">NULL</tt>; the <var>message</var> argument is a |
| 393 | message string. |
| 394 | |
| 395 | <P> |
| 396 | This function normally prints a warning message to <var>sys.stderr</var>; |
| 397 | however, it is also possible that the user has specified that |
| 398 | warnings are to be turned into errors, and in that case this will |
| 399 | raise an exception. It is also possible that the function raises an |
| 400 | exception because of a problem with the warning machinery (the |
| 401 | implementation imports the <tt class="module">warnings</tt> module to do the heavy |
| 402 | lifting). The return value is <code>0</code> if no exception is raised, |
| 403 | or <code>-1</code> if an exception is raised. (It is not possible to |
| 404 | determine whether a warning message is actually printed, nor what |
| 405 | the reason is for the exception; this is intentional.) If an |
| 406 | exception is raised, the caller should do its normal exception |
| 407 | handling (for example, <tt class="cfunction">Py_DECREF()</tt> owned references and |
| 408 | return an error value). |
| 409 | |
| 410 | <P> |
| 411 | Warning categories must be subclasses of <tt class="cdata">Warning</tt>; the |
| 412 | default warning category is <tt class="cdata">RuntimeWarning</tt>. The standard |
| 413 | Python warning categories are available as global variables whose |
| 414 | names are "<tt class="samp">PyExc_</tt>" followed by the Python exception name. |
| 415 | These have the type <tt class="ctype">PyObject*</tt>; they are all class objects. |
| 416 | Their names are <tt class="cdata">PyExc_Warning</tt>, <tt class="cdata">PyExc_UserWarning</tt>, |
| 417 | <tt class="cdata">PyExc_DeprecationWarning</tt>, <tt class="cdata">PyExc_SyntaxWarning</tt>, |
| 418 | <tt class="cdata">PyExc_RuntimeWarning</tt>, and <tt class="cdata">PyExc_FutureWarning</tt>. |
| 419 | <tt class="cdata">PyExc_Warning</tt> is a subclass of <tt class="cdata">PyExc_Exception</tt>; the |
| 420 | other warning categories are subclasses of <tt class="cdata">PyExc_Warning</tt>. |
| 421 | |
| 422 | <P> |
| 423 | For information about warning control, see the documentation for the |
| 424 | <tt class="module">warnings</tt> module and the <b class="programopt">-W</b> option in the |
| 425 | command line documentation. There is no C API for warning control. |
| 426 | </dd></dl> |
| 427 | |
| 428 | <P> |
| 429 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-113' xml:id='l2h-113' class="cfunction">PyErr_WarnExplicit</tt></b>(</nobr></td><td>PyObject *<var>category</var>, char *<var>message</var>, |
| 430 | char *<var>filename</var>, int <var>lineno</var>, char *<var>module</var>, PyObject *<var>registry</var>)</td></tr></table></dt> |
| 431 | <dd> |
| 432 | Issue a warning message with explicit control over all warning |
| 433 | attributes. This is a straightforward wrapper around the Python |
| 434 | function <tt class="function">warnings.warn_explicit()</tt>, see there for more |
| 435 | information. The <var>module</var> and <var>registry</var> arguments may be |
| 436 | set to <tt class="constant">NULL</tt> to get the default effect described there. |
| 437 | </dd></dl> |
| 438 | |
| 439 | <P> |
| 440 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-114' xml:id='l2h-114' class="cfunction">PyErr_CheckSignals</tt></b>(</nobr></td><td>)</td></tr></table></dt> |
| 441 | <dd> |
| 442 | This function interacts with Python's signal handling. It checks |
| 443 | whether a signal has been sent to the processes and if so, invokes |
| 444 | the corresponding signal handler. If the |
| 445 | <tt class="module">signal</tt><a id='l2h-123' xml:id='l2h-123'></a> module is supported, this can |
| 446 | invoke a signal handler written in Python. In all cases, the |
| 447 | default effect for <tt class="constant">SIGINT</tt><a id='l2h-124' xml:id='l2h-124'></a> is to raise the |
| 448 | <a id='l2h-116' xml:id='l2h-116'></a> <tt class="exception">KeyboardInterrupt</tt> exception. If an exception is raised |
| 449 | the error indicator is set and the function returns <code>1</code>; |
| 450 | otherwise the function returns <code>0</code>. The error indicator may or |
| 451 | may not be cleared if it was previously set. |
| 452 | </dd></dl> |
| 453 | |
| 454 | <P> |
| 455 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void <b><tt id='l2h-117' xml:id='l2h-117' class="cfunction">PyErr_SetInterrupt</tt></b>(</nobr></td><td>)</td></tr></table></dt> |
| 456 | <dd> |
| 457 | This function simulates the effect of a |
| 458 | <tt class="constant">SIGINT</tt><a id='l2h-125' xml:id='l2h-125'></a> signal arriving -- the next time |
| 459 | <tt class="cfunction">PyErr_CheckSignals()</tt> is called, |
| 460 | <a id='l2h-119' xml:id='l2h-119'></a> <tt class="exception">KeyboardInterrupt</tt> will be raised. It may be called |
| 461 | without holding the interpreter lock. |
| 462 | </dd></dl> |
| 463 | |
| 464 | <P> |
| 465 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-120' xml:id='l2h-120' class="cfunction">PyErr_NewException</tt></b>(</nobr></td><td>char *<var>name</var>, |
| 466 | PyObject *<var>base</var>, |
| 467 | PyObject *<var>dict</var>)</td></tr></table></dt> |
| 468 | <dd> |
| 469 | <div class="refcount-info"> |
| 470 | <span class="label">Return value:</span> |
| 471 | <span class="value">New reference.</span> |
| 472 | </div> |
| 473 | This utility function creates and returns a new exception object. |
| 474 | The <var>name</var> argument must be the name of the new exception, a C |
| 475 | string of the form <code>module.class</code>. The <var>base</var> and |
| 476 | <var>dict</var> arguments are normally <tt class="constant">NULL</tt>. This creates a class |
| 477 | object derived from the root for all exceptions, the built-in name |
| 478 | <tt class="exception">Exception</tt> (accessible in C as <tt class="cdata">PyExc_Exception</tt>). |
| 479 | The <tt class="member">__module__</tt> attribute of the new class is set to the |
| 480 | first part (up to the last dot) of the <var>name</var> argument, and the |
| 481 | class name is set to the last part (after the last dot). The |
| 482 | <var>base</var> argument can be used to specify an alternate base class. |
| 483 | The <var>dict</var> argument can be used to specify a dictionary of class |
| 484 | variables and methods. |
| 485 | </dd></dl> |
| 486 | |
| 487 | <P> |
| 488 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void <b><tt id='l2h-121' xml:id='l2h-121' class="cfunction">PyErr_WriteUnraisable</tt></b>(</nobr></td><td>PyObject *<var>obj</var>)</td></tr></table></dt> |
| 489 | <dd> |
| 490 | This utility function prints a warning message to <code>sys.stderr</code> |
| 491 | when an exception has been set but it is impossible for the |
| 492 | interpreter to actually raise the exception. It is used, for |
| 493 | example, when an exception occurs in an <tt class="method">__del__()</tt> method. |
| 494 | |
| 495 | <P> |
| 496 | The function is called with a single argument <var>obj</var> that |
| 497 | identifies the context in which the unraisable exception occurred. |
| 498 | The repr of <var>obj</var> will be printed in the warning message. |
| 499 | </dd></dl> |
| 500 | |
| 501 | <P> |
| 502 | |
| 503 | <p><br /></p><hr class='online-navigation' /> |
| 504 | <div class='online-navigation'> |
| 505 | <!--Table of Child-Links--> |
| 506 | <A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a> |
| 507 | |
| 508 | <UL CLASS="ChildLinks"> |
| 509 | <LI><A href="standardExceptions.html">4.1 Standard Exceptions</a> |
| 510 | <LI><A href="node15.html">4.2 Deprecation of String Exceptions</a> |
| 511 | </ul> |
| 512 | <!--End of Table of Child-Links--> |
| 513 | </div> |
| 514 | |
| 515 | <DIV CLASS="navigation"> |
| 516 | <div class='online-navigation'> |
| 517 | <p></p><hr /> |
| 518 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 519 | <tr> |
| 520 | <td class='online-navigation'><a rel="prev" title="3. Reference Counting" |
| 521 | href="countingRefs.html"><img src='../icons/previous.png' |
| 522 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 523 | <td class='online-navigation'><a rel="parent" title="Python/C API Reference Manual" |
| 524 | href="api.html"><img src='../icons/up.png' |
| 525 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 526 | <td class='online-navigation'><a rel="next" title="4.1 Standard Exceptions" |
| 527 | href="standardExceptions.html"><img src='../icons/next.png' |
| 528 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 529 | <td align="center" width="100%">Python/C API Reference Manual</td> |
| 530 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 531 | href="contents.html"><img src='../icons/contents.png' |
| 532 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 533 | <td class='online-navigation'><img src='../icons/blank.png' |
| 534 | border='0' height='32' alt='' width='32' /></td> |
| 535 | <td class='online-navigation'><a rel="index" title="Index" |
| 536 | href="genindex.html"><img src='../icons/index.png' |
| 537 | border='0' height='32' alt='Index' width='32' /></A></td> |
| 538 | </tr></table> |
| 539 | <div class='online-navigation'> |
| 540 | <b class="navlabel">Previous:</b> |
| 541 | <a class="sectref" rel="prev" href="countingRefs.html">3. Reference Counting</A> |
| 542 | <b class="navlabel">Up:</b> |
| 543 | <a class="sectref" rel="parent" href="api.html">Python/C API Reference Manual</A> |
| 544 | <b class="navlabel">Next:</b> |
| 545 | <a class="sectref" rel="next" href="standardExceptions.html">4.1 Standard Exceptions</A> |
| 546 | </div> |
| 547 | </div> |
| 548 | <hr /> |
| 549 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> |
| 550 | </DIV> |
| 551 | <!--End of Navigation Panel--> |
| 552 | <ADDRESS> |
| 553 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. |
| 554 | </ADDRESS> |
| 555 | </BODY> |
| 556 | </HTML> |