Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(169902)

Delta Between Two Patch Sets: Doc/c-api/exceptions.rst

Issue 11619: On Windows, don't encode filenames in the import machinery
Left Patch Set: Created 8 years, 7 months ago
Right Patch Set: Created 6 years, 3 months ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
Left: Side by side diff | Download
Right: Side by side diff | Download
« no previous file with change/comment | « no previous file | Include/ast.h » ('j') | no next file with change/comment »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
LEFTRIGHT
1 .. highlightlang:: c 1 .. highlightlang:: c
2 2
3 3
4 .. _exceptionhandling: 4 .. _exceptionhandling:
5 5
6 ****************** 6 ******************
7 Exception Handling 7 Exception Handling
8 ****************** 8 ******************
9 9
10 The functions described in this chapter will let you handle and raise Python 10 The functions described in this chapter will let you handle and raise Python
(...skipping 109 matching lines...) Expand 10 before | Expand all | Expand 10 after
120 later.) This call takes away a reference to each object: you must own a 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 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 122 these references. (If you don't understand this, don't use this function. I
123 warned you.) 123 warned you.)
124 124
125 .. note:: 125 .. note::
126 126
127 This function is normally only used by code that needs to save and restore the 127 This function is normally only used by code that needs to save and restore the
128 error indicator temporarily; use :c:func:`PyErr_Fetch` to save the current 128 error indicator temporarily; use :c:func:`PyErr_Fetch` to save the current
129 exception state. 129 exception state.
130
131
132 .. c:function:: void PyErr_GetExcInfo(PyObject **ptype, PyObject **pvalue, PyObj ect **ptraceback)
133
134 Retrieve the exception info, as known from ``sys.exc_info()``. This refers
135 to an exception that was already caught, not to an exception that was
136 freshly raised. Returns new references for the three objects, any of which
137 may be *NULL*. Does not modify the exception info state.
138
139 .. note::
140
141 This function is not normally used by code that wants to handle exceptions .
142 Rather, it can be used when code needs to save and restore the exception
143 state temporarily. Use :c:func:`PyErr_SetExcInfo` to restore or clear the
144 exception state.
145
146 .. versionadded:: 3.3
147
148
149 .. c:function:: void PyErr_SetExcInfo(PyObject *type, PyObject *value, PyObject *traceback)
150
151 Set the exception info, as known from ``sys.exc_info()``. This refers
152 to an exception that was already caught, not to an exception that was
153 freshly raised. This function steals the references of the arguments.
154 To clear the exception state, pass *NULL* for all three arguments.
155 For general rules about the three arguments, see :c:func:`PyErr_Restore`.
156
157 .. note::
158
159 This function is not normally used by code that wants to handle exceptions .
160 Rather, it can be used when code needs to save and restore the exception
161 state temporarily. Use :c:func:`PyErr_GetExcInfo` to read the exception
162 state.
163
164 .. versionadded:: 3.3
130 165
131 166
132 .. c:function:: void PyErr_SetString(PyObject *type, const char *message) 167 .. c:function:: void PyErr_SetString(PyObject *type, const char *message)
133 168
134 This is the most common way to set the error indicator. The first argument 169 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, 170 specifies the exception type; it is normally one of the standard exceptions,
136 e.g. :c:data:`PyExc_RuntimeError`. You need not increment its reference coun t. 171 e.g. :c:data:`PyExc_RuntimeError`. You need not increment its reference coun t.
137 The second argument is an error message; it is decoded from ``'utf-8``'. 172 The second argument is an error message; it is decoded from ``'utf-8``'.
138 173
139 174
(...skipping 40 matching lines...) Expand 10 before | Expand all | Expand 10 after
180 tuple object whose first item is the integer :c:data:`errno` value and whose 215 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 `), 216 second item is the corresponding error message (gotten from :c:func:`strerror `),
182 and then calls ``PyErr_SetObject(type, object)``. On Unix, when the 217 and then calls ``PyErr_SetObject(type, object)``. On Unix, when the
183 :c:data:`errno` value is :const:`EINTR`, indicating an interrupted system cal l, 218 :c:data:`errno` value is :const:`EINTR`, indicating an interrupted system cal l,
184 this calls :c:func:`PyErr_CheckSignals`, and if that set the error indicator, 219 this calls :c:func:`PyErr_CheckSignals`, and if that set the error indicator,
185 leaves it set to that. The function always returns *NULL*, so a wrapper 220 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);`` 221 function around a system call can write ``return PyErr_SetFromErrno(type);``
187 when the system call returns an error. 222 when the system call returns an error.
188 223
189 224
225 .. c:function:: PyObject* PyErr_SetFromErrnoWithFilenameObject(PyObject *type, P yObject *filenameObject)
226
227 Similar to :c:func:`PyErr_SetFromErrno`, with the additional behavior that if
228 *filenameObject* is not *NULL*, it is passed to the constructor of *type* as
229 a third parameter. In the case of exceptions such as :exc:`IOError` and
230 :exc:`OSError`, this is used to define the :attr:`filename` attribute of the
231 exception instance.
232
233
190 .. c:function:: PyObject* PyErr_SetFromErrnoWithFilename(PyObject *type, const c har *filename) 234 .. c:function:: PyObject* PyErr_SetFromErrnoWithFilename(PyObject *type, const c har *filename)
191 235
192 Similar to :c:func:`PyErr_SetFromErrno`, with the additional behavior that if 236 Similar to :c:func:`PyErr_SetFromErrnoWithFilenameObject`, but the filename
193 *filename* is not *NULL*, it is passed to the constructor of *type* as a thir d 237 is given as a C string. *filename* is decoded from the filesystem encoding
194 parameter. In the case of exceptions such as :exc:`IOError` and :exc:`OSErro r`,
195 this is used to define the :attr:`filename` attribute of the exception instan ce.
196 *filename* is decoded from the filesystem encoding
197 (:func:`sys.getfilesystemencoding`). 238 (:func:`sys.getfilesystemencoding`).
198 239
199 240
200 .. c:function:: PyObject* PyErr_SetFromWindowsErr(int ierr) 241 .. c:function:: PyObject* PyErr_SetFromWindowsErr(int ierr)
201 242
202 This is a convenience function to raise :exc:`WindowsError`. If called with 243 This is a convenience function to raise :exc:`WindowsError`. If called with
203 *ierr* of :c:data:`0`, the error code returned by a call to :c:func:`GetLastE rror` 244 *ierr* of :c:data:`0`, the error code returned by a call to :c:func:`GetLastE rror`
204 is used instead. It calls the Win32 function :c:func:`FormatMessage` to retr ieve 245 is used instead. It calls the Win32 function :c:func:`FormatMessage` to retr ieve
205 the Windows description of error code given by *ierr* or :c:func:`GetLastErro r`, 246 the Windows description of error code given by *ierr* or :c:func:`GetLastErro r`,
206 then it constructs a tuple object whose first item is the *ierr* value and wh ose 247 then it constructs a tuple object whose first item is the *ierr* value and wh ose
207 second item is the corresponding error message (gotten from 248 second item is the corresponding error message (gotten from
208 :c:func:`FormatMessage`), and then calls ``PyErr_SetObject(PyExc_WindowsError , 249 :c:func:`FormatMessage`), and then calls ``PyErr_SetObject(PyExc_WindowsError ,
209 object)``. This function always returns *NULL*. Availability: Windows. 250 object)``. This function always returns *NULL*. Availability: Windows.
210 251
211 252
212 .. c:function:: PyObject* PyErr_SetExcFromWindowsErr(PyObject *type, int ierr) 253 .. c:function:: PyObject* PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)
213 254
214 Similar to :c:func:`PyErr_SetFromWindowsErr`, with an additional parameter 255 Similar to :c:func:`PyErr_SetFromWindowsErr`, with an additional parameter
215 specifying the exception type to be raised. Availability: Windows. 256 specifying the exception type to be raised. Availability: Windows.
216 257
217 258
259 .. c:function:: PyObject* PyErr_SetFromWindowsErrWithFilenameObject(int ierr, Py Object *filenameObject)
260
261 Similar to :c:func:`PyErr_SetFromWindowsErr`, with the additional behavior
262 that if *filenameObject* is not *NULL*, it is passed to the constructor of
263 :exc:`WindowsError` as a third parameter. Availability: Windows.
264
265
218 .. c:function:: PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const ch ar *filename) 266 .. c:function:: PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const ch ar *filename)
219 267
220 Similar to :c:func:`PyErr_SetFromWindowsErr`, with the additional behavior th at 268 Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, but the
221 if *filename* is not *NULL*, it is passed to the constructor of 269 filename is given as a C string. *filename* is decoded from the filesystem
222 :exc:`WindowsError` as a third parameter. *filename* is decoded from the 270 encoding (:func:`sys.getfilesystemencoding`). Availability: Windows.
223 filesystem encoding (:func:`sys.getfilesystemencoding`). Availability: 271
224 Windows. 272
225 273 .. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject *type, int ierr, PyObject *filename)
226 274
227 .. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, char *filename) 275 Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, with an
276 additional parameter specifying the exception type to be raised.
277 Availability: Windows.
278
279
280 .. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, const char *filename)
228 281
229 Similar to :c:func:`PyErr_SetFromWindowsErrWithFilename`, with an additional 282 Similar to :c:func:`PyErr_SetFromWindowsErrWithFilename`, with an additional
230 parameter specifying the exception type to be raised. Availability: Windows. 283 parameter specifying the exception type to be raised. Availability: Windows.
231 284
232 285
233 .. c:function:: void PyErr_SyntaxLocationObject(char *filename, int lineno, int col_offset) 286 .. c:function:: PyObject* PyErr_SetImportError(PyObject *msg, PyObject *name, Py Object *path)
287
288 This is a convenience function to raise :exc:`ImportError`. *msg* will be
289 set as the exception's message string. *name* and *path*, both of which can
290 be ``NULL``, will be set as the :exc:`ImportError`'s respective ``name``
291 and ``path`` attributes.
292
293 .. versionadded:: 3.3
294
295
296 .. c:function:: void PyErr_SyntaxLocationObject(PyObject *filename, int lineno, int col_offset)
234 297
235 Set file, line, and offset information for the current exception. If the 298 Set file, line, and offset information for the current exception. If the
236 current exception is not a :exc:`SyntaxError`, then it sets additional 299 current exception is not a :exc:`SyntaxError`, then it sets additional
237 attributes, which make the exception printing subsystem think the exception 300 attributes, which make the exception printing subsystem think the exception
238 is a :exc:`SyntaxError`. 301 is a :exc:`SyntaxError`.
239 302
240 .. versionadded:: 3.3 303 .. versionadded:: 3.3
241 304
242 305
243 .. c:function:: void PyErr_SyntaxLocationEx(char *filename, int lineno, int col_ offset) 306 .. c:function:: void PyErr_SyntaxLocationEx(char *filename, int lineno, int col_ offset)
244 307
245 Like :c:func:`PyErr_SyntaxLocationObject`, but *filename* is a byte string 308 Like :c:func:`PyErr_SyntaxLocationObject`, but *filename* is a byte string
246 decoded from the filesystem encoding (:func:`sys.getfilesystemencoding`). 309 decoded from the filesystem encoding (:func:`sys.getfilesystemencoding`).
247 310
248 .. versionadded:: 3.2 311 .. versionadded:: 3.2
249 312
250 313
251 .. c:function:: void PyErr_SyntaxLocation(char *filename, int lineno) 314 .. c:function:: void PyErr_SyntaxLocation(char *filename, int lineno)
252 315
253 Like :c:func:`PyErr_SyntaxLocationEx`, but the *col_offset* parameter is 316 Like :c:func:`PyErr_SyntaxLocationEx`, but the col_offset parameter is
254 omitted. 317 omitted.
255 318
256 319
257 .. c:function:: void PyErr_BadInternalCall() 320 .. c:function:: void PyErr_BadInternalCall()
258 321
259 This is a shorthand for ``PyErr_SetString(PyExc_SystemError, message)``, 322 This is a shorthand for ``PyErr_SetString(PyExc_SystemError, message)``,
260 where *message* indicates that an internal operation (e.g. a Python/C API 323 where *message* indicates that an internal operation (e.g. a Python/C API
261 function) was invoked with an illegal argument. It is mostly for internal 324 function) was invoked with an illegal argument. It is mostly for internal
262 use. 325 use.
263 326
(...skipping 56 matching lines...) Expand 10 before | Expand all | Expand 10 after
320 383
321 384
322 .. c:function:: int PyErr_WarnFormat(PyObject *category, Py_ssize_t stack_level, const char *format, ...) 385 .. c:function:: int PyErr_WarnFormat(PyObject *category, Py_ssize_t stack_level, const char *format, ...)
323 386
324 Function similar to :c:func:`PyErr_WarnEx`, but use 387 Function similar to :c:func:`PyErr_WarnEx`, but use
325 :c:func:`PyUnicode_FromFormat` to format the warning message. *format* is 388 :c:func:`PyUnicode_FromFormat` to format the warning message. *format* is
326 an ASCII-encoded string. 389 an ASCII-encoded string.
327 390
328 .. versionadded:: 3.2 391 .. versionadded:: 3.2
329 392
393
330 .. c:function:: int PyErr_CheckSignals() 394 .. c:function:: int PyErr_CheckSignals()
331 395
332 .. index:: 396 .. index::
333 module: signal 397 module: signal
334 single: SIGINT 398 single: SIGINT
335 single: KeyboardInterrupt (built-in exception) 399 single: KeyboardInterrupt (built-in exception)
336 400
337 This function interacts with Python's signal handling. It checks whether a 401 This function interacts with Python's signal handling. It checks whether a
338 signal has been sent to the processes and if so, invokes the corresponding 402 signal has been sent to the processes and if so, invokes the corresponding
339 signal handler. If the :mod:`signal` module is supported, this can invoke a 403 signal handler. If the :mod:`signal` module is supported, this can invoke a
(...skipping 23 matching lines...) Expand all
363 This utility function specifies a file descriptor to which a ``'\0'`` byte wi ll 427 This utility function specifies a file descriptor to which a ``'\0'`` byte wi ll
364 be written whenever a signal is received. It returns the previous such file 428 be written whenever a signal is received. It returns the previous such file
365 descriptor. The value ``-1`` disables the feature; this is the initial state . 429 descriptor. The value ``-1`` disables the feature; this is the initial state .
366 This is equivalent to :func:`signal.set_wakeup_fd` in Python, but without any 430 This is equivalent to :func:`signal.set_wakeup_fd` in Python, but without any
367 error checking. *fd* should be a valid file descriptor. The function should 431 error checking. *fd* should be a valid file descriptor. The function should
368 only be called from the main thread. 432 only be called from the main thread.
369 433
370 434
371 .. c:function:: PyObject* PyErr_NewException(char *name, PyObject *base, PyObjec t *dict) 435 .. c:function:: PyObject* PyErr_NewException(char *name, PyObject *base, PyObjec t *dict)
372 436
373 This utility function creates and returns a new exception object. The *name* 437 This utility function creates and returns a new exception class. The *name*
374 argument must be the name of the new exception, a C string of the form 438 argument must be the name of the new exception, a C string of the form
375 ``module.class``. The *base* and *dict* arguments are normally *NULL*. This 439 ``module.classname``. The *base* and *dict* arguments are normally *NULL*.
376 creates a class object derived from :exc:`Exception` (accessible in C as 440 This creates a class object derived from :exc:`Exception` (accessible in C as
377 :c:data:`PyExc_Exception`). 441 :c:data:`PyExc_Exception`).
378 442
379 The :attr:`__module__` attribute of the new class is set to the first part (u p 443 The :attr:`__module__` attribute of the new class is set to the first part (u p
380 to the last dot) of the *name* argument, and the class name is set to the las t 444 to the last dot) of the *name* argument, and the class name is set to the las t
381 part (after the last dot). The *base* argument can be used to specify altern ate 445 part (after the last dot). The *base* argument can be used to specify altern ate
382 base classes; it can either be only one class or a tuple of classes. The *dic t* 446 base classes; it can either be only one class or a tuple of classes. The *dic t*
383 argument can be used to specify a dictionary of class variables and methods. 447 argument can be used to specify a dictionary of class variables and methods.
384 448
385 449
386 .. c:function:: PyObject* PyErr_NewExceptionWithDoc(char *name, char *doc, PyObj ect *base, PyObject *dict) 450 .. c:function:: PyObject* PyErr_NewExceptionWithDoc(char *name, char *doc, PyObj ect *base, PyObject *dict)
(...skipping 43 matching lines...) Expand 10 before | Expand all | Expand 10 after
430 494
431 .. c:function:: void PyException_SetContext(PyObject *ex, PyObject *ctx) 495 .. c:function:: void PyException_SetContext(PyObject *ex, PyObject *ctx)
432 496
433 Set the context associated with the exception to *ctx*. Use *NULL* to clear 497 Set the context associated with the exception to *ctx*. Use *NULL* to clear
434 it. There is no type check to make sure that *ctx* is an exception instance. 498 it. There is no type check to make sure that *ctx* is an exception instance.
435 This steals a reference to *ctx*. 499 This steals a reference to *ctx*.
436 500
437 501
438 .. c:function:: PyObject* PyException_GetCause(PyObject *ex) 502 .. c:function:: PyObject* PyException_GetCause(PyObject *ex)
439 503
440 Return the cause (another exception instance set by ``raise ... from ...``) 504 Return the cause (either an exception instance, or :const:`None`,
441 associated with the exception as a new reference, as accessible from Python 505 set by ``raise ... from ...``) associated with the exception as a new
442 through :attr:`__cause__`. If there is no cause associated, this returns 506 reference, as accessible from Python through :attr:`__cause__`.
443 *NULL*.
444 507
445 508
446 .. c:function:: void PyException_SetCause(PyObject *ex, PyObject *ctx) 509 .. c:function:: void PyException_SetCause(PyObject *ex, PyObject *ctx)
447 510
448 Set the cause associated with the exception to *ctx*. Use *NULL* to clear 511 Set the cause associated with the exception to *ctx*. Use *NULL* to clear
449 it. There is no type check to make sure that *ctx* is an exception instance. 512 it. There is no type check to make sure that *ctx* is either an exception
450 This steals a reference to *ctx*. 513 instance or :const:`None`. This steals a reference to *ctx*.
514
515 :attr:`__suppress_context__` is implicitly set to ``True`` by this function.
451 516
452 517
453 .. _unicodeexceptions: 518 .. _unicodeexceptions:
454 519
455 Unicode Exception Objects 520 Unicode Exception Objects
456 ========================= 521 =========================
457 522
458 The following functions are used to create and modify Unicode exceptions from C. 523 The following functions are used to create and modify Unicode exceptions from C.
459 524
460 .. c:function:: PyObject* PyUnicodeDecodeError_Create(const char *encoding, cons t char *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason) 525 .. c:function:: PyObject* PyUnicodeDecodeError_Create(const char *encoding, cons t char *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
(...skipping 73 matching lines...) Expand 10 before | Expand all | Expand 10 after
534 599
535 These two functions provide a way to perform safe recursive calls at the C 600 These two functions provide a way to perform safe recursive calls at the C
536 level, both in the core and in extension modules. They are needed if the 601 level, both in the core and in extension modules. They are needed if the
537 recursive code does not necessarily invoke Python code (which tracks its 602 recursive code does not necessarily invoke Python code (which tracks its
538 recursion depth automatically). 603 recursion depth automatically).
539 604
540 .. c:function:: int Py_EnterRecursiveCall(char *where) 605 .. c:function:: int Py_EnterRecursiveCall(char *where)
541 606
542 Marks a point where a recursive C-level call is about to be performed. 607 Marks a point where a recursive C-level call is about to be performed.
543 608
544 If :const:`USE_STACKCHECK` is defined, this function checks if the the OS 609 If :const:`USE_STACKCHECK` is defined, this function checks if the OS
545 stack overflowed using :c:func:`PyOS_CheckStack`. In this is the case, it 610 stack overflowed using :c:func:`PyOS_CheckStack`. In this is the case, it
546 sets a :exc:`MemoryError` and returns a nonzero value. 611 sets a :exc:`MemoryError` and returns a nonzero value.
547 612
548 The function then checks if the recursion limit is reached. If this is the 613 The function then checks if the recursion limit is reached. If this is the
549 case, a :exc:`RuntimeError` is set and a nonzero value is returned. 614 case, a :exc:`RuntimeError` is set and a nonzero value is returned.
550 Otherwise, zero is returned. 615 Otherwise, zero is returned.
551 616
552 *where* should be a string such as ``" in instance check"`` to be 617 *where* should be a string such as ``" in instance check"`` to be
553 concatenated to the :exc:`RuntimeError` message caused by the recursion depth 618 concatenated to the :exc:`RuntimeError` message caused by the recursion depth
554 limit. 619 limit.
555 620
556 .. c:function:: void Py_LeaveRecursiveCall() 621 .. c:function:: void Py_LeaveRecursiveCall()
557 622
558 Ends a :c:func:`Py_EnterRecursiveCall`. Must be called once for each 623 Ends a :c:func:`Py_EnterRecursiveCall`. Must be called once for each
559 *successful* invocation of :c:func:`Py_EnterRecursiveCall`. 624 *successful* invocation of :c:func:`Py_EnterRecursiveCall`.
560 625
561 Properly implementing :attr:`tp_repr` for container types requires 626 Properly implementing :c:member:`~PyTypeObject.tp_repr` for container types requ ires
562 special recursion handling. In addition to protecting the stack, 627 special recursion handling. In addition to protecting the stack,
563 :attr:`tp_repr` also needs to track objects to prevent cycles. The 628 :c:member:`~PyTypeObject.tp_repr` also needs to track objects to prevent cycles. The
564 following two functions facilitate this functionality. Effectively, 629 following two functions facilitate this functionality. Effectively,
565 these are the C equivalent to :func:`reprlib.recursive_repr`. 630 these are the C equivalent to :func:`reprlib.recursive_repr`.
566 631
567 .. c:function:: int Py_ReprEnter(PyObject *object) 632 .. c:function:: int Py_ReprEnter(PyObject *object)
568 633
569 Called at the beginning of the :attr:`tp_repr` implementation to 634 Called at the beginning of the :c:member:`~PyTypeObject.tp_repr` implementati on to
570 detect cycles. 635 detect cycles.
571 636
572 If the object has already been processed, the function returns a 637 If the object has already been processed, the function returns a
573 positive integer. In that case the :attr:`tp_repr` implementation 638 positive integer. In that case the :c:member:`~PyTypeObject.tp_repr` impleme ntation
574 should return a string object indicating a cycle. As examples, 639 should return a string object indicating a cycle. As examples,
575 :class:`dict` objects return ``{...}`` and :class:`list` objects 640 :class:`dict` objects return ``{...}`` and :class:`list` objects
576 return ``[...]``. 641 return ``[...]``.
577 642
578 The function will return a negative integer if the recursion limit 643 The function will return a negative integer if the recursion limit
579 is reached. In that case the :attr:`tp_repr` implementation should 644 is reached. In that case the :c:member:`~PyTypeObject.tp_repr` implementatio n should
580 typically return ``NULL``. 645 typically return ``NULL``.
581 646
582 Otherwise, the function returns zero and the :attr:`tp_repr` 647 Otherwise, the function returns zero and the :c:member:`~PyTypeObject.tp_repr `
583 implementation can continue normally. 648 implementation can continue normally.
584 649
585 .. c:function:: void Py_ReprLeave(PyObject *object) 650 .. c:function:: void Py_ReprLeave(PyObject *object)
586 651
587 Ends a :c:func:`Py_ReprEnter`. Must be called once for each 652 Ends a :c:func:`Py_ReprEnter`. Must be called once for each
588 invocation of :c:func:`Py_ReprEnter` that returns zero. 653 invocation of :c:func:`Py_ReprEnter` that returns zero.
589 654
590 655
591 .. _standardexceptions: 656 .. _standardexceptions:
592 657
593 Standard Exceptions 658 Standard Exceptions
594 =================== 659 ===================
595 660
596 All standard Python exceptions are available as global variables whose names are 661 All standard Python exceptions are available as global variables whose names are
597 ``PyExc_`` followed by the Python exception name. These have the type 662 ``PyExc_`` followed by the Python exception name. These have the type
598 :c:type:`PyObject\*`; they are all class objects. For completeness, here are al l 663 :c:type:`PyObject\*`; they are all class objects. For completeness, here are al l
599 the variables: 664 the variables:
600 665
601 +-------------------------------------+----------------------------+----------+ 666 +-----------------------------------------+---------------------------------+--- -------+
602 | C Name | Python Name | Notes | 667 | C Name | Python Name | No tes |
603 +=====================================+============================+==========+ 668 +=========================================+=================================+=== =======+
604 | :c:data:`PyExc_BaseException` | :exc:`BaseException` | \(1) | 669 | :c:data:`PyExc_BaseException` | :exc:`BaseException` | \( 1) |
605 +-------------------------------------+----------------------------+----------+ 670 +-----------------------------------------+---------------------------------+--- -------+
606 | :c:data:`PyExc_Exception` | :exc:`Exception` | \(1) | 671 | :c:data:`PyExc_Exception` | :exc:`Exception` | \( 1) |
607 +-------------------------------------+----------------------------+----------+ 672 +-----------------------------------------+---------------------------------+--- -------+
608 | :c:data:`PyExc_ArithmeticError` | :exc:`ArithmeticError` | \(1) | 673 | :c:data:`PyExc_ArithmeticError` | :exc:`ArithmeticError` | \( 1) |
609 +-------------------------------------+----------------------------+----------+ 674 +-----------------------------------------+---------------------------------+--- -------+
610 | :c:data:`PyExc_LookupError` | :exc:`LookupError` | \(1) | 675 | :c:data:`PyExc_LookupError` | :exc:`LookupError` | \( 1) |
611 +-------------------------------------+----------------------------+----------+ 676 +-----------------------------------------+---------------------------------+--- -------+
612 | :c:data:`PyExc_AssertionError` | :exc:`AssertionError` | | 677 | :c:data:`PyExc_AssertionError` | :exc:`AssertionError` | |
613 +-------------------------------------+----------------------------+----------+ 678 +-----------------------------------------+---------------------------------+--- -------+
614 | :c:data:`PyExc_AttributeError` | :exc:`AttributeError` | | 679 | :c:data:`PyExc_AttributeError` | :exc:`AttributeError` | |
615 +-------------------------------------+----------------------------+----------+ 680 +-----------------------------------------+---------------------------------+--- -------+
616 | :c:data:`PyExc_EOFError` | :exc:`EOFError` | | 681 | :c:data:`PyExc_BlockingIOError` | :exc:`BlockingIOError` | |
617 +-------------------------------------+----------------------------+----------+ 682 +-----------------------------------------+---------------------------------+--- -------+
618 | :c:data:`PyExc_EnvironmentError` | :exc:`EnvironmentError` | \(1) | 683 | :c:data:`PyExc_BrokenPipeError` | :exc:`BrokenPipeError` | |
619 +-------------------------------------+----------------------------+----------+ 684 +-----------------------------------------+---------------------------------+--- -------+
620 | :c:data:`PyExc_FloatingPointError` | :exc:`FloatingPointError` | | 685 | :c:data:`PyExc_ChildProcessError` | :exc:`ChildProcessError` | |
621 +-------------------------------------+----------------------------+----------+ 686 +-----------------------------------------+---------------------------------+--- -------+
622 | :c:data:`PyExc_IOError` | :exc:`IOError` | | 687 | :c:data:`PyExc_ConnectionError` | :exc:`ConnectionError` | |
623 +-------------------------------------+----------------------------+----------+ 688 +-----------------------------------------+---------------------------------+--- -------+
624 | :c:data:`PyExc_ImportError` | :exc:`ImportError` | | 689 | :c:data:`PyExc_ConnectionAbortedError` | :exc:`ConnectionAbortedError` | |
625 +-------------------------------------+----------------------------+----------+ 690 +-----------------------------------------+---------------------------------+--- -------+
626 | :c:data:`PyExc_IndexError` | :exc:`IndexError` | | 691 | :c:data:`PyExc_ConnectionRefusedError` | :exc:`ConnectionRefusedError` | |
627 +-------------------------------------+----------------------------+----------+ 692 +-----------------------------------------+---------------------------------+--- -------+
628 | :c:data:`PyExc_KeyError` | :exc:`KeyError` | | 693 | :c:data:`PyExc_ConnectionResetError` | :exc:`ConnectionResetError` | |
629 +-------------------------------------+----------------------------+----------+ 694 +-----------------------------------------+---------------------------------+--- -------+
630 | :c:data:`PyExc_KeyboardInterrupt` | :exc:`KeyboardInterrupt` | | 695 | :c:data:`PyExc_FileExistsError` | :exc:`FileExistsError` | |
631 +-------------------------------------+----------------------------+----------+ 696 +-----------------------------------------+---------------------------------+--- -------+
632 | :c:data:`PyExc_MemoryError` | :exc:`MemoryError` | | 697 | :c:data:`PyExc_FileNotFoundError` | :exc:`FileNotFoundError` | |
633 +-------------------------------------+----------------------------+----------+ 698 +-----------------------------------------+---------------------------------+--- -------+
634 | :c:data:`PyExc_NameError` | :exc:`NameError` | | 699 | :c:data:`PyExc_EOFError` | :exc:`EOFError` | |
635 +-------------------------------------+----------------------------+----------+ 700 +-----------------------------------------+---------------------------------+--- -------+
636 | :c:data:`PyExc_NotImplementedError` | :exc:`NotImplementedError` | | 701 | :c:data:`PyExc_FloatingPointError` | :exc:`FloatingPointError` | |
637 +-------------------------------------+----------------------------+----------+ 702 +-----------------------------------------+---------------------------------+--- -------+
638 | :c:data:`PyExc_OSError` | :exc:`OSError` | | 703 | :c:data:`PyExc_ImportError` | :exc:`ImportError` | |
639 +-------------------------------------+----------------------------+----------+ 704 +-----------------------------------------+---------------------------------+--- -------+
640 | :c:data:`PyExc_OverflowError` | :exc:`OverflowError` | | 705 | :c:data:`PyExc_IndexError` | :exc:`IndexError` | |
641 +-------------------------------------+----------------------------+----------+ 706 +-----------------------------------------+---------------------------------+--- -------+
642 | :c:data:`PyExc_ReferenceError` | :exc:`ReferenceError` | \(2) | 707 | :c:data:`PyExc_InterruptedError` | :exc:`InterruptedError` | |
643 +-------------------------------------+----------------------------+----------+ 708 +-----------------------------------------+---------------------------------+--- -------+
644 | :c:data:`PyExc_RuntimeError` | :exc:`RuntimeError` | | 709 | :c:data:`PyExc_IsADirectoryError` | :exc:`IsADirectoryError` | |
645 +-------------------------------------+----------------------------+----------+ 710 +-----------------------------------------+---------------------------------+--- -------+
646 | :c:data:`PyExc_SyntaxError` | :exc:`SyntaxError` | | 711 | :c:data:`PyExc_KeyError` | :exc:`KeyError` | |
647 +-------------------------------------+----------------------------+----------+ 712 +-----------------------------------------+---------------------------------+--- -------+
648 | :c:data:`PyExc_SystemError` | :exc:`SystemError` | | 713 | :c:data:`PyExc_KeyboardInterrupt` | :exc:`KeyboardInterrupt` | |
649 +-------------------------------------+----------------------------+----------+ 714 +-----------------------------------------+---------------------------------+--- -------+
650 | :c:data:`PyExc_SystemExit` | :exc:`SystemExit` | | 715 | :c:data:`PyExc_MemoryError` | :exc:`MemoryError` | |
651 +-------------------------------------+----------------------------+----------+ 716 +-----------------------------------------+---------------------------------+--- -------+
652 | :c:data:`PyExc_TypeError` | :exc:`TypeError` | | 717 | :c:data:`PyExc_NameError` | :exc:`NameError` | |
653 +-------------------------------------+----------------------------+----------+ 718 +-----------------------------------------+---------------------------------+--- -------+
654 | :c:data:`PyExc_ValueError` | :exc:`ValueError` | | 719 | :c:data:`PyExc_NotADirectoryError` | :exc:`NotADirectoryError` | |
655 +-------------------------------------+----------------------------+----------+ 720 +-----------------------------------------+---------------------------------+--- -------+
656 | :c:data:`PyExc_WindowsError` | :exc:`WindowsError` | \(3) | 721 | :c:data:`PyExc_NotImplementedError` | :exc:`NotImplementedError` | |
657 +-------------------------------------+----------------------------+----------+ 722 +-----------------------------------------+---------------------------------+--- -------+
658 | :c:data:`PyExc_ZeroDivisionError` | :exc:`ZeroDivisionError` | | 723 | :c:data:`PyExc_OSError` | :exc:`OSError` | \( 1) |
659 +-------------------------------------+----------------------------+----------+ 724 +-----------------------------------------+---------------------------------+--- -------+
725 | :c:data:`PyExc_OverflowError` | :exc:`OverflowError` | |
726 +-----------------------------------------+---------------------------------+--- -------+
727 | :c:data:`PyExc_PermissionError` | :exc:`PermissionError` | |
728 +-----------------------------------------+---------------------------------+--- -------+
729 | :c:data:`PyExc_ProcessLookupError` | :exc:`ProcessLookupError` | |
730 +-----------------------------------------+---------------------------------+--- -------+
731 | :c:data:`PyExc_ReferenceError` | :exc:`ReferenceError` | \( 2) |
732 +-----------------------------------------+---------------------------------+--- -------+
733 | :c:data:`PyExc_RuntimeError` | :exc:`RuntimeError` | |
734 +-----------------------------------------+---------------------------------+--- -------+
735 | :c:data:`PyExc_SyntaxError` | :exc:`SyntaxError` | |
736 +-----------------------------------------+---------------------------------+--- -------+
737 | :c:data:`PyExc_SystemError` | :exc:`SystemError` | |
738 +-----------------------------------------+---------------------------------+--- -------+
739 | :c:data:`PyExc_TimeoutError` | :exc:`TimeoutError` | |
740 +-----------------------------------------+---------------------------------+--- -------+
741 | :c:data:`PyExc_SystemExit` | :exc:`SystemExit` | |
742 +-----------------------------------------+---------------------------------+--- -------+
743 | :c:data:`PyExc_TypeError` | :exc:`TypeError` | |
744 +-----------------------------------------+---------------------------------+--- -------+
745 | :c:data:`PyExc_ValueError` | :exc:`ValueError` | |
746 +-----------------------------------------+---------------------------------+--- -------+
747 | :c:data:`PyExc_ZeroDivisionError` | :exc:`ZeroDivisionError` | |
748 +-----------------------------------------+---------------------------------+--- -------+
749
750 .. versionadded:: 3.3
751 :c:data:`PyExc_BlockingIOError`, :c:data:`PyExc_BrokenPipeError`,
752 :c:data:`PyExc_ChildProcessError`, :c:data:`PyExc_ConnectionError`,
753 :c:data:`PyExc_ConnectionAbortedError`, :c:data:`PyExc_ConnectionRefusedError `,
754 :c:data:`PyExc_ConnectionResetError`, :c:data:`PyExc_FileExistsError`,
755 :c:data:`PyExc_FileNotFoundError`, :c:data:`PyExc_InterruptedError`,
756 :c:data:`PyExc_IsADirectoryError`, :c:data:`PyExc_NotADirectoryError`,
757 :c:data:`PyExc_PermissionError`, :c:data:`PyExc_ProcessLookupError`
758 and :c:data:`PyExc_TimeoutError` were introduced following :pep:`3151`.
759
760
761 These are compatibility aliases to :c:data:`PyExc_OSError`:
762
763 +-------------------------------------+----------+
764 | C Name | Notes |
765 +=====================================+==========+
766 | :c:data:`PyExc_EnvironmentError` | |
767 +-------------------------------------+----------+
768 | :c:data:`PyExc_IOError` | |
769 +-------------------------------------+----------+
770 | :c:data:`PyExc_WindowsError` | \(3) |
771 +-------------------------------------+----------+
772
773 .. versionchanged:: 3.3
774 These aliases used to be separate exception types.
775
660 776
661 .. index:: 777 .. index::
662 single: PyExc_BaseException 778 single: PyExc_BaseException
663 single: PyExc_Exception 779 single: PyExc_Exception
664 single: PyExc_ArithmeticError 780 single: PyExc_ArithmeticError
665 single: PyExc_LookupError 781 single: PyExc_LookupError
666 single: PyExc_AssertionError 782 single: PyExc_AssertionError
667 single: PyExc_AttributeError 783 single: PyExc_AttributeError
784 single: PyExc_BlockingIOError
785 single: PyExc_BrokenPipeError
786 single: PyExc_ConnectionError
787 single: PyExc_ConnectionAbortedError
788 single: PyExc_ConnectionRefusedError
789 single: PyExc_ConnectionResetError
668 single: PyExc_EOFError 790 single: PyExc_EOFError
669 single: PyExc_EnvironmentError 791 single: PyExc_FileExistsError
792 single: PyExc_FileNotFoundError
670 single: PyExc_FloatingPointError 793 single: PyExc_FloatingPointError
671 single: PyExc_IOError
672 single: PyExc_ImportError 794 single: PyExc_ImportError
673 single: PyExc_IndexError 795 single: PyExc_IndexError
796 single: PyExc_InterruptedError
797 single: PyExc_IsADirectoryError
674 single: PyExc_KeyError 798 single: PyExc_KeyError
675 single: PyExc_KeyboardInterrupt 799 single: PyExc_KeyboardInterrupt
676 single: PyExc_MemoryError 800 single: PyExc_MemoryError
677 single: PyExc_NameError 801 single: PyExc_NameError
802 single: PyExc_NotADirectoryError
678 single: PyExc_NotImplementedError 803 single: PyExc_NotImplementedError
679 single: PyExc_OSError 804 single: PyExc_OSError
680 single: PyExc_OverflowError 805 single: PyExc_OverflowError
806 single: PyExc_PermissionError
807 single: PyExc_ProcessLookupError
681 single: PyExc_ReferenceError 808 single: PyExc_ReferenceError
682 single: PyExc_RuntimeError 809 single: PyExc_RuntimeError
683 single: PyExc_SyntaxError 810 single: PyExc_SyntaxError
684 single: PyExc_SystemError 811 single: PyExc_SystemError
685 single: PyExc_SystemExit 812 single: PyExc_SystemExit
813 single: PyExc_TimeoutError
686 single: PyExc_TypeError 814 single: PyExc_TypeError
687 single: PyExc_ValueError 815 single: PyExc_ValueError
816 single: PyExc_ZeroDivisionError
817 single: PyExc_EnvironmentError
818 single: PyExc_IOError
688 single: PyExc_WindowsError 819 single: PyExc_WindowsError
689 single: PyExc_ZeroDivisionError
690 820
691 Notes: 821 Notes:
692 822
693 (1) 823 (1)
694 This is a base class for other standard exceptions. 824 This is a base class for other standard exceptions.
695 825
696 (2) 826 (2)
697 This is the same as :exc:`weakref.ReferenceError`. 827 This is the same as :exc:`weakref.ReferenceError`.
698 828
699 (3) 829 (3)
700 Only defined on Windows; protect code that uses this by testing that the 830 Only defined on Windows; protect code that uses this by testing that the
701 preprocessor macro ``MS_WINDOWS`` is defined. 831 preprocessor macro ``MS_WINDOWS`` is defined.
LEFTRIGHT
« no previous file | Include/ast.h » ('j') | Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Toggle Comments ('s')

RSS Feeds Recent Issues | This issue
This is Rietveld 894c83f36cb7+