cpython-lru_cache-weakref: Doc/api/exceptions.tex annotate

annotate Doc/api/exceptions.tex @ 22360:c8a6ea00a9e1 legacy-trunk

restructure a bit to not rely on test case execution ordering add test case for bug #482460

author	Skip Montanaro <skip@pobox.com>
date	Sun, 17 Mar 2002 23:03:42 +0000
parents	73384e13bd2a
children	1c838be6d004 0f1ae37cd8eb

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
73384e13bd2a Clarify that the Python runtime may behave mysteriously when an exception Fred Drake <fdrake@acm.org> parents: 21156 diff changeset	22 carefully propogated, additional calls into the Python/C API may not
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}{PyObjectexc, PyObjectval, 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
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	105 string or class; if it is a class, the value should be an instance
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	106 of that class. Do not pass an invalid exception type or value.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	107 (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	108 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	109 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	110 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	111 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	112 by code that needs to save and restore the error indicator
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	113 temporarily.}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	114 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	115
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	116 \begin{cfuncdesc}{void}{PyErr_SetString}{PyObject type, char message}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	117 This is the most common way to set the error indicator. The first
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	118 argument specifies the exception type; it is normally one of the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	119 standard exceptions, e.g. \cdata{PyExc_RuntimeError}. You need not
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	120 increment its reference count. The second argument is an error
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	121 message; it is converted to a string object.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	122 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	123
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	124 \begin{cfuncdesc}{void}{PyErr_SetObject}{PyObject type, PyObject value}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	125 This function is similar to \cfunction{PyErr_SetString()} but lets
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	126 you specify an arbitrary Python object for the ``value'' of the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	127 exception. You need not increment its reference count.
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}
21156 9fecba526936 PyErr_Format() does not return a new reference; it always returns NULL. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	132 This function sets the error indicator and returns \NULL..
9fecba526936 PyErr_Format() does not return a new reference; it always returns NULL. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	133 \var{exception} should be a Python exception (string or class, not
9fecba526936 PyErr_Format() does not return a new reference; it always returns NULL. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	134 an instance). \var{format} should be a string, containing format
9fecba526936 PyErr_Format() does not return a new reference; it always returns NULL. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	135 codes, similar to \cfunction{printf()}. The \code{width.precision}
9fecba526936 PyErr_Format() does not return a new reference; it always returns NULL. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	136 before a format code is parsed, but the width part is ignored.
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	137
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	138 \begin{tableii}{c\|l}{character}{Character}{Meaning}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	139 \lineii{c}{Character, as an \ctype{int} parameter}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	140 \lineii{d}{Number in decimal, as an \ctype{int} parameter}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	141 \lineii{x}{Number in hexadecimal, as an \ctype{int} parameter}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	142 \lineii{x}{A string, as a \ctype{char *} parameter}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	143 \end{tableii}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	144
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	145 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	146 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	147 arguments discarded.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	148 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	149
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	150 \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	151 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	152 Py_None)}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	153 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	154
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	155 \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	156 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	157 \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	158 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	159 internal use.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	160 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	161
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	162 \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	163 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	164 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	165 \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	166 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	167
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	168 \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	169 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	170 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	171 \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	172 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	173 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	174 \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	175 \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	176 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	177 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	178 \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	179 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	180 \NULL, so a wrapper function around a system call can write
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	181 \samp{return PyErr_SetFromErrno();} when the system call returns an
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	182 error.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	183 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	184
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	185 \begin{cfuncdesc}{PyObject}{PyErr_SetFromErrnoWithFilename}{PyObject type,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	186 char *filename}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	187 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	188 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	189 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	190 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	191 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	192 instance.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	193 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	194
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	195 \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	196 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	197 \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	198 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	199 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	200 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	201
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	202 \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	203 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	204 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	205 message string.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	206
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	207 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	208 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	209 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	210 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	211 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	212 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	213 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	214 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	215 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	216 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	217 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	218 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	219 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	220
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	221 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	222 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	223 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	224 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	225 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	226 Their names are \cdata{PyExc_Warning}, \cdata{PyExc_UserWarning},
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	227 \cdata{PyExc_DeprecationWarning}, \cdata{PyExc_SyntaxWarning}, and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	228 \cdata{PyExc_RuntimeWarning}. \cdata{PyExc_Warning} is a subclass
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	229 of \cdata{PyExc_Exception}; the other warning categories are
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	230 subclasses of \cdata{PyExc_Warning}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	231
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	232 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	233 \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	234 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	235 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	236
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	237 \begin{cfuncdesc}{int}{PyErr_WarnExplicit}{PyObject category, char message,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	238 char filename, int lineno, char module, PyObject *registry}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	239 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	240 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	241 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	242 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	243 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	244 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	245
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	246 \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	247 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	248 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	249 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	250 \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	251 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	252 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	253 \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	254 \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	255 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	256 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	257 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	258 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	259
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	260 \begin{cfuncdesc}{void}{PyErr_SetInterrupt}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	261 This function is obsolete. It simulates the effect of a
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	262 \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	263 \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	264 \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	265 \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	266 without holding the interpreter lock.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	267 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	268
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	269 \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	270 PyObject *base,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	271 PyObject *dict}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	272 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	273 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	274 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	275 \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	276 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	277 \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	278 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	279 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	280 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	281 \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	282 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	283 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	284 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	285
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	286 \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	287 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	288 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	289 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	290 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	291
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	292 The function is called with a single argument \var{obj} that
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	293 identifies where the context in which the unraisable exception
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	294 occurred. The repr of \var{obj} will be printed in the warning
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	295 message.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	296 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	297
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	298 \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	299
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	300 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	301 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	302 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	303 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	304
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	305 \begin{tableiii}{l\|l\|c}{cdata}{C Name}{Python Name}{Notes}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	306 \lineiii{PyExc_Exception}{\exception{Exception}}{(1)}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	307 \lineiii{PyExc_StandardError}{\exception{StandardError}}{(1)}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	308 \lineiii{PyExc_ArithmeticError}{\exception{ArithmeticError}}{(1)}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	309 \lineiii{PyExc_LookupError}{\exception{LookupError}}{(1)}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	310 \lineiii{PyExc_AssertionError}{\exception{AssertionError}}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	311 \lineiii{PyExc_AttributeError}{\exception{AttributeError}}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	312 \lineiii{PyExc_EOFError}{\exception{EOFError}}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	313 \lineiii{PyExc_EnvironmentError}{\exception{EnvironmentError}}{(1)}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	314 \lineiii{PyExc_FloatingPointError}{\exception{FloatingPointError}}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	315 \lineiii{PyExc_IOError}{\exception{IOError}}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	316 \lineiii{PyExc_ImportError}{\exception{ImportError}}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	317 \lineiii{PyExc_IndexError}{\exception{IndexError}}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	318 \lineiii{PyExc_KeyError}{\exception{KeyError}}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	319 \lineiii{PyExc_KeyboardInterrupt}{\exception{KeyboardInterrupt}}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	320 \lineiii{PyExc_MemoryError}{\exception{MemoryError}}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	321 \lineiii{PyExc_NameError}{\exception{NameError}}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	322 \lineiii{PyExc_NotImplementedError}{\exception{NotImplementedError}}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	323 \lineiii{PyExc_OSError}{\exception{OSError}}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	324 \lineiii{PyExc_OverflowError}{\exception{OverflowError}}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	325 \lineiii{PyExc_ReferenceError}{\exception{ReferenceError}}{(2)}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	326 \lineiii{PyExc_RuntimeError}{\exception{RuntimeError}}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	327 \lineiii{PyExc_SyntaxError}{\exception{SyntaxError}}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	328 \lineiii{PyExc_SystemError}{\exception{SystemError}}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	329 \lineiii{PyExc_SystemExit}{\exception{SystemExit}}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	330 \lineiii{PyExc_TypeError}{\exception{TypeError}}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	331 \lineiii{PyExc_ValueError}{\exception{ValueError}}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	332 \lineiii{PyExc_WindowsError}{\exception{WindowsError}}{(3)}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	333 \lineiii{PyExc_ZeroDivisionError}{\exception{ZeroDivisionError}}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	334 \end{tableiii}
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 \noindent
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	337 Notes:
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	338 \begin{description}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	339 \item[(1)]
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	340 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	341
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	342 \item[(2)]
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	343 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	344
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	345 \item[(3)]
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	346 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	347 the preprocessor macro \code{MS_WINDOWS} is defined.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	348 \end{description}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	349
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	350
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	351 \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	352
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	353 All exceptions built into Python or provided in the standard library
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	354 are derived from \exception{Exception}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	355 \withsubitem{(built-in exception)}{\ttindex{Exception}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	356
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	357 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	358 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	359 release.

Mercurial > cpython-lru_cache-weakref

annotate Doc/api/exceptions.tex @ 22360:c8a6ea00a9e1 legacy-trunk