Mercurial > cpython-lru_cache-weakref

annotate Doc/api/exceptions.tex @ 39496:352ffe77b71d legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Patch #1535500: fix segfault in BZ2File.writelines and make sure it raises the correct exceptions.
author Georg Brandl <georg@python.org>
date Mon, 14 Aug 2006 21:42:55 +0000
parents 635b09b1f542
children 4f8ebacec5f0
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
36754
2f19b981ac24 Make documentation match the implementation.
Martin v. Löwis <martin@v.loewis.de>
parents: 32444
diff changeset
116 \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
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
38173
380dad395599 Teach PyString_FromFormat, PyErr_Format, and PyString_FromFormatV
Tim Peters <tim.peters@gmail.com>
parents: 36781
diff changeset
138 % This should be exactly the same as the table in PyString_FromFormat.
380dad395599 Teach PyString_FromFormat, PyErr_Format, and PyString_FromFormatV
Tim Peters <tim.peters@gmail.com>
parents: 36781
diff changeset
139 % One should just refer to the other.
380dad395599 Teach PyString_FromFormat, PyErr_Format, and PyString_FromFormatV
Tim Peters <tim.peters@gmail.com>
parents: 36781
diff changeset
140
380dad395599 Teach PyString_FromFormat, PyErr_Format, and PyString_FromFormatV
Tim Peters <tim.peters@gmail.com>
parents: 36781
diff changeset
141 % The descriptions for %zd and %zu are wrong, but the truth is complicated
380dad395599 Teach PyString_FromFormat, PyErr_Format, and PyString_FromFormatV
Tim Peters <tim.peters@gmail.com>
parents: 36781
diff changeset
142 % because not all compilers support the %z width modifier -- we fake it
380dad395599 Teach PyString_FromFormat, PyErr_Format, and PyString_FromFormatV
Tim Peters <tim.peters@gmail.com>
parents: 36781
diff changeset
143 % when necessary via interpolating PY_FORMAT_SIZE_T.
380dad395599 Teach PyString_FromFormat, PyErr_Format, and PyString_FromFormatV
Tim Peters <tim.peters@gmail.com>
parents: 36781
diff changeset
144
380dad395599 Teach PyString_FromFormat, PyErr_Format, and PyString_FromFormatV
Tim Peters <tim.peters@gmail.com>
parents: 36781
diff changeset
145 % %u, %lu, %zu should have "new in Python 2.5" blurbs.
380dad395599 Teach PyString_FromFormat, PyErr_Format, and PyString_FromFormatV
Tim Peters <tim.peters@gmail.com>
parents: 36781
diff changeset
146
380dad395599 Teach PyString_FromFormat, PyErr_Format, and PyString_FromFormatV
Tim Peters <tim.peters@gmail.com>
parents: 36781
diff changeset
147 \begin{tableiii}{l|l|l}{member}{Format Characters}{Type}{Comment}
380dad395599 Teach PyString_FromFormat, PyErr_Format, and PyString_FromFormatV
Tim Peters <tim.peters@gmail.com>
parents: 36781
diff changeset
148 \lineiii{\%\%}{\emph{n/a}}{The literal \% character.}
380dad395599 Teach PyString_FromFormat, PyErr_Format, and PyString_FromFormatV
Tim Peters <tim.peters@gmail.com>
parents: 36781
diff changeset
149 \lineiii{\%c}{int}{A single character, represented as an C int.}
380dad395599 Teach PyString_FromFormat, PyErr_Format, and PyString_FromFormatV
Tim Peters <tim.peters@gmail.com>
parents: 36781
diff changeset
150 \lineiii{\%d}{int}{Exactly equivalent to \code{printf("\%d")}.}
380dad395599 Teach PyString_FromFormat, PyErr_Format, and PyString_FromFormatV
Tim Peters <tim.peters@gmail.com>
parents: 36781
diff changeset
151 \lineiii{\%u}{unsigned int}{Exactly equivalent to \code{printf("\%u")}.}
380dad395599 Teach PyString_FromFormat, PyErr_Format, and PyString_FromFormatV
Tim Peters <tim.peters@gmail.com>
parents: 36781
diff changeset
152 \lineiii{\%ld}{long}{Exactly equivalent to \code{printf("\%ld")}.}
380dad395599 Teach PyString_FromFormat, PyErr_Format, and PyString_FromFormatV
Tim Peters <tim.peters@gmail.com>
parents: 36781
diff changeset
153 \lineiii{\%lu}{unsigned long}{Exactly equivalent to \code{printf("\%lu")}.}
380dad395599 Teach PyString_FromFormat, PyErr_Format, and PyString_FromFormatV
Tim Peters <tim.peters@gmail.com>
parents: 36781
diff changeset
154 \lineiii{\%zd}{Py_ssize_t}{Exactly equivalent to \code{printf("\%zd")}.}
38174
ebd573210e25 Typo repair.
Tim Peters <tim.peters@gmail.com>
parents: 38173
diff changeset
155 \lineiii{\%zu}{size_t}{Exactly equivalent to \code{printf("\%zu")}.}
38173
380dad395599 Teach PyString_FromFormat, PyErr_Format, and PyString_FromFormatV
Tim Peters <tim.peters@gmail.com>
parents: 36781
diff changeset
156 \lineiii{\%i}{int}{Exactly equivalent to \code{printf("\%i")}.}
380dad395599 Teach PyString_FromFormat, PyErr_Format, and PyString_FromFormatV
Tim Peters <tim.peters@gmail.com>
parents: 36781
diff changeset
157 \lineiii{\%x}{int}{Exactly equivalent to \code{printf("\%x")}.}
380dad395599 Teach PyString_FromFormat, PyErr_Format, and PyString_FromFormatV
Tim Peters <tim.peters@gmail.com>
parents: 36781
diff changeset
158 \lineiii{\%s}{char*}{A null-terminated C character array.}
380dad395599 Teach PyString_FromFormat, PyErr_Format, and PyString_FromFormatV
Tim Peters <tim.peters@gmail.com>
parents: 36781
diff changeset
159 \lineiii{\%p}{void*}{The hex representation of a C pointer.
380dad395599 Teach PyString_FromFormat, PyErr_Format, and PyString_FromFormatV
Tim Peters <tim.peters@gmail.com>
parents: 36781
diff changeset
160 Mostly equivalent to \code{printf("\%p")} except that it is
380dad395599 Teach PyString_FromFormat, PyErr_Format, and PyString_FromFormatV
Tim Peters <tim.peters@gmail.com>
parents: 36781
diff changeset
161 guaranteed to start with the literal \code{0x} regardless of
380dad395599 Teach PyString_FromFormat, PyErr_Format, and PyString_FromFormatV
Tim Peters <tim.peters@gmail.com>
parents: 36781
diff changeset
162 what the platform's \code{printf} yields.}
380dad395599 Teach PyString_FromFormat, PyErr_Format, and PyString_FromFormatV
Tim Peters <tim.peters@gmail.com>
parents: 36781
diff changeset
163 \end{tableiii}
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
164
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
165 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
166 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
167 arguments discarded.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
168 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
169
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
170 \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
171 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
172 Py_None)}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
173 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
174
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
175 \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
176 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
177 \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
178 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
179 internal use.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
180 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
181
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
182 \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
183 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
184 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
185 \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
186 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
187
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
188 \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
189 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
190 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
191 \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
192 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
193 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
194 \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
195 \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
196 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
197 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
198 \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
199 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
200 \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
201 \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
202 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
203 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
204
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
205 \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
206 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
207 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
208 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
209 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
210 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
211 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
212 instance.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
213 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
214
24080
15447a5573bd Docs for PyErr_SetFromWindowsErrWithFilename() and
Thomas Heller <theller@ctypes.org>
parents: 22605
diff changeset
215 \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
216 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
217 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
218 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
219 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
220 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
221 \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
222 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
223 corresponding error message (gotten from
24080
15447a5573bd Docs for PyErr_SetFromWindowsErrWithFilename() and
Thomas Heller <theller@ctypes.org>
parents: 22605
diff changeset
224 \cfunction{FormatMessage()}), and then calls
15447a5573bd Docs for PyErr_SetFromWindowsErrWithFilename() and
Thomas Heller <theller@ctypes.org>
parents: 22605
diff changeset
225 \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
226 This function always returns \NULL.
e66ced481c77 Minor markup adjustments, consistency changes, and shorten a long
Fred Drake <fdrake@acm.org>
parents: 24080
diff changeset
227 Availability: Windows.
24080
15447a5573bd Docs for PyErr_SetFromWindowsErrWithFilename() and
Thomas Heller <theller@ctypes.org>
parents: 22605
diff changeset
228 \end{cfuncdesc}
15447a5573bd Docs for PyErr_SetFromWindowsErrWithFilename() and
Thomas Heller <theller@ctypes.org>
parents: 22605
diff changeset
229
24423
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
230 \begin{cfuncdesc}{PyObject*}{PyErr_SetExcFromWindowsErr}{PyObject *type,
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
231 int ierr}
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
232 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
233 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
234 Availability: Windows.
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
235 \versionadded{2.3}
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
236 \end{cfuncdesc}
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
237
24080
15447a5573bd Docs for PyErr_SetFromWindowsErrWithFilename() and
Thomas Heller <theller@ctypes.org>
parents: 22605
diff changeset
238 \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
239 const char *filename}
24080
15447a5573bd Docs for PyErr_SetFromWindowsErrWithFilename() and
Thomas Heller <theller@ctypes.org>
parents: 22605
diff changeset
240 Similar to \cfunction{PyErr_SetFromWindowsErr()}, with the
15447a5573bd Docs for PyErr_SetFromWindowsErrWithFilename() and
Thomas Heller <theller@ctypes.org>
parents: 22605
diff changeset
241 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
242 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
243 parameter.
e66ced481c77 Minor markup adjustments, consistency changes, and shorten a long
Fred Drake <fdrake@acm.org>
parents: 24080
diff changeset
244 Availability: Windows.
24080
15447a5573bd Docs for PyErr_SetFromWindowsErrWithFilename() and
Thomas Heller <theller@ctypes.org>
parents: 22605
diff changeset
245 \end{cfuncdesc}
15447a5573bd Docs for PyErr_SetFromWindowsErrWithFilename() and
Thomas Heller <theller@ctypes.org>
parents: 22605
diff changeset
246
24423
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
247 \begin{cfuncdesc}{PyObject*}{PyErr_SetExcFromWindowsErrWithFilename}
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
248 {PyObject *type, int ierr, char *filename}
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
249 Similar to \cfunction{PyErr_SetFromWindowsErrWithFilename()}, with
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
250 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
251 Availability: Windows.
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
252 \versionadded{2.3}
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
253 \end{cfuncdesc}
3db261a93a5b New functions for extension writers on Windows:
Thomas Heller <theller@ctypes.org>
parents: 24082
diff changeset
254
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
255 \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
256 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
257 \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
258 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
259 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
260 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
261
39329
b79b68b82a44 Document PyErr_WarnEx. (Bad Neal! No biscuit!)
Andrew M. Kuchling <amk@amk.ca>
parents: 38396
diff changeset
262 \begin{cfuncdesc}{int}{PyErr_WarnEx}{PyObject *category, char *message, int stacklevel}
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
263 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
264 category (see below) or \NULL; the \var{message} argument is a
39329
b79b68b82a44 Document PyErr_WarnEx. (Bad Neal! No biscuit!)
Andrew M. Kuchling <amk@amk.ca>
parents: 38396
diff changeset
265 message string. \var{stacklevel} is a positive number giving a
b79b68b82a44 Document PyErr_WarnEx. (Bad Neal! No biscuit!)
Andrew M. Kuchling <amk@amk.ca>
parents: 38396
diff changeset
266 number of stack frames; the warning will be issued from the
b79b68b82a44 Document PyErr_WarnEx. (Bad Neal! No biscuit!)
Andrew M. Kuchling <amk@amk.ca>
parents: 38396
diff changeset
267 currently executing line of code in that stack frame. A \var{stacklevel}
b79b68b82a44 Document PyErr_WarnEx. (Bad Neal! No biscuit!)
Andrew M. Kuchling <amk@amk.ca>
parents: 38396
diff changeset
268 of 1 is the function calling \cfunction{PyErr_WarnEx()}, 2 is
b79b68b82a44 Document PyErr_WarnEx. (Bad Neal! No biscuit!)
Andrew M. Kuchling <amk@amk.ca>
parents: 38396
diff changeset
269 the function above that, and so forth.
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
270
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
271 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
272 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
273 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
274 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
275 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
276 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
277 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
278 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
279 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
280 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
281 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
282 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
283 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
284
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
285 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
286 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
287 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
288 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
289 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
290 Their names are \cdata{PyExc_Warning}, \cdata{PyExc_UserWarning},
39487
635b09b1f542 Slightly revised version of patch #1538956:
Marc-André Lemburg <mal@egenix.com>
parents: 39334
diff changeset
291 \cdata{PyExc_UnicodeWarning}, \cdata{PyExc_DeprecationWarning},
635b09b1f542 Slightly revised version of patch #1538956:
Marc-André Lemburg <mal@egenix.com>
parents: 39334
diff changeset
292 \cdata{PyExc_SyntaxWarning}, \cdata{PyExc_RuntimeWarning}, and
635b09b1f542 Slightly revised version of patch #1538956:
Marc-André Lemburg <mal@egenix.com>
parents: 39334
diff changeset
293 \cdata{PyExc_FutureWarning}. \cdata{PyExc_Warning} is a subclass of
635b09b1f542 Slightly revised version of patch #1538956:
Marc-André Lemburg <mal@egenix.com>
parents: 39334
diff changeset
294 \cdata{PyExc_Exception}; the other warning categories are subclasses
635b09b1f542 Slightly revised version of patch #1538956:
Marc-André Lemburg <mal@egenix.com>
parents: 39334
diff changeset
295 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
296
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
297 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
298 \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
299 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
300 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
301
39329
b79b68b82a44 Document PyErr_WarnEx. (Bad Neal! No biscuit!)
Andrew M. Kuchling <amk@amk.ca>
parents: 38396
diff changeset
302 \begin{cfuncdesc}{int}{PyErr_Warn}{PyObject *category, char *message}
b79b68b82a44 Document PyErr_WarnEx. (Bad Neal! No biscuit!)
Andrew M. Kuchling <amk@amk.ca>
parents: 38396
diff changeset
303 Issue a warning message. The \var{category} argument is a warning
b79b68b82a44 Document PyErr_WarnEx. (Bad Neal! No biscuit!)
Andrew M. Kuchling <amk@amk.ca>
parents: 38396
diff changeset
304 category (see below) or \NULL; the \var{message} argument is a
b79b68b82a44 Document PyErr_WarnEx. (Bad Neal! No biscuit!)
Andrew M. Kuchling <amk@amk.ca>
parents: 38396
diff changeset
305 message string. The warning will appear to be issued from the function
b79b68b82a44 Document PyErr_WarnEx. (Bad Neal! No biscuit!)
Andrew M. Kuchling <amk@amk.ca>
parents: 38396
diff changeset
306 calling \cfunction{PyErr_Warn()}, equivalent to calling
39334
4966b17963b4 Fix function name.
Georg Brandl <georg@python.org>
parents: 39329
diff changeset
307 \cfunction{PyErr_WarnEx()} with a \var{stacklevel} of 1.
39329
b79b68b82a44 Document PyErr_WarnEx. (Bad Neal! No biscuit!)
Andrew M. Kuchling <amk@amk.ca>
parents: 38396
diff changeset
308
b79b68b82a44 Document PyErr_WarnEx. (Bad Neal! No biscuit!)
Andrew M. Kuchling <amk@amk.ca>
parents: 38396
diff changeset
309 Deprecated; use \cfunction{PyErr_WarnEx()} instead.
b79b68b82a44 Document PyErr_WarnEx. (Bad Neal! No biscuit!)
Andrew M. Kuchling <amk@amk.ca>
parents: 38396
diff changeset
310 \end{cfuncdesc}
b79b68b82a44 Document PyErr_WarnEx. (Bad Neal! No biscuit!)
Andrew M. Kuchling <amk@amk.ca>
parents: 38396
diff changeset
311
38173
380dad395599 Teach PyString_FromFormat, PyErr_Format, and PyString_FromFormatV
Tim Peters <tim.peters@gmail.com>
parents: 36781
diff changeset
312 \begin{cfuncdesc}{int}{PyErr_WarnExplicit}{PyObject *category,
380dad395599 Teach PyString_FromFormat, PyErr_Format, and PyString_FromFormatV
Tim Peters <tim.peters@gmail.com>
parents: 36781
diff changeset
313 const char *message, const char *filename, int lineno,
36754
2f19b981ac24 Make documentation match the implementation.
Martin v. Löwis <martin@v.loewis.de>
parents: 32444
diff changeset
314 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
315 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
316 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
317 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
318 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
319 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
320 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
321
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
322 \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
323 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
324 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
325 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
326 \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
327 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
328 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
329 \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
330 \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
331 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
332 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
333 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
334 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
335
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
336 \begin{cfuncdesc}{void}{PyErr_SetInterrupt}{}
32074
d6589c88d23b minor wording cleanup
Fred Drake <fdrake@acm.org>
parents: 31805
diff changeset
337 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
338 \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
339 \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
340 \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
341 \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
342 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
343 % 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
344 % 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
345 \end{cfuncdesc}
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{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
348 PyObject *base,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
349 PyObject *dict}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
350 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
351 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
352 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
353 \var{dict} arguments are normally \NULL. This creates a class
38396
df04f192a2a2 Exception isn't the root of all exception classes anymore.
Georg Brandl <georg@python.org>
parents: 38246
diff changeset
354 object derived from \exception{Exception} (accessible in C as
df04f192a2a2 Exception isn't the root of all exception classes anymore.
Georg Brandl <georg@python.org>
parents: 38246
diff changeset
355 \cdata{PyExc_Exception}).
df04f192a2a2 Exception isn't the root of all exception classes anymore.
Georg Brandl <georg@python.org>
parents: 38246
diff changeset
356
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
357 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
358 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
359 class name is set to the last part (after the last dot). The
38246
ee2139935a1d PyErr_NewException now accepts a tuple of base classes as its
Georg Brandl <georg@python.org>
parents: 38174
diff changeset
360 \var{base} argument can be used to specify alternate base classes;
ee2139935a1d PyErr_NewException now accepts a tuple of base classes as its
Georg Brandl <georg@python.org>
parents: 38174
diff changeset
361 it can either be only one class or a tuple of classes.
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
362 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
363 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
364 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
365
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
366 \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
367 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
368 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
369 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
370 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
371
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
372 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
373 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
374 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
375 \end{cfuncdesc}
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 \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
378
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
379 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
380 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
381 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
382 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
383
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
384 \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
385 \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
386 \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
387 \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
388 \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
389 \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
390 \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
391 \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
392 \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
393 \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
394 \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
395 \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
396 \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
397 \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
398 \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
399 \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
400 \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
401 \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
402 \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
403 \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
404 \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
405 \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
406 \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
407 \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
408 \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
409 \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
410 \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
411 \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
412 \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
413 \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
414 \end{tableiii}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
415
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
416 \noindent
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
417 Notes:
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
418 \begin{description}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
419 \item[(1)]
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
420 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
421
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
422 \item[(2)]
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
423 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
424
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
425 \item[(3)]
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
426 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
427 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
428
25f8e6dde4a3 Document PEP 352 changes. Also added GeneratorExit.
Brett Cannon <bcannon@gmail.com>
parents: 36754
diff changeset
429 \item[(4)]
25f8e6dde4a3 Document PEP 352 changes. Also added GeneratorExit.
Brett Cannon <bcannon@gmail.com>
parents: 36754
diff changeset
430 \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
431 \end{description}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
432
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
433
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
434 \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
435
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
436 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
437 are derived from \exception{BaseException}.
25f8e6dde4a3 Document PEP 352 changes. Also added GeneratorExit.
Brett Cannon <bcannon@gmail.com>
parents: 36754
diff changeset
438 \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
439
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
440 String exceptions are still supported in the interpreter to allow
38173
380dad395599 Teach PyString_FromFormat, PyErr_Format, and PyString_FromFormatV
Tim Peters <tim.peters@gmail.com>
parents: 36781
diff changeset
441 existing code to run unmodified, but this will also change in a future
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
442 release.