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

annotate Doc/api/exceptions.tex @ 20737:00a581bdedeb legacy-trunk

When overriding __str__ or __repr__, set the tp_print slot to NULL.

author	Guido van Rossum <guido@python.org>
date	Mon, 29 Oct 2001 14:33:44 +0000
parents	946bebd00132
children	9fecba526936

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
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	11 return an integer (exception: the \cfunction{PyArg_Parse*()} functions
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	12 return \code{1} for success and \code{0} for failure). When a
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	13 function must fail because some function it called failed, it
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	14 generally doesn't set the error indicator; the function it called
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	15 already set it.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	16
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	17 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	18 \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	19 \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	20 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	21 \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	22 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	23 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	24
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	25 % 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	26 % 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	27
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	28 \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	29 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	30 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	31 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	32 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	33
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	34 \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	35 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	36 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	37 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	38 \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	39 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	40 \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	41 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	42 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	43 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	44 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	45 exception.)}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	46 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	47
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	48 \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	49 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	50 \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	51 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	52 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	53 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	54
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	55 \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	56 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	57 \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	58 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	59 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	60 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	61 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	62 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	63
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	64 \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	65 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	66 \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	67 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	68 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	69 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	70 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	71 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	72 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	73
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	74 \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	75 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	76 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	77 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	78
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	79 \begin{cfuncdesc}{void}{PyErr_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	80 PyObject **ptraceback}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	81 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	82 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	83 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	84 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	85 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	86 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	87 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	88 indicator temporarily.}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	89 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	90
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	91 \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	92 PyObject *traceback}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	93 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	94 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	95 \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	96 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	97 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	98 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	99 (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	100 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	101 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	102 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	103 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	104 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	105 temporarily.}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	106 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	107
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	108 \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	109 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	110 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	111 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	112 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	113 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	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_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	117 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	118 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	119 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	120 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	121
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	122 \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	123 const char *format, \moreargs}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	124 This function sets the error indicator. \var{exception} 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	125 Python exception (string or class, not an instance). \var{format}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	126 should be a string, containing format codes, similar to
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	127 \cfunction{printf()}. The \code{width.precision} before a format
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	128 code is parsed, but the width part is ignored.
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{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	131 \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	132 \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	133 \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	134 \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	135 \end{tableii}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	136
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	137 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	138 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	139 arguments discarded.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	140
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	141 A new reference is returned, which is owned by the caller.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	142 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	143
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	144 \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	145 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	146 Py_None)}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	147 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	148
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	149 \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	150 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	151 \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	152 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	153 internal use.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	154 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	155
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	156 \begin{cfuncdesc}{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	157 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	158 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	159 \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	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_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	163 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	164 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	165 \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	166 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	167 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	168 \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	169 \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	170 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	171 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	172 \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	173 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	174 \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	175 \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	176 error.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	177 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	178
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	179 \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	180 char *filename}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	181 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	182 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	183 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	184 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	185 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	186 instance.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	187 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	188
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	189 \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	190 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	191 \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	192 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	193 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	194 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	195
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	196 \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	197 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	198 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	199 message string.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	200
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	201 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	202 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	203 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	204 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	205 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	206 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	207 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	208 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	209 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	210 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	211 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	212 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	213 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	214
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	215 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	216 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	217 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	218 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	219 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	220 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	221 \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	222 \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	223 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	224 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	225
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	226 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	227 \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	228 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	229 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	230
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	231 \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	232 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	233 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	234 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	235 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	236 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	237 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	238 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	239
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	240 \begin{cfuncdesc}{int}{PyErr_CheckSignals}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	241 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	242 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	243 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	244 \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	245 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	246 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	247 \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	248 \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	249 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	250 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	251 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	252 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	253
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	254 \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	255 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	256 \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	257 \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	258 \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	259 \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	260 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	261 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	262
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	263 \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	264 PyObject *base,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	265 PyObject *dict}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	266 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	267 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	268 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	269 \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	270 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	271 \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	272 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	273 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	274 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	275 \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	276 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	277 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	278 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	279
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	280 \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	281 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	282 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	283 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	284 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	285
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	286 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	287 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	288 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	289 message.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	290 \end{cfuncdesc}
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 \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	293
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	294 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	295 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	296 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	297 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	298
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	299 \begin{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	300 \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	301 \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	302 \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	303 \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	304 \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	305 \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	306 \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	307 \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	308 \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	309 \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	310 \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	311 \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	312 \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	313 \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	314 \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	315 \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	316 \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	317 \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	318 \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	319 \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	320 \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	321 \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	322 \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	323 \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	324 \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	325 \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	326 \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	327 \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	328 \end{tableiii}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	329
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	330 \noindent
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	331 Notes:
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	332 \begin{description}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	333 \item[(1)]
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	334 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	335
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	336 \item[(2)]
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	337 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	338
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	339 \item[(3)]
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	340 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	341 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	342 \end{description}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	343
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 \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	346
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	347 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	348 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	349 \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	350
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	351 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	352 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	353 release.

Mercurial > cpython-lru_cache-weakref

annotate Doc/api/exceptions.tex @ 20737:00a581bdedeb legacy-trunk