Mercurial > cpython-lru_cache-weakref

annotate Doc/api/exceptions.tex @ 38664:7619216bbc19 2.4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Bug #1502728: Correctly link against librt library on HP-UX. (backport from rev. 46743)
author Georg Brandl <georg@python.org>
date Thu, 08 Jun 2006 12:54:16 +0000
parents c56168fabf8e
children 2f19b981ac24
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1 \chapter{Exception Handling \label{exceptionHandling}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
2
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
3 The functions described in this chapter will let you handle and raise Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
4 exceptions. It is important to understand some of the basics of
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
5 Python exception handling. It works somewhat like the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
6 \UNIX{} \cdata{errno} variable: there is a global indicator (per
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
7 thread) of the last error that occurred. Most functions don't clear
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
8 this on success, but will set it to indicate the cause of the error on
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
9 failure. Most functions also return an error indicator, usually
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
10 \NULL{} if they are supposed to return a pointer, or \code{-1} if they
21160
73384e13bd2a Clarify that the Python runtime may behave mysteriously when an exception
Fred Drake <fdrake@acm.org>
parents: 21156
diff changeset
11 return an integer (exception: the \cfunction{PyArg_*()} functions
73384e13bd2a Clarify that the Python runtime may behave mysteriously when an exception
Fred Drake <fdrake@acm.org>
parents: 21156
diff changeset
12 return \code{1} for success and \code{0} for failure).
73384e13bd2a Clarify that the Python runtime may behave mysteriously when an exception
Fred Drake <fdrake@acm.org>
parents: 21156
diff changeset
13
73384e13bd2a Clarify that the Python runtime may behave mysteriously when an exception
Fred Drake <fdrake@acm.org>
parents: 21156
diff changeset
14 When a function must fail because some function it called failed, it
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
15 generally doesn't set the error indicator; the function it called
21160
73384e13bd2a Clarify that the Python runtime may behave mysteriously when an exception
Fred Drake <fdrake@acm.org>
parents: 21156
diff changeset
16 already set it. It is responsible for either handling the error and
73384e13bd2a Clarify that the Python runtime may behave mysteriously when an exception
Fred Drake <fdrake@acm.org>
parents: 21156
diff changeset
17 clearing the exception or returning after cleaning up any resources it
73384e13bd2a Clarify that the Python runtime may behave mysteriously when an exception
Fred Drake <fdrake@acm.org>
parents: 21156
diff changeset
18 holds (such as object references or memory allocations); it should
73384e13bd2a Clarify that the Python runtime may behave mysteriously when an exception
Fred Drake <fdrake@acm.org>
parents: 21156
diff changeset
19 \emph{not} continue normally if it is not prepared to handle the
73384e13bd2a Clarify that the Python runtime may behave mysteriously when an exception
Fred Drake <fdrake@acm.org>
parents: 21156
diff changeset
20 error. If returning due to an error, it is important to indicate to
73384e13bd2a Clarify that the Python runtime may behave mysteriously when an exception
Fred Drake <fdrake@acm.org>
parents: 21156
diff changeset
21 the caller that an error has been set. If the error is not handled or
26558
701b797bbdc8 Typo: propogate -> propagate
Thomas Heller <theller@ctypes.org>
parents: 25904
diff changeset
22 carefully propagated, additional calls into the Python/C API may not
21160
73384e13bd2a Clarify that the Python runtime may behave mysteriously when an exception
Fred Drake <fdrake@acm.org>
parents: 21156
diff changeset
23 behave as intended and may fail in mysterious ways.
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
24
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
25 The error indicator consists of three Python objects corresponding to
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
26 \withsubitem{(in module sys)}{
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
27 \ttindex{exc_type}\ttindex{exc_value}\ttindex{exc_traceback}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
28 the Python variables \code{sys.exc_type}, \code{sys.exc_value} and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
29 \code{sys.exc_traceback}. API functions exist to interact with the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
30 error indicator in various ways. There is a separate error indicator
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
31 for each thread.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
32
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
33 % XXX Order of these should be more thoughtful.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
34 % Either alphabetical or some kind of structure.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
35
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
36 \begin{cfuncdesc}{void}{PyErr_Print}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
37 Print a standard traceback to \code{sys.stderr} and clear the error
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
38 indicator. Call this function only when the error indicator is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
39 set. (Otherwise it will cause a fatal error!)
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
40 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
41
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
42 \begin{cfuncdesc}{PyObject*}{PyErr_Occurred}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
43 Test whether the error indicator is set. If set, return the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
44 exception \emph{type} (the first argument to the last call to one of
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
45 the \cfunction{PyErr_Set*()} functions or to
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
46 \cfunction{PyErr_Restore()}). If not set, return \NULL. You do
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
47 not own a reference to the return value, so you do not need to
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
48 \cfunction{Py_DECREF()} it. \note{Do not compare the return value
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
49 to a specific exception; use \cfunction{PyErr_ExceptionMatches()}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
50 instead, shown below. (The comparison could easily fail since the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
51 exception may be an instance instead of a class, in the case of a
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
52 class exception, or it may the a subclass of the expected
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
53 exception.)}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
54 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
55
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
56 \begin{cfuncdesc}{int}{PyErr_ExceptionMatches}{PyObject *exc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
57 Equivalent to \samp{PyErr_GivenExceptionMatches(PyErr_Occurred(),
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
58 \var{exc})}. This should only be called when an exception is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
59 actually set; a memory access violation will occur if no exception
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
60 has been raised.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
61 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
62
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
63 \begin{cfuncdesc}{int}{PyErr_GivenExceptionMatches}{PyObject *given, PyObject *exc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
64 Return true if the \var{given} exception matches the exception in
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
65 \var{exc}. If \var{exc} is a class object, this also returns true
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
66 when \var{given} is an instance of a subclass. If \var{exc} is a
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
67 tuple, all exceptions in the tuple (and recursively in subtuples)
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
68 are searched for a match. If \var{given} is \NULL, a memory access
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
69 violation will occur.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
70 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
71
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
72 \begin{cfuncdesc}{void}{PyErr_NormalizeException}{PyObject**exc, PyObject**val, PyObject**tb}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
73 Under certain circumstances, the values returned by
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
74 \cfunction{PyErr_Fetch()} below can be ``unnormalized'', meaning
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
75 that \code{*\var{exc}} is a class object but \code{*\var{val}} is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
76 not an instance of the same class. This function can be used to
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
77 instantiate the class in that case. If the values are already
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
78 normalized, nothing happens. The delayed normalization is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
79 implemented to improve performance.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
80 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
81
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
82 \begin{cfuncdesc}{void}{PyErr_Clear}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
83 Clear the error indicator. If the error indicator is not set, there
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
84 is no effect.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
85 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
86
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
87 \begin{cfuncdesc}{void}{PyErr_Fetch}{PyObject **ptype, PyObject **pvalue,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
88 PyObject **ptraceback}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
89 Retrieve the error indicator into three variables whose addresses
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
90 are passed. If the error indicator is not set, set all three
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
91 variables to \NULL. If it is set, it will be cleared and you own a
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
92 reference to each object retrieved. The value and traceback object
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
93 may be \NULL{} even when the type object is not. \note{This
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
94 function is normally only used by code that needs to handle
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
95 exceptions or by code that needs to save and restore the error
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
96 indicator temporarily.}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
97 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
98
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
99 \begin{cfuncdesc}{void}{PyErr_Restore}{PyObject *type, PyObject *value,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
100 PyObject *traceback}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
101 Set the error indicator from the three objects. If the error
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
102 indicator is already set, it is cleared first. If the objects are
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
103 \NULL, the error indicator is cleared. Do not pass a \NULL{} type
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
104 and non-\NULL{} value or traceback. The exception type should be a
29302
08a1cbdd0367 SF bug #719367, string exceptions are deprecated
Neal Norwitz <nnorwitz@gmail.com>
parents: 29300
diff changeset
105 class. Do not pass an invalid exception type or value.
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
106 (Violating these rules will cause subtle problems later.) This call
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
107 takes away a reference to each object: you must own a reference to
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
108 each object before the call and after the call you no longer own
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
109 these references. (If you don't understand this, don't use this
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
110 function. I warned you.) \note{This function is normally only used
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
111 by code that needs to save and restore the error indicator
25904
51828ea50b59 Correct the description of PyErr_Restore().
Fred Drake <fdrake@acm.org>
parents: 25411
diff changeset
112 temporarily; use \cfunction{PyErr_Fetch()} to save the current
51828ea50b59 Correct the description of PyErr_Restore().
Fred Drake <fdrake@acm.org>
parents: 25411
diff changeset
113 exception state.}
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
114 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
115
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
116 \begin{cfuncdesc}{void}{PyErr_SetString}{PyObject *type, char *message}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
117 This is the most common way to set the error indicator. The first
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
118 argument specifies the exception type; it is normally one of the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
119 standard exceptions, e.g. \cdata{PyExc_RuntimeError}. You need not
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
120 increment its reference count. The second argument is an error
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
121 message; it is converted to a string object.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
122 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
123
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
124 \begin{cfuncdesc}{void}{PyErr_SetObject}{PyObject *type, PyObject *value}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
125 This function is similar to \cfunction{PyErr_SetString()} but lets
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
126 you specify an arbitrary Python object for the ``value'' of the
25411
d2dbea17fc6f Ok, read the source this time: PyErr_SetObject() does not steal a reference.
Fred Drake <fdrake@acm.org>
parents: 25398
diff changeset
127 exception.
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
128 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
129
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
130 \begin{cfuncdesc}{PyObject*}{PyErr_Format}{PyObject *exception,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
131 const char *format, \moreargs}
29300
732836666000 Typo fix.
Greg Ward <gward@python.net>
parents: 26558
diff changeset
132 This function sets the error indicator and returns \NULL.
29302
08a1cbdd0367 SF bug #719367, string exceptions are deprecated
Neal Norwitz <nnorwitz@gmail.com>
parents: 29300
diff changeset
133 \var{exception} should be a Python exception (class, not
21156
9fecba526936 PyErr_Format() does not return a new reference; it always returns NULL.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
134 an instance). \var{format} should be a string, containing format
9fecba526936 PyErr_Format() does not return a new reference; it always returns NULL.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
135 codes, similar to \cfunction{printf()}. The \code{width.precision}
9fecba526936 PyErr_Format() does not return a new reference; it always returns NULL.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
136 before a format code is parsed, but the width part is ignored.
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
137
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
138 \begin{tableii}{c|l}{character}{Character}{Meaning}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
139 \lineii{c}{Character, as an \ctype{int} parameter}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
140 \lineii{d}{Number in decimal, as an \ctype{int} parameter}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
141 \lineii{x}{Number in hexadecimal, as an \ctype{int} parameter}
22605
da1645fd9c24 fix a typo in PyErr_Format table and add row for 'p' format char
Skip Montanaro <skip@pobox.com>
parents: 22483
diff changeset
142 \lineii{s}{A string, as a \ctype{char *} parameter}
da1645fd9c24 fix a typo in PyErr_Format table and add row for 'p' format char
Skip Montanaro <skip@pobox.com>
parents: 22483
diff changeset
143 \lineii{p}{A hex pointer, as a \ctype{void *} parameter}
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
144 \end{tableii}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
145
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
146 An unrecognized format character causes all the rest of the format
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
147 string to be copied as-is to the result string, and any extra
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
148 arguments discarded.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
149 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
150
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
151 \begin{cfuncdesc}{void}{PyErr_SetNone}{PyObject *type}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
152 This is a shorthand for \samp{PyErr_SetObject(\var{type},
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
153 Py_None)}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
154 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
155
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
156 \begin{cfuncdesc}{int}{PyErr_BadArgument}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
157 This is a shorthand for \samp{PyErr_SetString(PyExc_TypeError,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
158 \var{message})}, where \var{message} indicates that a built-in
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
159 operation was invoked with an illegal argument. It is mostly for
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
160 internal use.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
161 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
162
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
163 \begin{cfuncdesc}{PyObject*}{PyErr_NoMemory}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
164 This is a shorthand for \samp{PyErr_SetNone(PyExc_MemoryError)}; it
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
165 returns \NULL{} so an object allocation function can write
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
166 \samp{return PyErr_NoMemory();} when it runs out of memory.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
167 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
168
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
169 \begin{cfuncdesc}{PyObject*}{PyErr_SetFromErrno}{PyObject *type}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
170 This is a convenience function to raise an exception when a C
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
171 library function has returned an error and set the C variable
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
172 \cdata{errno}. It constructs a tuple object whose first item is the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
173 integer \cdata{errno} value and whose second item is the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
174 corresponding error message (gotten from
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
175 \cfunction{strerror()}\ttindex{strerror()}), and then calls
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
176 \samp{PyErr_SetObject(\var{type}, \var{object})}. On \UNIX, when
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
177 the \cdata{errno} value is \constant{EINTR}, indicating an
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
178 interrupted system call, this calls
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
179 \cfunction{PyErr_CheckSignals()}, and if that set the error
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
180 indicator, leaves it set to that. The function always returns
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
181 \NULL, so a wrapper function around a system call can write
22483
0f1ae37cd8eb Fix example for PyErr_SetFromErrno() (need to pass exception type).
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 21160
diff changeset
182 \samp{return PyErr_SetFromErrno(\var{type});} when the system call
0f1ae37cd8eb Fix example for PyErr_SetFromErrno() (need to pass exception type).
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 21160
diff changeset
183 returns an error.
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
184 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
185
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
186 \begin{cfuncdesc}{PyObject*}{PyErr_SetFromErrnoWithFilename}{PyObject *type,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
187 char *filename}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
188 Similar to \cfunction{PyErr_SetFromErrno()}, with the additional
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
189 behavior that if \var{filename} is not \NULL, it is passed to the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
190 constructor of \var{type} as a third parameter. In the case of
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
191 exceptions such as \exception{IOError} and \exception{OSError}, this
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
192 is used to define the \member{filename} attribute of the exception
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
193 instance.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
194 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
195
24080
15447a5573bd Docs for PyErr_SetFromWindowsErrWithFilename() and
Thomas Heller <theller@ctypes.org>
parents: 22605
diff changeset
196 \begin{cfuncdesc}{PyObject*}{PyErr_SetFromWindowsErr}{int ierr}
24082
e66ced481c77 Minor markup adjustments, consistency changes, and shorten a long
Fred Drake <fdrake@acm.org>
parents: 24080
diff changeset
197 This is a convenience function to raise \exception{WindowsError}.
e66ced481c77 Minor markup adjustments, consistency changes, and shorten a long
Fred Drake <fdrake@acm.org>
parents: 24080
diff changeset
198 If called with \var{ierr} of \cdata{0}, the error code returned by a
e66ced481c77 Minor markup adjustments, consistency changes, and shorten a long
Fred Drake <fdrake@acm.org>
parents: 24080
diff changeset
199 call to \cfunction{GetLastError()} is used instead. It calls the
e66ced481c77 Minor markup adjustments, consistency changes, and shorten a long
Fred Drake <fdrake@acm.org>
parents: 24080
diff changeset
200 Win32 function \cfunction{FormatMessage()} to retrieve the Windows
e66ced481c77 Minor markup adjustments, consistency changes, and shorten a long
Fred Drake <fdrake@acm.org>
parents: 24080
diff changeset
201 description of error code given by \var{ierr} or
e66ced481c77 Minor markup adjustments, consistency changes, and shorten a long
Fred Drake <fdrake@acm.org>
parents: 24080
diff changeset
202 \cfunction{GetLastError()}, then it constructs a tuple object whose
e66ced481c77 Minor markup adjustments, consistency changes, and shorten a long
Fred Drake <fdrake@acm.org>
parents: 24080
diff changeset
203 first item is the \var{ierr} value and whose second item is the
e66ced481c77 Minor markup adjustments, consistency changes, and shorten a long
Fred Drake <fdrake@acm.org>
parents: 24080
diff changeset
204 corresponding error message (gotten from
24080
15447a5573bd Docs for PyErr_SetFromWindowsErrWithFilename() and
Thomas Heller <theller@ctypes.org>
parents: 22605
diff changeset
205 \cfunction{FormatMessage()}), and then calls
15447a5573bd Docs for PyErr_SetFromWindowsErrWithFilename() and
Thomas Heller <theller@ctypes.org>
parents: 22605
diff changeset
206 \samp{PyErr_SetObject(\var{PyExc_WindowsError}, \var{object})}.
24082
e66ced481c77 Minor markup adjustments, consistency changes, and shorten a long
Fred Drake <fdrake@acm.org>
parents: 24080
diff changeset
207 This function always returns \NULL.
e66ced481c77 Minor markup adjustments, consistency changes, and shorten a long
Fred Drake <fdrake@acm.org>
parents: 24080
diff changeset
208 Availability: Windows.
24080
15447a5573bd Docs for PyErr_SetFromWindowsErrWithFilename() and
Thomas Heller <theller@ctypes.org>
parents: 22605
diff changeset
209 \end{cfuncdesc}
15447a5573bd Docs for PyErr_SetFromWindowsErrWithFilename() and
Thomas Heller <theller@ctypes.org>
parents: 22605
diff changeset
210
24423
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
211 \begin{cfuncdesc}{PyObject*}{PyErr_SetExcFromWindowsErr}{PyObject *type,
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
212 int ierr}
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
213 Similar to \cfunction{PyErr_SetFromWindowsErr()}, with an additional
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
214 parameter specifying the exception type to be raised.
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
215 Availability: Windows.
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
216 \versionadded{2.3}
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
217 \end{cfuncdesc}
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
218
24080
15447a5573bd Docs for PyErr_SetFromWindowsErrWithFilename() and
Thomas Heller <theller@ctypes.org>
parents: 22605
diff changeset
219 \begin{cfuncdesc}{PyObject*}{PyErr_SetFromWindowsErrWithFilename}{int ierr,
24082
e66ced481c77 Minor markup adjustments, consistency changes, and shorten a long
Fred Drake <fdrake@acm.org>
parents: 24080
diff changeset
220 char *filename}
24080
15447a5573bd Docs for PyErr_SetFromWindowsErrWithFilename() and
Thomas Heller <theller@ctypes.org>
parents: 22605
diff changeset
221 Similar to \cfunction{PyErr_SetFromWindowsErr()}, with the
15447a5573bd Docs for PyErr_SetFromWindowsErrWithFilename() and
Thomas Heller <theller@ctypes.org>
parents: 22605
diff changeset
222 additional behavior that if \var{filename} is not \NULL, it is
15447a5573bd Docs for PyErr_SetFromWindowsErrWithFilename() and
Thomas Heller <theller@ctypes.org>
parents: 22605
diff changeset
223 passed to the constructor of \exception{WindowsError} as a third
24082
e66ced481c77 Minor markup adjustments, consistency changes, and shorten a long
Fred Drake <fdrake@acm.org>
parents: 24080
diff changeset
224 parameter.
e66ced481c77 Minor markup adjustments, consistency changes, and shorten a long
Fred Drake <fdrake@acm.org>
parents: 24080
diff changeset
225 Availability: Windows.
24080
15447a5573bd Docs for PyErr_SetFromWindowsErrWithFilename() and
Thomas Heller <theller@ctypes.org>
parents: 22605
diff changeset
226 \end{cfuncdesc}
15447a5573bd Docs for PyErr_SetFromWindowsErrWithFilename() and
Thomas Heller <theller@ctypes.org>
parents: 22605
diff changeset
227
24423
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
228 \begin{cfuncdesc}{PyObject*}{PyErr_SetExcFromWindowsErrWithFilename}
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
229 {PyObject *type, int ierr, char *filename}
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
230 Similar to \cfunction{PyErr_SetFromWindowsErrWithFilename()}, with
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
231 an additional parameter specifying the exception type to be raised.
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
232 Availability: Windows.
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
233 \versionadded{2.3}
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
234 \end{cfuncdesc}
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
235
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
236 \begin{cfuncdesc}{void}{PyErr_BadInternalCall}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
237 This is a shorthand for \samp{PyErr_SetString(PyExc_TypeError,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
238 \var{message})}, where \var{message} indicates that an internal
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
239 operation (e.g. a Python/C API function) was invoked with an illegal
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
240 argument. It is mostly for internal use.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
241 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
242
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
243 \begin{cfuncdesc}{int}{PyErr_Warn}{PyObject *category, char *message}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
244 Issue a warning message. The \var{category} argument is a warning
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
245 category (see below) or \NULL; the \var{message} argument is a
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
246 message string.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
247
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
248 This function normally prints a warning message to \var{sys.stderr};
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
249 however, it is also possible that the user has specified that
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
250 warnings are to be turned into errors, and in that case this will
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
251 raise an exception. It is also possible that the function raises an
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
252 exception because of a problem with the warning machinery (the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
253 implementation imports the \module{warnings} module to do the heavy
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
254 lifting). The return value is \code{0} if no exception is raised,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
255 or \code{-1} if an exception is raised. (It is not possible to
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
256 determine whether a warning message is actually printed, nor what
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
257 the reason is for the exception; this is intentional.) If an
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
258 exception is raised, the caller should do its normal exception
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
259 handling (for example, \cfunction{Py_DECREF()} owned references and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
260 return an error value).
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
261
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
262 Warning categories must be subclasses of \cdata{Warning}; the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
263 default warning category is \cdata{RuntimeWarning}. The standard
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
264 Python warning categories are available as global variables whose
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
265 names are \samp{PyExc_} followed by the Python exception name.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
266 These have the type \ctype{PyObject*}; they are all class objects.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
267 Their names are \cdata{PyExc_Warning}, \cdata{PyExc_UserWarning},
24819
4e44fabe0fa0 Document PyExc_FutureWarning
Barry Warsaw <barry@python.org>
parents: 24423
diff changeset
268 \cdata{PyExc_DeprecationWarning}, \cdata{PyExc_SyntaxWarning},
4e44fabe0fa0 Document PyExc_FutureWarning
Barry Warsaw <barry@python.org>
parents: 24423
diff changeset
269 \cdata{PyExc_RuntimeWarning}, and \cdata{PyExc_FutureWarning}.
4e44fabe0fa0 Document PyExc_FutureWarning
Barry Warsaw <barry@python.org>
parents: 24423
diff changeset
270 \cdata{PyExc_Warning} is a subclass of \cdata{PyExc_Exception}; the
4e44fabe0fa0 Document PyExc_FutureWarning
Barry Warsaw <barry@python.org>
parents: 24423
diff changeset
271 other warning categories are subclasses of \cdata{PyExc_Warning}.
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
272
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
273 For information about warning control, see the documentation for the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
274 \module{warnings} module and the \programopt{-W} option in the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
275 command line documentation. There is no C API for warning control.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
276 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
277
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
278 \begin{cfuncdesc}{int}{PyErr_WarnExplicit}{PyObject *category, char *message,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
279 char *filename, int lineno, char *module, PyObject *registry}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
280 Issue a warning message with explicit control over all warning
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
281 attributes. This is a straightforward wrapper around the Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
282 function \function{warnings.warn_explicit()}, see there for more
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
283 information. The \var{module} and \var{registry} arguments may be
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
284 set to \NULL{} to get the default effect described there.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
285 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
286
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
287 \begin{cfuncdesc}{int}{PyErr_CheckSignals}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
288 This function interacts with Python's signal handling. It checks
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
289 whether a signal has been sent to the processes and if so, invokes
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
290 the corresponding signal handler. If the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
291 \module{signal}\refbimodindex{signal} module is supported, this can
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
292 invoke a signal handler written in Python. In all cases, the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
293 default effect for \constant{SIGINT}\ttindex{SIGINT} is to raise the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
294 \withsubitem{(built-in exception)}{\ttindex{KeyboardInterrupt}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
295 \exception{KeyboardInterrupt} exception. If an exception is raised
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
296 the error indicator is set and the function returns \code{1};
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
297 otherwise the function returns \code{0}. The error indicator may or
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
298 may not be cleared if it was previously set.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
299 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
300
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
301 \begin{cfuncdesc}{void}{PyErr_SetInterrupt}{}
32074
d6589c88d23b minor wording cleanup
Fred Drake <fdrake@acm.org>
parents: 31805
diff changeset
302 This function simulates the effect of a
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
303 \constant{SIGINT}\ttindex{SIGINT} signal arriving --- the next time
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
304 \cfunction{PyErr_CheckSignals()} is called,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
305 \withsubitem{(built-in exception)}{\ttindex{KeyboardInterrupt}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
306 \exception{KeyboardInterrupt} will be raised. It may be called
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
307 without holding the interpreter lock.
31805
cebda23aaadb Remove note that PyErr_SetInterrupt() is obsolete; add comment about the
Fred Drake <fdrake@acm.org>
parents: 31147
diff changeset
308 % XXX This was described as obsolete, but is used in
cebda23aaadb Remove note that PyErr_SetInterrupt() is obsolete; add comment about the
Fred Drake <fdrake@acm.org>
parents: 31147
diff changeset
309 % thread.interrupt_main() (used from IDLE), so it's still needed.
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
310 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
311
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
312 \begin{cfuncdesc}{PyObject*}{PyErr_NewException}{char *name,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
313 PyObject *base,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
314 PyObject *dict}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
315 This utility function creates and returns a new exception object.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
316 The \var{name} argument must be the name of the new exception, a C
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
317 string of the form \code{module.class}. The \var{base} and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
318 \var{dict} arguments are normally \NULL. This creates a class
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
319 object derived from the root for all exceptions, the built-in name
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
320 \exception{Exception} (accessible in C as \cdata{PyExc_Exception}).
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
321 The \member{__module__} attribute of the new class is set to the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
322 first part (up to the last dot) of the \var{name} argument, and the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
323 class name is set to the last part (after the last dot). The
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
324 \var{base} argument can be used to specify an alternate base class.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
325 The \var{dict} argument can be used to specify a dictionary of class
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
326 variables and methods.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
327 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
328
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
329 \begin{cfuncdesc}{void}{PyErr_WriteUnraisable}{PyObject *obj}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
330 This utility function prints a warning message to \code{sys.stderr}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
331 when an exception has been set but it is impossible for the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
332 interpreter to actually raise the exception. It is used, for
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
333 example, when an exception occurs in an \method{__del__()} method.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
334
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
335 The function is called with a single argument \var{obj} that
31147
381ae326ee65 SF patch #838938: Typos in the docs (Extending/Embedding + Python/C API)
Raymond Hettinger <python@rcn.com>
parents: 29302
diff changeset
336 identifies the context in which the unraisable exception occurred.
381ae326ee65 SF patch #838938: Typos in the docs (Extending/Embedding + Python/C API)
Raymond Hettinger <python@rcn.com>
parents: 29302
diff changeset
337 The repr of \var{obj} will be printed in the warning message.
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
338 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
339
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
340 \section{Standard Exceptions \label{standardExceptions}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
341
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
342 All standard Python exceptions are available as global variables whose
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
343 names are \samp{PyExc_} followed by the Python exception name. These
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
344 have the type \ctype{PyObject*}; they are all class objects. For
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
345 completeness, here are all the variables:
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
346
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
347 \begin{tableiii}{l|l|c}{cdata}{C Name}{Python Name}{Notes}
32444
c56168fabf8e [Bug #948970] Add PyExc_* symbols to index.
Andrew M. Kuchling <amk@amk.ca>
parents: 32074
diff changeset
348 \lineiii{PyExc_Exception\ttindex{PyExc_Exception}}{\exception{Exception}}{(1)}
c56168fabf8e [Bug #948970] Add PyExc_* symbols to index.
Andrew M. Kuchling <amk@amk.ca>
parents: 32074
diff changeset
349 \lineiii{PyExc_StandardError\ttindex{PyExc_StandardError}}{\exception{StandardError}}{(1)}
c56168fabf8e [Bug #948970] Add PyExc_* symbols to index.
Andrew M. Kuchling <amk@amk.ca>
parents: 32074
diff changeset
350 \lineiii{PyExc_ArithmeticError\ttindex{PyExc_ArithmeticError}}{\exception{ArithmeticError}}{(1)}
c56168fabf8e [Bug #948970] Add PyExc_* symbols to index.
Andrew M. Kuchling <amk@amk.ca>
parents: 32074
diff changeset
351 \lineiii{PyExc_LookupError\ttindex{PyExc_LookupError}}{\exception{LookupError}}{(1)}
c56168fabf8e [Bug #948970] Add PyExc_* symbols to index.
Andrew M. Kuchling <amk@amk.ca>
parents: 32074
diff changeset
352 \lineiii{PyExc_AssertionError\ttindex{PyExc_AssertionError}}{\exception{AssertionError}}{}
c56168fabf8e [Bug #948970] Add PyExc_* symbols to index.
Andrew M. Kuchling <amk@amk.ca>
parents: 32074
diff changeset
353 \lineiii{PyExc_AttributeError\ttindex{PyExc_AttributeError}}{\exception{AttributeError}}{}
c56168fabf8e [Bug #948970] Add PyExc_* symbols to index.
Andrew M. Kuchling <amk@amk.ca>
parents: 32074
diff changeset
354 \lineiii{PyExc_EOFError\ttindex{PyExc_EOFError}}{\exception{EOFError}}{}
c56168fabf8e [Bug #948970] Add PyExc_* symbols to index.
Andrew M. Kuchling <amk@amk.ca>
parents: 32074
diff changeset
355 \lineiii{PyExc_EnvironmentError\ttindex{PyExc_EnvironmentError}}{\exception{EnvironmentError}}{(1)}
c56168fabf8e [Bug #948970] Add PyExc_* symbols to index.
Andrew M. Kuchling <amk@amk.ca>
parents: 32074
diff changeset
356 \lineiii{PyExc_FloatingPointError\ttindex{PyExc_FloatingPointError}}{\exception{FloatingPointError}}{}
c56168fabf8e [Bug #948970] Add PyExc_* symbols to index.
Andrew M. Kuchling <amk@amk.ca>
parents: 32074
diff changeset
357 \lineiii{PyExc_IOError\ttindex{PyExc_IOError}}{\exception{IOError}}{}
c56168fabf8e [Bug #948970] Add PyExc_* symbols to index.
Andrew M. Kuchling <amk@amk.ca>
parents: 32074
diff changeset
358 \lineiii{PyExc_ImportError\ttindex{PyExc_ImportError}}{\exception{ImportError}}{}
c56168fabf8e [Bug #948970] Add PyExc_* symbols to index.
Andrew M. Kuchling <amk@amk.ca>
parents: 32074
diff changeset
359 \lineiii{PyExc_IndexError\ttindex{PyExc_IndexError}}{\exception{IndexError}}{}
c56168fabf8e [Bug #948970] Add PyExc_* symbols to index.
Andrew M. Kuchling <amk@amk.ca>
parents: 32074
diff changeset
360 \lineiii{PyExc_KeyError\ttindex{PyExc_KeyError}}{\exception{KeyError}}{}
c56168fabf8e [Bug #948970] Add PyExc_* symbols to index.
Andrew M. Kuchling <amk@amk.ca>
parents: 32074
diff changeset
361 \lineiii{PyExc_KeyboardInterrupt\ttindex{PyExc_KeyboardInterrupt}}{\exception{KeyboardInterrupt}}{}
c56168fabf8e [Bug #948970] Add PyExc_* symbols to index.
Andrew M. Kuchling <amk@amk.ca>
parents: 32074
diff changeset
362 \lineiii{PyExc_MemoryError\ttindex{PyExc_MemoryError}}{\exception{MemoryError}}{}
c56168fabf8e [Bug #948970] Add PyExc_* symbols to index.
Andrew M. Kuchling <amk@amk.ca>
parents: 32074
diff changeset
363 \lineiii{PyExc_NameError\ttindex{PyExc_NameError}}{\exception{NameError}}{}
c56168fabf8e [Bug #948970] Add PyExc_* symbols to index.
Andrew M. Kuchling <amk@amk.ca>
parents: 32074
diff changeset
364 \lineiii{PyExc_NotImplementedError\ttindex{PyExc_NotImplementedError}}{\exception{NotImplementedError}}{}
c56168fabf8e [Bug #948970] Add PyExc_* symbols to index.
Andrew M. Kuchling <amk@amk.ca>
parents: 32074
diff changeset
365 \lineiii{PyExc_OSError\ttindex{PyExc_OSError}}{\exception{OSError}}{}
c56168fabf8e [Bug #948970] Add PyExc_* symbols to index.
Andrew M. Kuchling <amk@amk.ca>
parents: 32074
diff changeset
366 \lineiii{PyExc_OverflowError\ttindex{PyExc_OverflowError}}{\exception{OverflowError}}{}
c56168fabf8e [Bug #948970] Add PyExc_* symbols to index.
Andrew M. Kuchling <amk@amk.ca>
parents: 32074
diff changeset
367 \lineiii{PyExc_ReferenceError\ttindex{PyExc_ReferenceError}}{\exception{ReferenceError}}{(2)}
c56168fabf8e [Bug #948970] Add PyExc_* symbols to index.
Andrew M. Kuchling <amk@amk.ca>
parents: 32074
diff changeset
368 \lineiii{PyExc_RuntimeError\ttindex{PyExc_RuntimeError}}{\exception{RuntimeError}}{}
c56168fabf8e [Bug #948970] Add PyExc_* symbols to index.
Andrew M. Kuchling <amk@amk.ca>
parents: 32074
diff changeset
369 \lineiii{PyExc_SyntaxError\ttindex{PyExc_SyntaxError}}{\exception{SyntaxError}}{}
c56168fabf8e [Bug #948970] Add PyExc_* symbols to index.
Andrew M. Kuchling <amk@amk.ca>
parents: 32074
diff changeset
370 \lineiii{PyExc_SystemError\ttindex{PyExc_SystemError}}{\exception{SystemError}}{}
c56168fabf8e [Bug #948970] Add PyExc_* symbols to index.
Andrew M. Kuchling <amk@amk.ca>
parents: 32074
diff changeset
371 \lineiii{PyExc_SystemExit\ttindex{PyExc_SystemExit}}{\exception{SystemExit}}{}
c56168fabf8e [Bug #948970] Add PyExc_* symbols to index.
Andrew M. Kuchling <amk@amk.ca>
parents: 32074
diff changeset
372 \lineiii{PyExc_TypeError\ttindex{PyExc_TypeError}}{\exception{TypeError}}{}
c56168fabf8e [Bug #948970] Add PyExc_* symbols to index.
Andrew M. Kuchling <amk@amk.ca>
parents: 32074
diff changeset
373 \lineiii{PyExc_ValueError\ttindex{PyExc_ValueError}}{\exception{ValueError}}{}
c56168fabf8e [Bug #948970] Add PyExc_* symbols to index.
Andrew M. Kuchling <amk@amk.ca>
parents: 32074
diff changeset
374 \lineiii{PyExc_WindowsError\ttindex{PyExc_WindowsError}}{\exception{WindowsError}}{(3)}
c56168fabf8e [Bug #948970] Add PyExc_* symbols to index.
Andrew M. Kuchling <amk@amk.ca>
parents: 32074
diff changeset
375 \lineiii{PyExc_ZeroDivisionError\ttindex{PyExc_ZeroDivisionError}}{\exception{ZeroDivisionError}}{}
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
376 \end{tableiii}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
377
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
378 \noindent
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
379 Notes:
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
380 \begin{description}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
381 \item[(1)]
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
382 This is a base class for other standard exceptions.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
383
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
384 \item[(2)]
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
385 This is the same as \exception{weakref.ReferenceError}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
386
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
387 \item[(3)]
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
388 Only defined on Windows; protect code that uses this by testing that
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
389 the preprocessor macro \code{MS_WINDOWS} is defined.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
390 \end{description}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
391
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
392
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
393 \section{Deprecation of String Exceptions}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
394
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
395 All exceptions built into Python or provided in the standard library
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
396 are derived from \exception{Exception}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
397 \withsubitem{(built-in exception)}{\ttindex{Exception}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
398
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
399 String exceptions are still supported in the interpreter to allow
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
400 existing code to run unmodified, but this will also change in a future
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
401 release.