cpython-lru_cache-weakref: Doc/c-api/exceptions.rst annotate

annotate Doc/c-api/exceptions.rst @ 79675:c0a2294de787 2.7

Issue #16199: Backport 2to3 typo fix from 3.2.

author	Chris Jerdonek <chris.jerdonek@gmail.com>
date	Thu, 11 Oct 2012 16:15:46 -0700
parents	74ff71b2f53d
children	4cc94d30926f

rev	line source
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1 .. highlightlang:: c
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	4 .. _exceptionhandling:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	5
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	6 ******************
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	7 Exception Handling
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	8 ******************
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	9
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	10 The functions described in this chapter will let you handle and raise Python
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	11 exceptions. It is important to understand some of the basics of Python
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	12 exception handling. It works somewhat like the Unix :c:data:`errno` variable:
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	13 there is a global indicator (per thread) of the last error that occurred. Most
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	14 functions don't clear this on success, but will set it to indicate the cause of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	15 the error on failure. Most functions also return an error indicator, usually
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	16 NULL if they are supposed to return a pointer, or ``-1`` if they return an
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	17 integer (exception: the :c:func:`PyArg_\*` functions return ``1`` for success and
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	18 ``0`` for failure).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	19
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	20 When a function must fail because some function it called failed, it generally
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	21 doesn't set the error indicator; the function it called already set it. It is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	22 responsible for either handling the error and clearing the exception or
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	23 returning after cleaning up any resources it holds (such as object references or
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	24 memory allocations); it should not continue normally if it is not prepared to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	25 handle the error. If returning due to an error, it is important to indicate to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	26 the caller that an error has been set. If the error is not handled or carefully
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	27 propagated, additional calls into the Python/C API may not behave as intended
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	28 and may fail in mysterious ways.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	29
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	30 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	31 single: exc_type (in module sys)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	32 single: exc_value (in module sys)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	33 single: exc_traceback (in module sys)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	34
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	35 The error indicator consists of three Python objects corresponding to the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	36 Python variables ``sys.exc_type``, ``sys.exc_value`` and ``sys.exc_traceback``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	37 API functions exist to interact with the error indicator in various ways. There
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	38 is a separate error indicator for each thread.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	39
44383 3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 44355 diff changeset	40 .. XXX Order of these should be more thoughtful.
3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 44355 diff changeset	41 Either alphabetical or some kind of structure.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	42
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	43
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	44 .. c:function:: void PyErr_PrintEx(int set_sys_last_vars)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	45
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	46 Print a standard traceback to ``sys.stderr`` and clear the error indicator.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	47 Call this function only when the error indicator is set. (Otherwise it will
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	48 cause a fatal error!)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	49
51809 a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50424 diff changeset	50 If set_sys_last_vars is nonzero, the variables :data:`sys.last_type`,
a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50424 diff changeset	51 :data:`sys.last_value` and :data:`sys.last_traceback` will be set to the
a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50424 diff changeset	52 type, value and traceback of the printed exception, respectively.
a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50424 diff changeset	53
a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50424 diff changeset	54
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	55 .. c:function:: void PyErr_Print()
51809 a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50424 diff changeset	56
a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50424 diff changeset	57 Alias for ``PyErr_PrintEx(1)``.
a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50424 diff changeset	58
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	59
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	60 .. c:function:: PyObject* PyErr_Occurred()
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	61
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	62 Test whether the error indicator is set. If set, return the exception type
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	63 (the first argument to the last call to one of the :c:func:`PyErr_Set\*`
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	64 functions or to :c:func:`PyErr_Restore`). If not set, return NULL. You do not
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	65 own a reference to the return value, so you do not need to :c:func:`Py_DECREF`
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	66 it.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	67
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	68 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	69
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	70 Do not compare the return value to a specific exception; use
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	71 :c:func:`PyErr_ExceptionMatches` instead, shown below. (The comparison could
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	72 easily fail since the exception may be an instance instead of a class, in the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	73 case of a class exception, or it may the a subclass of the expected exception.)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	74
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	75
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	76 .. c:function:: int PyErr_ExceptionMatches(PyObject *exc)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	77
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	78 Equivalent to ``PyErr_GivenExceptionMatches(PyErr_Occurred(), exc)``. This
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	79 should only be called when an exception is actually set; a memory access
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	80 violation will occur if no exception has been raised.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	81
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	82
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	83 .. c:function:: int PyErr_GivenExceptionMatches(PyObject given, PyObject exc)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	84
50424 df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from Georg Brandl <georg@python.org> parents: 46572 diff changeset	85 Return true if the given exception matches the exception in exc. If
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from Georg Brandl <georg@python.org> parents: 46572 diff changeset	86 exc is a class object, this also returns true when given is an instance
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from Georg Brandl <georg@python.org> parents: 46572 diff changeset	87 of a subclass. If exc is a tuple, all exceptions in the tuple (and
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from Georg Brandl <georg@python.org> parents: 46572 diff changeset	88 recursively in subtuples) are searched for a match.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	89
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	90
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	91 .. c:function:: void PyErr_NormalizeException(PyObjectexc, PyObjectval, PyObject**tb)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	92
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	93 Under certain circumstances, the values returned by :c:func:`PyErr_Fetch` below
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	94 can be "unnormalized", meaning that ``exc`` is a class object but ``val`` is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	95 not an instance of the same class. This function can be used to instantiate
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	96 the class in that case. If the values are already normalized, nothing happens.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	97 The delayed normalization is implemented to improve performance.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	98
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	99
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	100 .. c:function:: void PyErr_Clear()
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	101
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	102 Clear the error indicator. If the error indicator is not set, there is no
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	103 effect.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	104
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	105
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	106 .. c:function:: void PyErr_Fetch(PyObject ptype, PyObject pvalue, PyObject **ptraceback)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	107
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	108 Retrieve the error indicator into three variables whose addresses are passed.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	109 If the error indicator is not set, set all three variables to NULL. If it is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	110 set, it will be cleared and you own a reference to each object retrieved. The
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	111 value and traceback object may be NULL even when the type object is not.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	112
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	113 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	114
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	115 This function is normally only used by code that needs to handle exceptions or
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	116 by code that needs to save and restore the error indicator temporarily.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	117
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	118
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	119 .. c:function:: void PyErr_Restore(PyObject type, PyObject value, PyObject *traceback)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	120
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	121 Set the error indicator from the three objects. If the error indicator is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	122 already set, it is cleared first. If the objects are NULL, the error
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	123 indicator is cleared. Do not pass a NULL type and non-NULL value or
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	124 traceback. The exception type should be a class. Do not pass an invalid
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	125 exception type or value. (Violating these rules will cause subtle problems
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	126 later.) This call takes away a reference to each object: you must own a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	127 reference to each object before the call and after the call you no longer own
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	128 these references. (If you don't understand this, don't use this function. I
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	129 warned you.)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	130
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	131 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	132
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	133 This function is normally only used by code that needs to save and restore the
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	134 error indicator temporarily; use :c:func:`PyErr_Fetch` to save the current
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	135 exception state.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	136
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	137
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	138 .. c:function:: void PyErr_SetString(PyObject type, const char message)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	139
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	140 This is the most common way to set the error indicator. The first argument
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	141 specifies the exception type; it is normally one of the standard exceptions,
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	142 e.g. :c:data:`PyExc_RuntimeError`. You need not increment its reference count.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	143 The second argument is an error message; it is converted to a string object.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	144
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	145
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	146 .. c:function:: void PyErr_SetObject(PyObject type, PyObject value)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	147
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	148 This function is similar to :c:func:`PyErr_SetString` but lets you specify an
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	149 arbitrary Python object for the "value" of the exception.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	150
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	151
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	152 .. c:function:: PyObject* PyErr_Format(PyObject exception, const char format, ...)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	153
66520 72f0bea05457 Merged revisions 86838 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66467 diff changeset	154 This function sets the error indicator and returns NULL. exception
72f0bea05457 Merged revisions 86838 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66467 diff changeset	155 should be a Python exception class. The format and subsequent
72f0bea05457 Merged revisions 86838 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66467 diff changeset	156 parameters help format the error message; they have the same meaning and
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	157 values as in :c:func:`PyString_FromFormat`.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	158
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	159
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	160 .. c:function:: void PyErr_SetNone(PyObject *type)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	161
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	162 This is a shorthand for ``PyErr_SetObject(type, Py_None)``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	163
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	164
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	165 .. c:function:: int PyErr_BadArgument()
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	166
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	167 This is a shorthand for ``PyErr_SetString(PyExc_TypeError, message)``, where
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	168 message indicates that a built-in operation was invoked with an illegal
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	169 argument. It is mostly for internal use.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	170
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	171
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	172 .. c:function:: PyObject* PyErr_NoMemory()
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	173
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	174 This is a shorthand for ``PyErr_SetNone(PyExc_MemoryError)``; it returns NULL
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	175 so an object allocation function can write ``return PyErr_NoMemory();`` when it
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	176 runs out of memory.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	177
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	178
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	179 .. c:function:: PyObject* PyErr_SetFromErrno(PyObject *type)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	180
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	181 .. index:: single: strerror()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	182
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	183 This is a convenience function to raise an exception when a C library function
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	184 has returned an error and set the C variable :c:data:`errno`. It constructs a
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	185 tuple object whose first item is the integer :c:data:`errno` value and whose
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	186 second item is the corresponding error message (gotten from :c:func:`strerror`),
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	187 and then calls ``PyErr_SetObject(type, object)``. On Unix, when the
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	188 :c:data:`errno` value is :const:`EINTR`, indicating an interrupted system call,
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	189 this calls :c:func:`PyErr_CheckSignals`, and if that set the error indicator,
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	190 leaves it set to that. The function always returns NULL, so a wrapper
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	191 function around a system call can write ``return PyErr_SetFromErrno(type);``
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	192 when the system call returns an error.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	193
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	194
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	195 .. c:function:: PyObject* PyErr_SetFromErrnoWithFilename(PyObject type, const char filename)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	196
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	197 Similar to :c:func:`PyErr_SetFromErrno`, with the additional behavior that if
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	198 filename is not NULL, it is passed to the constructor of type as a third
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	199 parameter. In the case of exceptions such as :exc:`IOError` and :exc:`OSError`,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	200 this is used to define the :attr:`filename` attribute of the exception instance.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	201
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	202
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	203 .. c:function:: PyObject* PyErr_SetFromWindowsErr(int ierr)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	204
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	205 This is a convenience function to raise :exc:`WindowsError`. If called with
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	206 ierr of :c:data:`0`, the error code returned by a call to :c:func:`GetLastError`
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	207 is used instead. It calls the Win32 function :c:func:`FormatMessage` to retrieve
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	208 the Windows description of error code given by ierr or :c:func:`GetLastError`,
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	209 then it constructs a tuple object whose first item is the ierr value and whose
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	210 second item is the corresponding error message (gotten from
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	211 :c:func:`FormatMessage`), and then calls ``PyErr_SetObject(PyExc_WindowsError,
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	212 object)``. This function always returns NULL. Availability: Windows.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	213
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	214
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	215 .. c:function:: PyObject* PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	216
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	217 Similar to :c:func:`PyErr_SetFromWindowsErr`, with an additional parameter
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	218 specifying the exception type to be raised. Availability: Windows.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	219
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	220 .. versionadded:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	221
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	222
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	223 .. c:function:: PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	224
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	225 Similar to :c:func:`PyErr_SetFromWindowsErr`, with the additional behavior that
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	226 if filename is not NULL, it is passed to the constructor of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	227 :exc:`WindowsError` as a third parameter. Availability: Windows.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	228
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	229
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	230 .. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilename(PyObject type, int ierr, char filename)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	231
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	232 Similar to :c:func:`PyErr_SetFromWindowsErrWithFilename`, with an additional
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	233 parameter specifying the exception type to be raised. Availability: Windows.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	234
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	235 .. versionadded:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	236
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	237
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	238 .. c:function:: void PyErr_BadInternalCall()
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	239
56796 47e2c14b1503 Merged revisions 69131,69140-69141,69155 via svnmerge from Georg Brandl <georg@python.org> parents: 51809 diff changeset	240 This is a shorthand for ``PyErr_SetString(PyExc_SystemError, message)``,
47e2c14b1503 Merged revisions 69131,69140-69141,69155 via svnmerge from Georg Brandl <georg@python.org> parents: 51809 diff changeset	241 where message indicates that an internal operation (e.g. a Python/C API
47e2c14b1503 Merged revisions 69131,69140-69141,69155 via svnmerge from Georg Brandl <georg@python.org> parents: 51809 diff changeset	242 function) was invoked with an illegal argument. It is mostly for internal
47e2c14b1503 Merged revisions 69131,69140-69141,69155 via svnmerge from Georg Brandl <georg@python.org> parents: 51809 diff changeset	243 use.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	244
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	245
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	246 .. c:function:: int PyErr_WarnEx(PyObject category, char message, int stacklevel)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	247
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	248 Issue a warning message. The category argument is a warning category (see
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	249 below) or NULL; the message argument is a message string. stacklevel is a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	250 positive number giving a number of stack frames; the warning will be issued from
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	251 the currently executing line of code in that stack frame. A stacklevel of 1
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	252 is the function calling :c:func:`PyErr_WarnEx`, 2 is the function above that,
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	253 and so forth.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	254
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	255 This function normally prints a warning message to sys.stderr; however, it is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	256 also possible that the user has specified that warnings are to be turned into
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	257 errors, and in that case this will raise an exception. It is also possible that
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	258 the function raises an exception because of a problem with the warning machinery
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	259 (the implementation imports the :mod:`warnings` module to do the heavy lifting).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	260 The return value is ``0`` if no exception is raised, or ``-1`` if an exception
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	261 is raised. (It is not possible to determine whether a warning message is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	262 actually printed, nor what the reason is for the exception; this is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	263 intentional.) If an exception is raised, the caller should do its normal
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	264 exception handling (for example, :c:func:`Py_DECREF` owned references and return
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	265 an error value).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	266
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	267 Warning categories must be subclasses of :c:data:`Warning`; the default warning
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	268 category is :c:data:`RuntimeWarning`. The standard Python warning categories are
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	269 available as global variables whose names are ``PyExc_`` followed by the Python
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	270 exception name. These have the type :c:type:`PyObject\*`; they are all class
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	271 objects. Their names are :c:data:`PyExc_Warning`, :c:data:`PyExc_UserWarning`,
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	272 :c:data:`PyExc_UnicodeWarning`, :c:data:`PyExc_DeprecationWarning`,
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	273 :c:data:`PyExc_SyntaxWarning`, :c:data:`PyExc_RuntimeWarning`, and
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	274 :c:data:`PyExc_FutureWarning`. :c:data:`PyExc_Warning` is a subclass of
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	275 :c:data:`PyExc_Exception`; the other warning categories are subclasses of
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	276 :c:data:`PyExc_Warning`.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	277
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	278 For information about warning control, see the documentation for the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	279 :mod:`warnings` module and the :option:`-W` option in the command line
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	280 documentation. There is no C API for warning control.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	281
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	282
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	283 .. c:function:: int PyErr_Warn(PyObject category, char message)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	284
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	285 Issue a warning message. The category argument is a warning category (see
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	286 below) or NULL; the message argument is a message string. The warning will
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	287 appear to be issued from the function calling :c:func:`PyErr_Warn`, equivalent to
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	288 calling :c:func:`PyErr_WarnEx` with a stacklevel of 1.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	289
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	290 Deprecated; use :c:func:`PyErr_WarnEx` instead.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	291
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	292
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	293 .. c:function:: int PyErr_WarnExplicit(PyObject category, const char message, const char filename, int lineno, const char module, PyObject *registry)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	294
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	295 Issue a warning message with explicit control over all warning attributes. This
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	296 is a straightforward wrapper around the Python function
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	297 :func:`warnings.warn_explicit`, see there for more information. The module
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	298 and registry arguments may be set to NULL to get the default effect
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	299 described there.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	300
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	301
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	302 .. c:function:: int PyErr_WarnPy3k(char *message, int stacklevel)
46572 d58ec38e6db1 Added PyErr_WarnPy3k function. (issue 2671) I will be converting current Py3k warnings to the use of this function soon. Benjamin Peterson <benjamin@python.org> parents: 44383 diff changeset	303
d58ec38e6db1 Added PyErr_WarnPy3k function. (issue 2671) I will be converting current Py3k warnings to the use of this function soon. Benjamin Peterson <benjamin@python.org> parents: 44383 diff changeset	304 Issue a :exc:`DeprecationWarning` with the given message and stacklevel
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	305 if the :c:data:`Py_Py3kWarningFlag` flag is enabled.
46572 d58ec38e6db1 Added PyErr_WarnPy3k function. (issue 2671) I will be converting current Py3k warnings to the use of this function soon. Benjamin Peterson <benjamin@python.org> parents: 44383 diff changeset	306
d58ec38e6db1 Added PyErr_WarnPy3k function. (issue 2671) I will be converting current Py3k warnings to the use of this function soon. Benjamin Peterson <benjamin@python.org> parents: 44383 diff changeset	307 .. versionadded:: 2.6
d58ec38e6db1 Added PyErr_WarnPy3k function. (issue 2671) I will be converting current Py3k warnings to the use of this function soon. Benjamin Peterson <benjamin@python.org> parents: 44383 diff changeset	308
d58ec38e6db1 Added PyErr_WarnPy3k function. (issue 2671) I will be converting current Py3k warnings to the use of this function soon. Benjamin Peterson <benjamin@python.org> parents: 44383 diff changeset	309
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	310 .. c:function:: int PyErr_CheckSignals()
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	311
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	312 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	313 module: signal
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	314 single: SIGINT
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	315 single: KeyboardInterrupt (built-in exception)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	316
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	317 This function interacts with Python's signal handling. It checks whether a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	318 signal has been sent to the processes and if so, invokes the corresponding
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	319 signal handler. If the :mod:`signal` module is supported, this can invoke a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	320 signal handler written in Python. In all cases, the default effect for
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	321 :const:`SIGINT` is to raise the :exc:`KeyboardInterrupt` exception. If an
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	322 exception is raised the error indicator is set and the function returns ``-1``;
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	323 otherwise the function returns ``0``. The error indicator may or may not be
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	324 cleared if it was previously set.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	325
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	326
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	327 .. c:function:: void PyErr_SetInterrupt()
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	328
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	329 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	330 single: SIGINT
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	331 single: KeyboardInterrupt (built-in exception)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	332
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	333 This function simulates the effect of a :const:`SIGINT` signal arriving --- the
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	334 next time :c:func:`PyErr_CheckSignals` is called, :exc:`KeyboardInterrupt` will
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	335 be raised. It may be called without holding the interpreter lock.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	336
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	337 .. % XXX This was described as obsolete, but is used in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	338 .. % thread.interrupt_main() (used from IDLE), so it's still needed.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	339
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	340
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	341 .. c:function:: int PySignal_SetWakeupFd(int fd)
44355 b89b0334372b Patch #1583 by Adam Olsen. Guido van Rossum <guido@python.org> parents: 42603 diff changeset	342
b89b0334372b Patch #1583 by Adam Olsen. Guido van Rossum <guido@python.org> parents: 42603 diff changeset	343 This utility function specifies a file descriptor to which a ``'\0'`` byte will
b89b0334372b Patch #1583 by Adam Olsen. Guido van Rossum <guido@python.org> parents: 42603 diff changeset	344 be written whenever a signal is received. It returns the previous such file
b89b0334372b Patch #1583 by Adam Olsen. Guido van Rossum <guido@python.org> parents: 42603 diff changeset	345 descriptor. The value ``-1`` disables the feature; this is the initial state.
b89b0334372b Patch #1583 by Adam Olsen. Guido van Rossum <guido@python.org> parents: 42603 diff changeset	346 This is equivalent to :func:`signal.set_wakeup_fd` in Python, but without any
b89b0334372b Patch #1583 by Adam Olsen. Guido van Rossum <guido@python.org> parents: 42603 diff changeset	347 error checking. fd should be a valid file descriptor. The function should
b89b0334372b Patch #1583 by Adam Olsen. Guido van Rossum <guido@python.org> parents: 42603 diff changeset	348 only be called from the main thread.
b89b0334372b Patch #1583 by Adam Olsen. Guido van Rossum <guido@python.org> parents: 42603 diff changeset	349
69427 ebd080593351 Issue #11768: signal.set_wakeup_fd() and PySignal_SetWakeupFd() added in 2.6 Victor Stinner <victor.stinner@haypocalc.com> parents: 68256 diff changeset	350 .. versionadded:: 2.6
ebd080593351 Issue #11768: signal.set_wakeup_fd() and PySignal_SetWakeupFd() added in 2.6 Victor Stinner <victor.stinner@haypocalc.com> parents: 68256 diff changeset	351
44355 b89b0334372b Patch #1583 by Adam Olsen. Guido van Rossum <guido@python.org> parents: 42603 diff changeset	352
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	353 .. c:function:: PyObject* PyErr_NewException(char name, PyObject base, PyObject *dict)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	354
71306 488c6b481652 Clarify that PyErr_NewException creates an exception class, not instance. Georg Brandl <georg@python.org> parents: 69427 diff changeset	355 This utility function creates and returns a new exception class. The name
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	356 argument must be the name of the new exception, a C string of the form
71306 488c6b481652 Clarify that PyErr_NewException creates an exception class, not instance. Georg Brandl <georg@python.org> parents: 69427 diff changeset	357 ``module.classname``. The base and dict arguments are normally NULL.
488c6b481652 Clarify that PyErr_NewException creates an exception class, not instance. Georg Brandl <georg@python.org> parents: 69427 diff changeset	358 This creates a class object derived from :exc:`Exception` (accessible in C as
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	359 :c:data:`PyExc_Exception`).
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	360
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	361 The :attr:`__module__` attribute of the new class is set to the first part (up
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	362 to the last dot) of the name argument, and the class name is set to the last
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	363 part (after the last dot). The base argument can be used to specify alternate
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	364 base classes; it can either be only one class or a tuple of classes. The dict
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	365 argument can be used to specify a dictionary of class variables and methods.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	366
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	367
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	368 .. c:function:: PyObject* PyErr_NewExceptionWithDoc(char name, char doc, PyObject base, PyObject dict)
57961 cf39c5e462f9 #7033: add new API function PyErr_NewExceptionWithDoc, for easily giving new exceptions a docstring. Georg Brandl <georg@python.org> parents: 57277 diff changeset	369
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	370 Same as :c:func:`PyErr_NewException`, except that the new exception class can
57961 cf39c5e462f9 #7033: add new API function PyErr_NewExceptionWithDoc, for easily giving new exceptions a docstring. Georg Brandl <georg@python.org> parents: 57277 diff changeset	371 easily be given a docstring: If doc is non-NULL, it will be used as the
cf39c5e462f9 #7033: add new API function PyErr_NewExceptionWithDoc, for easily giving new exceptions a docstring. Georg Brandl <georg@python.org> parents: 57277 diff changeset	372 docstring for the exception class.
cf39c5e462f9 #7033: add new API function PyErr_NewExceptionWithDoc, for easily giving new exceptions a docstring. Georg Brandl <georg@python.org> parents: 57277 diff changeset	373
cf39c5e462f9 #7033: add new API function PyErr_NewExceptionWithDoc, for easily giving new exceptions a docstring. Georg Brandl <georg@python.org> parents: 57277 diff changeset	374 .. versionadded:: 2.7
cf39c5e462f9 #7033: add new API function PyErr_NewExceptionWithDoc, for easily giving new exceptions a docstring. Georg Brandl <georg@python.org> parents: 57277 diff changeset	375
cf39c5e462f9 #7033: add new API function PyErr_NewExceptionWithDoc, for easily giving new exceptions a docstring. Georg Brandl <georg@python.org> parents: 57277 diff changeset	376
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	377 .. c:function:: void PyErr_WriteUnraisable(PyObject *obj)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	378
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	379 This utility function prints a warning message to ``sys.stderr`` when an
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	380 exception has been set but it is impossible for the interpreter to actually
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	381 raise the exception. It is used, for example, when an exception occurs in an
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	382 :meth:`__del__` method.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	383
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	384 The function is called with a single argument obj that identifies the context
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	385 in which the unraisable exception occurred. The repr of obj will be printed in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	386 the warning message.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	387
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	388
66467 7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	389 .. _unicodeexceptions:
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	390
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	391 Unicode Exception Objects
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	392 =========================
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	393
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	394 The following functions are used to create and modify Unicode exceptions from C.
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	395
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	396 .. 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)
66467 7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	397
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	398 Create a :class:`UnicodeDecodeError` object with the attributes encoding,
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	399 object, length, start, end and reason.
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	400
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	401 .. 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)
66467 7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	402
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	403 Create a :class:`UnicodeEncodeError` object with the attributes encoding,
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	404 object, length, start, end and reason.
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	405
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	406 .. c:function:: PyObject* PyUnicodeTranslateError_Create(const Py_UNICODE object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char reason)
66467 7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	407
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	408 Create a :class:`UnicodeTranslateError` object with the attributes object,
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	409 length, start, end and reason.
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	410
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	411 .. c:function:: PyObject* PyUnicodeDecodeError_GetEncoding(PyObject *exc)
66467 7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	412 PyObject* PyUnicodeEncodeError_GetEncoding(PyObject *exc)
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	413
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	414 Return the encoding attribute of the given exception object.
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	415
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	416 .. c:function:: PyObject* PyUnicodeDecodeError_GetObject(PyObject *exc)
66467 7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	417 PyObject* PyUnicodeEncodeError_GetObject(PyObject *exc)
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	418 PyObject* PyUnicodeTranslateError_GetObject(PyObject *exc)
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	419
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	420 Return the object attribute of the given exception object.
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	421
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	422 .. c:function:: int PyUnicodeDecodeError_GetStart(PyObject exc, Py_ssize_t start)
66467 7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	423 int PyUnicodeEncodeError_GetStart(PyObject exc, Py_ssize_t start)
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	424 int PyUnicodeTranslateError_GetStart(PyObject exc, Py_ssize_t start)
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	425
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	426 Get the start attribute of the given exception object and place it into
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	427 \start. start* must not be NULL. Return ``0`` on success, ``-1`` on
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	428 failure.
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	429
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	430 .. c:function:: int PyUnicodeDecodeError_SetStart(PyObject *exc, Py_ssize_t start)
66467 7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	431 int PyUnicodeEncodeError_SetStart(PyObject *exc, Py_ssize_t start)
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	432 int PyUnicodeTranslateError_SetStart(PyObject *exc, Py_ssize_t start)
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	433
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	434 Set the start attribute of the given exception object to start. Return
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	435 ``0`` on success, ``-1`` on failure.
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	436
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	437 .. c:function:: int PyUnicodeDecodeError_GetEnd(PyObject exc, Py_ssize_t end)
66467 7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	438 int PyUnicodeEncodeError_GetEnd(PyObject exc, Py_ssize_t end)
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	439 int PyUnicodeTranslateError_GetEnd(PyObject exc, Py_ssize_t end)
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	440
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	441 Get the end attribute of the given exception object and place it into
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	442 \end. end* must not be NULL. Return ``0`` on success, ``-1`` on
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	443 failure.
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	444
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	445 .. c:function:: int PyUnicodeDecodeError_SetEnd(PyObject *exc, Py_ssize_t end)
66467 7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	446 int PyUnicodeEncodeError_SetEnd(PyObject *exc, Py_ssize_t end)
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	447 int PyUnicodeTranslateError_SetEnd(PyObject *exc, Py_ssize_t end)
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	448
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	449 Set the end attribute of the given exception object to end. Return ``0``
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	450 on success, ``-1`` on failure.
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	451
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	452 .. c:function:: PyObject* PyUnicodeDecodeError_GetReason(PyObject *exc)
66467 7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	453 PyObject* PyUnicodeEncodeError_GetReason(PyObject *exc)
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	454 PyObject* PyUnicodeTranslateError_GetReason(PyObject *exc)
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	455
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	456 Return the reason attribute of the given exception object.
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	457
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	458 .. c:function:: int PyUnicodeDecodeError_SetReason(PyObject exc, const char reason)
66467 7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	459 int PyUnicodeEncodeError_SetReason(PyObject exc, const char reason)
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	460 int PyUnicodeTranslateError_SetReason(PyObject exc, const char reason)
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	461
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	462 Set the reason attribute of the given exception object to reason. Return
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	463 ``0`` on success, ``-1`` on failure.
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	464
7c0eb8d56146 Merged revisions 86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 59528 diff changeset	465
59841 d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from Georg Brandl <georg@python.org> parents: 56796 diff changeset	466 Recursion Control
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from Georg Brandl <georg@python.org> parents: 56796 diff changeset	467 =================
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from Georg Brandl <georg@python.org> parents: 56796 diff changeset	468
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from Georg Brandl <georg@python.org> parents: 56796 diff changeset	469 These two functions provide a way to perform safe recursive calls at the C
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from Georg Brandl <georg@python.org> parents: 56796 diff changeset	470 level, both in the core and in extension modules. They are needed if the
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from Georg Brandl <georg@python.org> parents: 56796 diff changeset	471 recursive code does not necessarily invoke Python code (which tracks its
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from Georg Brandl <georg@python.org> parents: 56796 diff changeset	472 recursion depth automatically).
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from Georg Brandl <georg@python.org> parents: 56796 diff changeset	473
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	474 .. c:function:: int Py_EnterRecursiveCall(char *where)
59841 d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from Georg Brandl <georg@python.org> parents: 56796 diff changeset	475
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from Georg Brandl <georg@python.org> parents: 56796 diff changeset	476 Marks a point where a recursive C-level call is about to be performed.
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from Georg Brandl <georg@python.org> parents: 56796 diff changeset	477
72984 86e3943d0d5b Remove duplication. Ezio Melotti <ezio.melotti@gmail.com> parents: 71306 diff changeset	478 If :const:`USE_STACKCHECK` is defined, this function checks if the OS
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	479 stack overflowed using :c:func:`PyOS_CheckStack`. In this is the case, it
59841 d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from Georg Brandl <georg@python.org> parents: 56796 diff changeset	480 sets a :exc:`MemoryError` and returns a nonzero value.
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from Georg Brandl <georg@python.org> parents: 56796 diff changeset	481
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from Georg Brandl <georg@python.org> parents: 56796 diff changeset	482 The function then checks if the recursion limit is reached. If this is the
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from Georg Brandl <georg@python.org> parents: 56796 diff changeset	483 case, a :exc:`RuntimeError` is set and a nonzero value is returned.
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from Georg Brandl <georg@python.org> parents: 56796 diff changeset	484 Otherwise, zero is returned.
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from Georg Brandl <georg@python.org> parents: 56796 diff changeset	485
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from Georg Brandl <georg@python.org> parents: 56796 diff changeset	486 where should be a string such as ``" in instance check"`` to be
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from Georg Brandl <georg@python.org> parents: 56796 diff changeset	487 concatenated to the :exc:`RuntimeError` message caused by the recursion depth
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from Georg Brandl <georg@python.org> parents: 56796 diff changeset	488 limit.
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from Georg Brandl <georg@python.org> parents: 56796 diff changeset	489
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	490 .. c:function:: void Py_LeaveRecursiveCall()
59841 d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from Georg Brandl <georg@python.org> parents: 56796 diff changeset	491
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	492 Ends a :c:func:`Py_EnterRecursiveCall`. Must be called once for each
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	493 successful invocation of :c:func:`Py_EnterRecursiveCall`.
59841 d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from Georg Brandl <georg@python.org> parents: 56796 diff changeset	494
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from Georg Brandl <georg@python.org> parents: 56796 diff changeset	495
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	496 .. _standardexceptions:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	497
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	498 Standard Exceptions
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	499 ===================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	500
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	501 All standard Python exceptions are available as global variables whose names are
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	502 ``PyExc_`` followed by the Python exception name. These have the type
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	503 :c:type:`PyObject\*`; they are all class objects. For completeness, here are all
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	504 the variables:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	505
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	506 +-------------------------------------+----------------------------+----------+
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	507 \| C Name \| Python Name \| Notes \|
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	508 +=====================================+============================+==========+
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	509 \| :c:data:`PyExc_BaseException` \| :exc:`BaseException` \| (1), (4) \|
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	510 +-------------------------------------+----------------------------+----------+
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	511 \| :c:data:`PyExc_Exception` \| :exc:`Exception` \| \(1) \|
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	512 +-------------------------------------+----------------------------+----------+
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	513 \| :c:data:`PyExc_StandardError` \| :exc:`StandardError` \| \(1) \|
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	514 +-------------------------------------+----------------------------+----------+
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	515 \| :c:data:`PyExc_ArithmeticError` \| :exc:`ArithmeticError` \| \(1) \|
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	516 +-------------------------------------+----------------------------+----------+
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	517 \| :c:data:`PyExc_LookupError` \| :exc:`LookupError` \| \(1) \|
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	518 +-------------------------------------+----------------------------+----------+
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	519 \| :c:data:`PyExc_AssertionError` \| :exc:`AssertionError` \| \|
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	520 +-------------------------------------+----------------------------+----------+
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	521 \| :c:data:`PyExc_AttributeError` \| :exc:`AttributeError` \| \|
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	522 +-------------------------------------+----------------------------+----------+
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	523 \| :c:data:`PyExc_EOFError` \| :exc:`EOFError` \| \|
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	524 +-------------------------------------+----------------------------+----------+
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	525 \| :c:data:`PyExc_EnvironmentError` \| :exc:`EnvironmentError` \| \(1) \|
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	526 +-------------------------------------+----------------------------+----------+
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	527 \| :c:data:`PyExc_FloatingPointError` \| :exc:`FloatingPointError` \| \|
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	528 +-------------------------------------+----------------------------+----------+
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	529 \| :c:data:`PyExc_IOError` \| :exc:`IOError` \| \|
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	530 +-------------------------------------+----------------------------+----------+
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	531 \| :c:data:`PyExc_ImportError` \| :exc:`ImportError` \| \|
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	532 +-------------------------------------+----------------------------+----------+
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	533 \| :c:data:`PyExc_IndexError` \| :exc:`IndexError` \| \|
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	534 +-------------------------------------+----------------------------+----------+
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	535 \| :c:data:`PyExc_KeyError` \| :exc:`KeyError` \| \|
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	536 +-------------------------------------+----------------------------+----------+
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	537 \| :c:data:`PyExc_KeyboardInterrupt` \| :exc:`KeyboardInterrupt` \| \|
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	538 +-------------------------------------+----------------------------+----------+
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	539 \| :c:data:`PyExc_MemoryError` \| :exc:`MemoryError` \| \|
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	540 +-------------------------------------+----------------------------+----------+
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	541 \| :c:data:`PyExc_NameError` \| :exc:`NameError` \| \|
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	542 +-------------------------------------+----------------------------+----------+
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	543 \| :c:data:`PyExc_NotImplementedError` \| :exc:`NotImplementedError` \| \|
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	544 +-------------------------------------+----------------------------+----------+
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	545 \| :c:data:`PyExc_OSError` \| :exc:`OSError` \| \|
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	546 +-------------------------------------+----------------------------+----------+
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	547 \| :c:data:`PyExc_OverflowError` \| :exc:`OverflowError` \| \|
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	548 +-------------------------------------+----------------------------+----------+
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	549 \| :c:data:`PyExc_ReferenceError` \| :exc:`ReferenceError` \| \(2) \|
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	550 +-------------------------------------+----------------------------+----------+
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	551 \| :c:data:`PyExc_RuntimeError` \| :exc:`RuntimeError` \| \|
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	552 +-------------------------------------+----------------------------+----------+
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	553 \| :c:data:`PyExc_SyntaxError` \| :exc:`SyntaxError` \| \|
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	554 +-------------------------------------+----------------------------+----------+
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	555 \| :c:data:`PyExc_SystemError` \| :exc:`SystemError` \| \|
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	556 +-------------------------------------+----------------------------+----------+
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	557 \| :c:data:`PyExc_SystemExit` \| :exc:`SystemExit` \| \|
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	558 +-------------------------------------+----------------------------+----------+
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	559 \| :c:data:`PyExc_TypeError` \| :exc:`TypeError` \| \|
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	560 +-------------------------------------+----------------------------+----------+
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	561 \| :c:data:`PyExc_ValueError` \| :exc:`ValueError` \| \|
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	562 +-------------------------------------+----------------------------+----------+
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	563 \| :c:data:`PyExc_WindowsError` \| :exc:`WindowsError` \| \(3) \|
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	564 +-------------------------------------+----------------------------+----------+
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	565 \| :c:data:`PyExc_ZeroDivisionError` \| :exc:`ZeroDivisionError` \| \|
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 72984 diff changeset	566 +-------------------------------------+----------------------------+----------+
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	567
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	568 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	569 single: PyExc_BaseException
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	570 single: PyExc_Exception
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	571 single: PyExc_StandardError
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	572 single: PyExc_ArithmeticError
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	573 single: PyExc_LookupError
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	574 single: PyExc_AssertionError
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	575 single: PyExc_AttributeError
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	576 single: PyExc_EOFError
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	577 single: PyExc_EnvironmentError
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	578 single: PyExc_FloatingPointError
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	579 single: PyExc_IOError
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	580 single: PyExc_ImportError
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	581 single: PyExc_IndexError
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	582 single: PyExc_KeyError
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	583 single: PyExc_KeyboardInterrupt
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	584 single: PyExc_MemoryError
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	585 single: PyExc_NameError
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	586 single: PyExc_NotImplementedError
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	587 single: PyExc_OSError
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	588 single: PyExc_OverflowError
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	589 single: PyExc_ReferenceError
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	590 single: PyExc_RuntimeError
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	591 single: PyExc_SyntaxError
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	592 single: PyExc_SystemError
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	593 single: PyExc_SystemExit
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	594 single: PyExc_TypeError
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	595 single: PyExc_ValueError
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	596 single: PyExc_WindowsError
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	597 single: PyExc_ZeroDivisionError
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	598
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	599 Notes:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	600
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	601 (1)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	602 This is a base class for other standard exceptions.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	603
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	604 (2)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	605 This is the same as :exc:`weakref.ReferenceError`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	606
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	607 (3)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	608 Only defined on Windows; protect code that uses this by testing that the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	609 preprocessor macro ``MS_WINDOWS`` is defined.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	610
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	611 (4)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	612 .. versionadded:: 2.5
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	613
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	614
68020 78db3d0c6db7 #11317: fix wrong info about string exceptions. Georg Brandl <georg@python.org> parents: 66520 diff changeset	615 String Exceptions
78db3d0c6db7 #11317: fix wrong info about string exceptions. Georg Brandl <georg@python.org> parents: 66520 diff changeset	616 =================
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	617
68020 78db3d0c6db7 #11317: fix wrong info about string exceptions. Georg Brandl <georg@python.org> parents: 66520 diff changeset	618 .. versionchanged:: 2.6
78db3d0c6db7 #11317: fix wrong info about string exceptions. Georg Brandl <georg@python.org> parents: 66520 diff changeset	619 All exceptions to be raised or caught must be derived from :exc:`BaseException`.
78db3d0c6db7 #11317: fix wrong info about string exceptions. Georg Brandl <georg@python.org> parents: 66520 diff changeset	620 Trying to raise a string exception now raises :exc:`TypeError`.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	621

Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/exceptions.rst @ 79675:c0a2294de787 2.7