diff options
Diffstat (limited to 'Doc/api/exceptions.tex')
| -rw-r--r-- | Doc/api/exceptions.tex | 353 |
1 files changed, 353 insertions, 0 deletions
diff --git a/Doc/api/exceptions.tex b/Doc/api/exceptions.tex new file mode 100644 index 0000000..355e6fb --- /dev/null +++ b/Doc/api/exceptions.tex @@ -0,0 +1,353 @@ +\chapter{Exception Handling \label{exceptionHandling}} + +The functions described in this chapter will let you handle and raise Python +exceptions. It is important to understand some of the basics of +Python exception handling. It works somewhat like the +\UNIX{} \cdata{errno} variable: there is a global indicator (per +thread) of the last error that occurred. Most functions don't clear +this on success, but will set it to indicate the cause of the error on +failure. Most functions also return an error indicator, usually +\NULL{} if they are supposed to return a pointer, or \code{-1} if they +return an integer (exception: the \cfunction{PyArg_Parse*()} functions +return \code{1} for success and \code{0} for failure). When a +function must fail because some function it called failed, it +generally doesn't set the error indicator; the function it called +already set it. + +The error indicator consists of three Python objects corresponding to +\withsubitem{(in module sys)}{ + \ttindex{exc_type}\ttindex{exc_value}\ttindex{exc_traceback}} +the Python variables \code{sys.exc_type}, \code{sys.exc_value} and +\code{sys.exc_traceback}. API functions exist to interact with the +error indicator in various ways. There is a separate error indicator +for each thread. + +% XXX Order of these should be more thoughtful. +% Either alphabetical or some kind of structure. + +\begin{cfuncdesc}{void}{PyErr_Print}{} + Print a standard traceback to \code{sys.stderr} and clear the error + indicator. Call this function only when the error indicator is + set. (Otherwise it will cause a fatal error!) +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyErr_Occurred}{} + Test whether the error indicator is set. If set, return the + exception \emph{type} (the first argument to the last call to one of + the \cfunction{PyErr_Set*()} functions or to + \cfunction{PyErr_Restore()}). If not set, return \NULL. You do + not own a reference to the return value, so you do not need to + \cfunction{Py_DECREF()} it. \note{Do not compare the return value + to a specific exception; use \cfunction{PyErr_ExceptionMatches()} + instead, shown below. (The comparison could easily fail since the + exception may be an instance instead of a class, in the case of a + class exception, or it may the a subclass of the expected + exception.)} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyErr_ExceptionMatches}{PyObject *exc} + Equivalent to \samp{PyErr_GivenExceptionMatches(PyErr_Occurred(), + \var{exc})}. This should only be called when an exception is + actually set; a memory access violation will occur if no exception + has been raised. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyErr_GivenExceptionMatches}{PyObject *given, PyObject *exc} + Return true if the \var{given} exception matches the exception in + \var{exc}. If \var{exc} is a class object, this also returns true + when \var{given} is an instance of a subclass. If \var{exc} is a + tuple, all exceptions in the tuple (and recursively in subtuples) + are searched for a match. If \var{given} is \NULL, a memory access + violation will occur. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyErr_NormalizeException}{PyObject**exc, PyObject**val, PyObject**tb} + Under certain circumstances, the values returned by + \cfunction{PyErr_Fetch()} below can be ``unnormalized'', meaning + that \code{*\var{exc}} is a class object but \code{*\var{val}} is + not an instance of the same class. This function can be used to + instantiate the class in that case. If the values are already + normalized, nothing happens. The delayed normalization is + implemented to improve performance. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyErr_Clear}{} + Clear the error indicator. If the error indicator is not set, there + is no effect. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyErr_Fetch}{PyObject **ptype, PyObject **pvalue, + PyObject **ptraceback} + Retrieve the error indicator into three variables whose addresses + are passed. If the error indicator is not set, set all three + variables to \NULL. If it is set, it will be cleared and you own a + reference to each object retrieved. The value and traceback object + may be \NULL{} even when the type object is not. \note{This + function is normally only used by code that needs to handle + exceptions or by code that needs to save and restore the error + indicator temporarily.} +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyErr_Restore}{PyObject *type, PyObject *value, + PyObject *traceback} + Set the error indicator from the three objects. If the error + indicator is already set, it is cleared first. If the objects are + \NULL, the error indicator is cleared. Do not pass a \NULL{} type + and non-\NULL{} value or traceback. The exception type should be a + string or class; if it is a class, the value should be an instance + of that class. Do not pass an invalid exception type or value. + (Violating these rules will cause subtle problems later.) This call + takes away a reference to each object: you must own a reference to + each object before the call and after the call you no longer own + these references. (If you don't understand this, don't use this + function. I warned you.) \note{This function is normally only used + by code that needs to save and restore the error indicator + temporarily.} +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyErr_SetString}{PyObject *type, char *message} + This is the most common way to set the error indicator. The first + argument specifies the exception type; it is normally one of the + standard exceptions, e.g. \cdata{PyExc_RuntimeError}. You need not + increment its reference count. The second argument is an error + message; it is converted to a string object. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyErr_SetObject}{PyObject *type, PyObject *value} + This function is similar to \cfunction{PyErr_SetString()} but lets + you specify an arbitrary Python object for the ``value'' of the + exception. You need not increment its reference count. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyErr_Format}{PyObject *exception, + const char *format, \moreargs} + This function sets the error indicator. \var{exception} should be a + Python exception (string or class, not an instance). \var{format} + should be a string, containing format codes, similar to + \cfunction{printf()}. The \code{width.precision} before a format + code is parsed, but the width part is ignored. + + \begin{tableii}{c|l}{character}{Character}{Meaning} + \lineii{c}{Character, as an \ctype{int} parameter} + \lineii{d}{Number in decimal, as an \ctype{int} parameter} + \lineii{x}{Number in hexadecimal, as an \ctype{int} parameter} + \lineii{x}{A string, as a \ctype{char *} parameter} + \end{tableii} + + An unrecognized format character causes all the rest of the format + string to be copied as-is to the result string, and any extra + arguments discarded. + + A new reference is returned, which is owned by the caller. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyErr_SetNone}{PyObject *type} + This is a shorthand for \samp{PyErr_SetObject(\var{type}, + Py_None)}. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyErr_BadArgument}{} + This is a shorthand for \samp{PyErr_SetString(PyExc_TypeError, + \var{message})}, where \var{message} indicates that a built-in + operation was invoked with an illegal argument. It is mostly for + internal use. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyErr_NoMemory}{} + This is a shorthand for \samp{PyErr_SetNone(PyExc_MemoryError)}; it + returns \NULL{} so an object allocation function can write + \samp{return PyErr_NoMemory();} when it runs out of memory. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyErr_SetFromErrno}{PyObject *type} + This is a convenience function to raise an exception when a C + library function has returned an error and set the C variable + \cdata{errno}. It constructs a tuple object whose first item is the + integer \cdata{errno} value and whose second item is the + corresponding error message (gotten from + \cfunction{strerror()}\ttindex{strerror()}), and then calls + \samp{PyErr_SetObject(\var{type}, \var{object})}. On \UNIX, when + the \cdata{errno} value is \constant{EINTR}, indicating an + interrupted system call, this calls + \cfunction{PyErr_CheckSignals()}, and if that set the error + indicator, leaves it set to that. The function always returns + \NULL, so a wrapper function around a system call can write + \samp{return PyErr_SetFromErrno();} when the system call returns an + error. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyErr_SetFromErrnoWithFilename}{PyObject *type, + char *filename} + Similar to \cfunction{PyErr_SetFromErrno()}, with the additional + behavior that if \var{filename} is not \NULL, it is passed to the + constructor of \var{type} as a third parameter. In the case of + exceptions such as \exception{IOError} and \exception{OSError}, this + is used to define the \member{filename} attribute of the exception + instance. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyErr_BadInternalCall}{} + This is a shorthand for \samp{PyErr_SetString(PyExc_TypeError, + \var{message})}, where \var{message} indicates that an internal + operation (e.g. a Python/C API function) was invoked with an illegal + argument. It is mostly for internal use. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyErr_Warn}{PyObject *category, char *message} + Issue a warning message. The \var{category} argument is a warning + category (see below) or \NULL; the \var{message} argument is a + message string. + + This function normally prints a warning message to \var{sys.stderr}; + however, it is also possible that the user has specified that + warnings are to be turned into errors, and in that case this will + raise an exception. It is also possible that the function raises an + exception because of a problem with the warning machinery (the + implementation imports the \module{warnings} module to do the heavy + lifting). The return value is \code{0} if no exception is raised, + or \code{-1} if an exception is raised. (It is not possible to + determine whether a warning message is actually printed, nor what + the reason is for the exception; this is intentional.) If an + exception is raised, the caller should do its normal exception + handling (for example, \cfunction{Py_DECREF()} owned references and + return an error value). + + Warning categories must be subclasses of \cdata{Warning}; the + default warning category is \cdata{RuntimeWarning}. The standard + Python warning categories are available as global variables whose + names are \samp{PyExc_} followed by the Python exception name. + These have the type \ctype{PyObject*}; they are all class objects. + Their names are \cdata{PyExc_Warning}, \cdata{PyExc_UserWarning}, + \cdata{PyExc_DeprecationWarning}, \cdata{PyExc_SyntaxWarning}, and + \cdata{PyExc_RuntimeWarning}. \cdata{PyExc_Warning} is a subclass + of \cdata{PyExc_Exception}; the other warning categories are + subclasses of \cdata{PyExc_Warning}. + + For information about warning control, see the documentation for the + \module{warnings} module and the \programopt{-W} option in the + command line documentation. There is no C API for warning control. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyErr_WarnExplicit}{PyObject *category, char *message, + char *filename, int lineno, char *module, PyObject *registry} + Issue a warning message with explicit control over all warning + attributes. This is a straightforward wrapper around the Python + function \function{warnings.warn_explicit()}, see there for more + information. The \var{module} and \var{registry} arguments may be + set to \NULL{} to get the default effect described there. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyErr_CheckSignals}{} + This function interacts with Python's signal handling. It checks + whether a signal has been sent to the processes and if so, invokes + the corresponding signal handler. If the + \module{signal}\refbimodindex{signal} module is supported, this can + invoke a signal handler written in Python. In all cases, the + default effect for \constant{SIGINT}\ttindex{SIGINT} is to raise the + \withsubitem{(built-in exception)}{\ttindex{KeyboardInterrupt}} + \exception{KeyboardInterrupt} exception. If an exception is raised + the error indicator is set and the function returns \code{1}; + otherwise the function returns \code{0}. The error indicator may or + may not be cleared if it was previously set. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyErr_SetInterrupt}{} + This function is obsolete. It simulates the effect of a + \constant{SIGINT}\ttindex{SIGINT} signal arriving --- the next time + \cfunction{PyErr_CheckSignals()} is called, + \withsubitem{(built-in exception)}{\ttindex{KeyboardInterrupt}} + \exception{KeyboardInterrupt} will be raised. It may be called + without holding the interpreter lock. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyErr_NewException}{char *name, + PyObject *base, + PyObject *dict} + This utility function creates and returns a new exception object. + The \var{name} argument must be the name of the new exception, a C + string of the form \code{module.class}. The \var{base} and + \var{dict} arguments are normally \NULL. This creates a class + object derived from the root for all exceptions, the built-in name + \exception{Exception} (accessible in C as \cdata{PyExc_Exception}). + The \member{__module__} attribute of the new class is set to the + first part (up to the last dot) of the \var{name} argument, and the + class name is set to the last part (after the last dot). The + \var{base} argument can be used to specify an alternate base class. + The \var{dict} argument can be used to specify a dictionary of class + variables and methods. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyErr_WriteUnraisable}{PyObject *obj} + This utility function prints a warning message to \code{sys.stderr} + when an exception has been set but it is impossible for the + interpreter to actually raise the exception. It is used, for + example, when an exception occurs in an \method{__del__()} method. + + The function is called with a single argument \var{obj} that + identifies where the context in which the unraisable exception + occurred. The repr of \var{obj} will be printed in the warning + message. +\end{cfuncdesc} + +\section{Standard Exceptions \label{standardExceptions}} + +All standard Python exceptions are available as global variables whose +names are \samp{PyExc_} followed by the Python exception name. These +have the type \ctype{PyObject*}; they are all class objects. For +completeness, here are all the variables: + +\begin{tableiii}{l|l|c}{cdata}{C Name}{Python Name}{Notes} + \lineiii{PyExc_Exception}{\exception{Exception}}{(1)} + \lineiii{PyExc_StandardError}{\exception{StandardError}}{(1)} + \lineiii{PyExc_ArithmeticError}{\exception{ArithmeticError}}{(1)} + \lineiii{PyExc_LookupError}{\exception{LookupError}}{(1)} + \lineiii{PyExc_AssertionError}{\exception{AssertionError}}{} + \lineiii{PyExc_AttributeError}{\exception{AttributeError}}{} + \lineiii{PyExc_EOFError}{\exception{EOFError}}{} + \lineiii{PyExc_EnvironmentError}{\exception{EnvironmentError}}{(1)} + \lineiii{PyExc_FloatingPointError}{\exception{FloatingPointError}}{} + \lineiii{PyExc_IOError}{\exception{IOError}}{} + \lineiii{PyExc_ImportError}{\exception{ImportError}}{} + \lineiii{PyExc_IndexError}{\exception{IndexError}}{} + \lineiii{PyExc_KeyError}{\exception{KeyError}}{} + \lineiii{PyExc_KeyboardInterrupt}{\exception{KeyboardInterrupt}}{} + \lineiii{PyExc_MemoryError}{\exception{MemoryError}}{} + \lineiii{PyExc_NameError}{\exception{NameError}}{} + \lineiii{PyExc_NotImplementedError}{\exception{NotImplementedError}}{} + \lineiii{PyExc_OSError}{\exception{OSError}}{} + \lineiii{PyExc_OverflowError}{\exception{OverflowError}}{} + \lineiii{PyExc_ReferenceError}{\exception{ReferenceError}}{(2)} + \lineiii{PyExc_RuntimeError}{\exception{RuntimeError}}{} + \lineiii{PyExc_SyntaxError}{\exception{SyntaxError}}{} + \lineiii{PyExc_SystemError}{\exception{SystemError}}{} + \lineiii{PyExc_SystemExit}{\exception{SystemExit}}{} + \lineiii{PyExc_TypeError}{\exception{TypeError}}{} + \lineiii{PyExc_ValueError}{\exception{ValueError}}{} + \lineiii{PyExc_WindowsError}{\exception{WindowsError}}{(3)} + \lineiii{PyExc_ZeroDivisionError}{\exception{ZeroDivisionError}}{} +\end{tableiii} + +\noindent +Notes: +\begin{description} +\item[(1)] + This is a base class for other standard exceptions. + +\item[(2)] + This is the same as \exception{weakref.ReferenceError}. + +\item[(3)] + Only defined on Windows; protect code that uses this by testing that + the preprocessor macro \code{MS_WINDOWS} is defined. +\end{description} + + +\section{Deprecation of String Exceptions} + +All exceptions built into Python or provided in the standard library +are derived from \exception{Exception}. +\withsubitem{(built-in exception)}{\ttindex{Exception}} + +String exceptions are still supported in the interpreter to allow +existing code to run unmodified, but this will also change in a future +release. |