Mercurial > cpython-lru_cache-weakref

annotate Doc/api/exceptions.tex @ 37850:ebe59cd18273

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Use explicit relative import for an, ehm, relative import.
author Thomas Wouters <thomas@python.org>
date Tue, 18 Apr 2006 21:41:36 +0000
parents 7ada16a14968
children 29ae5e0fc348
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
37042
7ada16a14968 Remove sys.exc_type, sys.exc_value, sys.exc_traceback
Neal Norwitz <nnorwitz@gmail.com>
parents: 36781
diff changeset
26 the result of \code{sys.exc_info()}. API functions exist to interact
7ada16a14968 Remove sys.exc_type, sys.exc_value, sys.exc_traceback
Neal Norwitz <nnorwitz@gmail.com>
parents: 36781
diff changeset
27 with the error indicator in various ways. There is a separate
7ada16a14968 Remove sys.exc_type, sys.exc_value, sys.exc_traceback
Neal Norwitz <nnorwitz@gmail.com>
parents: 36781
diff changeset
28 error indicator for each thread.
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
29
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
30 % 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
31 % 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
32
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
33 \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
34 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
35 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
36 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
37 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
38
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
39 \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
40 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
41 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
42 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
43 \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
44 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
45 \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
46 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
47 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
48 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
49 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
50 exception.)}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
51 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
52
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
53 \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
54 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
55 \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
56 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
57 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
58 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
59
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
60 \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
61 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
62 \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
63 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
64 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
65 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
66 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
67 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
68
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
69 \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
70 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
71 \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
72 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
73 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
74 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
75 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
76 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
77 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
78
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
79 \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
80 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
81 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
82 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
83
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
84 \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
85 PyObject **ptraceback}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
86 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
87 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
88 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
89 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
90 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
91 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
92 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
93 indicator temporarily.}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
94 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
95
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
96 \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
97 PyObject *traceback}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
98 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
99 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
100 \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
101 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
102 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
103 (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
104 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
105 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
106 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
107 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
108 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
109 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
110 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
111 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
112
36754
2f19b981ac24 Make documentation match the implementation.
Martin v. Löwis <martin@v.loewis.de>
parents: 32444
diff changeset
113 \begin{cfuncdesc}{void}{PyErr_SetString}{PyObject *type, const char *message}
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
114 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
115 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
116 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
117 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
118 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
119 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
120
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
121 \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
122 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
123 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
124 exception.
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
125 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
126
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
127 \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
128 const char *format, \moreargs}
29300
732836666000 Typo fix.
Greg Ward <gward@python.net>
parents: 26558
diff changeset
129 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
130 \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
131 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
132 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
133 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
134
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
135 \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
136 \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
137 \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
138 \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
139 \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
140 \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
141 \end{tableii}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
142
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
143 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
144 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
145 arguments discarded.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
146 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
147
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
148 \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
149 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
150 Py_None)}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
151 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
152
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
153 \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
154 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
155 \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
156 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
157 internal use.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
158 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
159
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
160 \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
161 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
162 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
163 \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
164 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
165
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
166 \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
167 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
168 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
169 \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
170 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
171 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
172 \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
173 \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
174 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
175 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
176 \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
177 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
178 \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
179 \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
180 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
181 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
182
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
183 \begin{cfuncdesc}{PyObject*}{PyErr_SetFromErrnoWithFilename}{PyObject *type,
36754
2f19b981ac24 Make documentation match the implementation.
Martin v. Löwis <martin@v.loewis.de>
parents: 32444
diff changeset
184 const char *filename}
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
185 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
186 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
187 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
188 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
189 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
190 instance.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
191 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
192
24080
15447a5573bd Docs for PyErr_SetFromWindowsErrWithFilename() and
Thomas Heller <theller@ctypes.org>
parents: 22605
diff changeset
193 \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
194 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
195 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
196 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
197 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
198 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
199 \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
200 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
201 corresponding error message (gotten from
24080
15447a5573bd Docs for PyErr_SetFromWindowsErrWithFilename() and
Thomas Heller <theller@ctypes.org>
parents: 22605
diff changeset
202 \cfunction{FormatMessage()}), and then calls
15447a5573bd Docs for PyErr_SetFromWindowsErrWithFilename() and
Thomas Heller <theller@ctypes.org>
parents: 22605
diff changeset
203 \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
204 This function always returns \NULL.
e66ced481c77 Minor markup adjustments, consistency changes, and shorten a long
Fred Drake <fdrake@acm.org>
parents: 24080
diff changeset
205 Availability: Windows.
24080
15447a5573bd Docs for PyErr_SetFromWindowsErrWithFilename() and
Thomas Heller <theller@ctypes.org>
parents: 22605
diff changeset
206 \end{cfuncdesc}
15447a5573bd Docs for PyErr_SetFromWindowsErrWithFilename() and
Thomas Heller <theller@ctypes.org>
parents: 22605
diff changeset
207
24423
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
208 \begin{cfuncdesc}{PyObject*}{PyErr_SetExcFromWindowsErr}{PyObject *type,
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
209 int ierr}
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
210 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
211 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
212 Availability: Windows.
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
213 \versionadded{2.3}
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
214 \end{cfuncdesc}
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
215
24080
15447a5573bd Docs for PyErr_SetFromWindowsErrWithFilename() and
Thomas Heller <theller@ctypes.org>
parents: 22605
diff changeset
216 \begin{cfuncdesc}{PyObject*}{PyErr_SetFromWindowsErrWithFilename}{int ierr,
36754
2f19b981ac24 Make documentation match the implementation.
Martin v. Löwis <martin@v.loewis.de>
parents: 32444
diff changeset
217 const char *filename}
24080
15447a5573bd Docs for PyErr_SetFromWindowsErrWithFilename() and
Thomas Heller <theller@ctypes.org>
parents: 22605
diff changeset
218 Similar to \cfunction{PyErr_SetFromWindowsErr()}, with the
15447a5573bd Docs for PyErr_SetFromWindowsErrWithFilename() and
Thomas Heller <theller@ctypes.org>
parents: 22605
diff changeset
219 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
220 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
221 parameter.
e66ced481c77 Minor markup adjustments, consistency changes, and shorten a long
Fred Drake <fdrake@acm.org>
parents: 24080
diff changeset
222 Availability: Windows.
24080
15447a5573bd Docs for PyErr_SetFromWindowsErrWithFilename() and
Thomas Heller <theller@ctypes.org>
parents: 22605
diff changeset
223 \end{cfuncdesc}
15447a5573bd Docs for PyErr_SetFromWindowsErrWithFilename() and
Thomas Heller <theller@ctypes.org>
parents: 22605
diff changeset
224
24423
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
225 \begin{cfuncdesc}{PyObject*}{PyErr_SetExcFromWindowsErrWithFilename}
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
226 {PyObject *type, int ierr, char *filename}
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
227 Similar to \cfunction{PyErr_SetFromWindowsErrWithFilename()}, with
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
228 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
229 Availability: Windows.
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
230 \versionadded{2.3}
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
231 \end{cfuncdesc}
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
232
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
233 \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
234 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
235 \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
236 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
237 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
238 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
239
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
240 \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
241 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
242 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
243 message string.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
244
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
245 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
246 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
247 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
248 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
249 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
250 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
251 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
252 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
253 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
254 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
255 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
256 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
257 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
258
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
259 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
260 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
261 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
262 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
263 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
264 Their names are \cdata{PyExc_Warning}, \cdata{PyExc_UserWarning},
24819
4e44fabe0fa0 Document PyExc_FutureWarning
Barry Warsaw <barry@python.org>
parents: 24423
diff changeset
265 \cdata{PyExc_DeprecationWarning}, \cdata{PyExc_SyntaxWarning},
4e44fabe0fa0 Document PyExc_FutureWarning
Barry Warsaw <barry@python.org>
parents: 24423
diff changeset
266 \cdata{PyExc_RuntimeWarning}, and \cdata{PyExc_FutureWarning}.
4e44fabe0fa0 Document PyExc_FutureWarning
Barry Warsaw <barry@python.org>
parents: 24423
diff changeset
267 \cdata{PyExc_Warning} is a subclass of \cdata{PyExc_Exception}; the
4e44fabe0fa0 Document PyExc_FutureWarning
Barry Warsaw <barry@python.org>
parents: 24423
diff changeset
268 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
269
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
270 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
271 \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
272 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
273 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
274
36754
2f19b981ac24 Make documentation match the implementation.
Martin v. Löwis <martin@v.loewis.de>
parents: 32444
diff changeset
275 \begin{cfuncdesc}{int}{PyErr_WarnExplicit}{PyObject *category,
2f19b981ac24 Make documentation match the implementation.
Martin v. Löwis <martin@v.loewis.de>
parents: 32444
diff changeset
276 const char *message, const char *filename, int lineno,
2f19b981ac24 Make documentation match the implementation.
Martin v. Löwis <martin@v.loewis.de>
parents: 32444
diff changeset
277 const char *module, PyObject *registry}
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
278 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
279 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
280 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
281 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
282 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
283 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
284
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
285 \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
286 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
287 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
288 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
289 \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
290 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
291 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
292 \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
293 \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
294 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
295 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
296 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
297 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
298
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
299 \begin{cfuncdesc}{void}{PyErr_SetInterrupt}{}
32074
d6589c88d23b minor wording cleanup
Fred Drake <fdrake@acm.org>
parents: 31805
diff changeset
300 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
301 \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
302 \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
303 \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
304 \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
305 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
306 % 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
307 % 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
308 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
309
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
310 \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
311 PyObject *base,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
312 PyObject *dict}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
313 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
314 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
315 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
316 \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
317 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
318 \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
319 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
320 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
321 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
322 \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
323 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
324 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
325 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
326
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
327 \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
328 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
329 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
330 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
331 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
332
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
333 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
334 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
335 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
336 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
337
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
338 \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
339
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
340 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
341 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
342 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
343 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
344
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
345 \begin{tableiii}{l|l|c}{cdata}{C Name}{Python Name}{Notes}
36781
25f8e6dde4a3 Document PEP 352 changes. Also added GeneratorExit.
Brett Cannon <bcannon@gmail.com>
parents: 36754
diff changeset
346 \lineiii{PyExc_BaseException\ttindex{PyExc_BaseException}}{\exception{BaseException}}{(1), (4)}
32444
c56168fabf8e [Bug #948970] Add PyExc_* symbols to index.
Andrew M. Kuchling <amk@amk.ca>
parents: 32074
diff changeset
347 \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
348 \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
349 \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
350 \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
351 \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
352 \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
353 \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
354 \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
355 \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
356 \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
357 \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
358 \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
359 \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
360 \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
361 \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
362 \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
363 \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
364 \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
365 \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
366 \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
367 \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
368 \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
369 \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
370 \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
371 \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
372 \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
373 \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
374 \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
375 \end{tableiii}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
376
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
377 \noindent
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
378 Notes:
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
379 \begin{description}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
380 \item[(1)]
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
381 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
382
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
383 \item[(2)]
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
384 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
385
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
386 \item[(3)]
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
387 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
388 the preprocessor macro \code{MS_WINDOWS} is defined.
36781
25f8e6dde4a3 Document PEP 352 changes. Also added GeneratorExit.
Brett Cannon <bcannon@gmail.com>
parents: 36754
diff changeset
389
25f8e6dde4a3 Document PEP 352 changes. Also added GeneratorExit.
Brett Cannon <bcannon@gmail.com>
parents: 36754
diff changeset
390 \item[(4)]
25f8e6dde4a3 Document PEP 352 changes. Also added GeneratorExit.
Brett Cannon <bcannon@gmail.com>
parents: 36754
diff changeset
391 \versionadded{2.5}
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
392 \end{description}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
393
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 \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
396
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
397 All exceptions built into Python or provided in the standard library
36781
25f8e6dde4a3 Document PEP 352 changes. Also added GeneratorExit.
Brett Cannon <bcannon@gmail.com>
parents: 36754
diff changeset
398 are derived from \exception{BaseException}.
25f8e6dde4a3 Document PEP 352 changes. Also added GeneratorExit.
Brett Cannon <bcannon@gmail.com>
parents: 36754
diff changeset
399 \withsubitem{(built-in exception)}{\ttindex{BaseException}}
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
400
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
401 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
402 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
403 release.