Doc/api/exceptions.tex

   1 \chapter{Exception Handling \label{exceptionHandling}}
   2
   3 The functions described in this chapter will let you handle and raise Python
   4 exceptions.  It is important to understand some of the basics of
   5 Python exception handling.  It works somewhat like the
   6 \UNIX{} \cdata{errno} variable: there is a global indicator (per
   7 thread) of the last error that occurred.  Most functions don't clear
   8 this on success, but will set it to indicate the cause of the error on
   9 failure.  Most functions also return an error indicator, usually
  10 \NULL{} if they are supposed to return a pointer, or \code{-1} if they
  11 return an integer (exception: the \cfunction{PyArg_*()} functions
  12 return \code{1} for success and \code{0} for failure).
  13
  14 When a function must fail because some function it called failed, it
  15 generally doesn't set the error indicator; the function it called
  16 already set it.  It is responsible for either handling the error and
  17 clearing the exception or returning after cleaning up any resources it
  18 holds (such as object references or memory allocations); it should
  19 \emph{not} continue normally if it is not prepared to handle the
  20 error.  If returning due to an error, it is important to indicate to
  21 the caller that an error has been set.  If the error is not handled or
  22 carefully propogated, additional calls into the Python/C API may not
  23 behave as intended and may fail in mysterious ways.
  24
  25 The error indicator consists of three Python objects corresponding to
  26 \withsubitem{(in module sys)}{
  27   \ttindex{exc_type}\ttindex{exc_value}\ttindex{exc_traceback}}
  28 the Python variables \code{sys.exc_type}, \code{sys.exc_value} and
  29 \code{sys.exc_traceback}.  API functions exist to interact with the
  30 error indicator in various ways.  There is a separate error indicator
  31 for each thread.
  32
  33 % XXX Order of these should be more thoughtful.
  34 % Either alphabetical or some kind of structure.
  35
  36 \begin{cfuncdesc}{void}{PyErr_Print}{}
  37   Print a standard traceback to \code{sys.stderr} and clear the error
  38   indicator.  Call this function only when the error indicator is
  39   set.  (Otherwise it will cause a fatal error!)
  40 \end{cfuncdesc}
  41
  42 \begin{cfuncdesc}{PyObject*}{PyErr_Occurred}{}
  43   Test whether the error indicator is set.  If set, return the
  44   exception \emph{type} (the first argument to the last call to one of
  45   the \cfunction{PyErr_Set*()} functions or to
  46   \cfunction{PyErr_Restore()}).  If not set, return \NULL.  You do
  47   not own a reference to the return value, so you do not need to
  48   \cfunction{Py_DECREF()} it.  \note{Do not compare the return value
  49     to a specific exception; use \cfunction{PyErr_ExceptionMatches()}
  50     instead, shown below.  (The comparison could easily fail since the
  51     exception may be an instance instead of a class, in the case of a
  52     class exception, or it may the a subclass of the expected
  53     exception.)}
  54 \end{cfuncdesc}
  55
  56 \begin{cfuncdesc}{int}{PyErr_ExceptionMatches}{PyObject *exc}
  57   Equivalent to \samp{PyErr_GivenExceptionMatches(PyErr_Occurred(),
  58   \var{exc})}.  This should only be called when an exception is
  59   actually set; a memory access violation will occur if no exception
  60   has been raised.
  61 \end{cfuncdesc}
  62
  63 \begin{cfuncdesc}{int}{PyErr_GivenExceptionMatches}{PyObject *given, PyObject *exc}
  64   Return true if the \var{given} exception matches the exception in
  65   \var{exc}.  If \var{exc} is a class object, this also returns true
  66   when \var{given} is an instance of a subclass.  If \var{exc} is a
  67   tuple, all exceptions in the tuple (and recursively in subtuples)
  68   are searched for a match.  If \var{given} is \NULL, a memory access
  69   violation will occur.
  70 \end{cfuncdesc}
  71
  72 \begin{cfuncdesc}{void}{PyErr_NormalizeException}{PyObject**exc, PyObject**val, PyObject**tb}
  73   Under certain circumstances, the values returned by
  74   \cfunction{PyErr_Fetch()} below can be ``unnormalized'', meaning
  75   that \code{*\var{exc}} is a class object but \code{*\var{val}} is
  76   not an instance of the  same class.  This function can be used to
  77   instantiate the class in that case.  If the values are already
  78   normalized, nothing happens.  The delayed normalization is
  79   implemented to improve performance.
  80 \end{cfuncdesc}
  81
  82 \begin{cfuncdesc}{void}{PyErr_Clear}{}
  83   Clear the error indicator.  If the error indicator is not set, there
  84   is no effect.
  85 \end{cfuncdesc}
  86
  87 \begin{cfuncdesc}{void}{PyErr_Fetch}{PyObject **ptype, PyObject **pvalue,
  88                                      PyObject **ptraceback}
  89   Retrieve the error indicator into three variables whose addresses
  90   are passed.  If the error indicator is not set, set all three
  91   variables to \NULL.  If it is set, it will be cleared and you own a
  92   reference to each object retrieved.  The value and traceback object
  93   may be \NULL{} even when the type object is not.  \note{This
  94   function is normally only used by code that needs to handle
  95   exceptions or by code that needs to save and restore the error
  96   indicator temporarily.}
  97 \end{cfuncdesc}
  98
  99 \begin{cfuncdesc}{void}{PyErr_Restore}{PyObject *type, PyObject *value,
 100                                        PyObject *traceback}
 101   Set  the error indicator from the three objects.  If the error
 102   indicator is already set, it is cleared first.  If the objects are
 103   \NULL, the error indicator is cleared.  Do not pass a \NULL{} type
 104   and non-\NULL{} value or traceback.  The exception type should be a
 105   string or class; if it is a class, the value should be an instance
 106   of that class.  Do not pass an invalid exception type or value.
 107   (Violating these rules will cause subtle problems later.)  This call
 108   takes away a reference to each object: you must own a reference to
 109   each object before the call and after the call you no longer own
 110   these references.  (If you don't understand this, don't use this
 111   function.  I warned you.)  \note{This function is normally only used
 112   by code that needs to save and restore the error indicator
 113   temporarily.}
 114 \end{cfuncdesc}
 115
 116 \begin{cfuncdesc}{void}{PyErr_SetString}{PyObject *type, char *message}
 117   This is the most common way to set the error indicator.  The first
 118   argument specifies the exception type; it is normally one of the
 119   standard exceptions, e.g. \cdata{PyExc_RuntimeError}.  You need not
 120   increment its reference count.  The second argument is an error
 121   message; it is converted to a string object.
 122 \end{cfuncdesc}
 123
 124 \begin{cfuncdesc}{void}{PyErr_SetObject}{PyObject *type, PyObject *value}
 125   This function is similar to \cfunction{PyErr_SetString()} but lets
 126   you specify an arbitrary Python object for the ``value'' of the
 127   exception.  You need not increment its reference count.
 128 \end{cfuncdesc}
 129
 130 \begin{cfuncdesc}{PyObject*}{PyErr_Format}{PyObject *exception,
 131                                            const char *format, \moreargs}
 132   This function sets the error indicator and returns \NULL..
 133   \var{exception} should be a Python exception (string or class, not
 134   an instance).  \var{format} should be a string, containing format
 135   codes, similar to \cfunction{printf()}. The \code{width.precision}
 136   before a format code is parsed, but the width part is ignored.
 137
 138   \begin{tableii}{c|l}{character}{Character}{Meaning}
 139     \lineii{c}{Character, as an \ctype{int} parameter}
 140     \lineii{d}{Number in decimal, as an \ctype{int} parameter}
 141     \lineii{x}{Number in hexadecimal, as an \ctype{int} parameter}
 142     \lineii{x}{A string, as a \ctype{char *} parameter}
 143   \end{tableii}
 144
 145   An unrecognized format character causes all the rest of the format
 146   string to be copied as-is to the result string, and any extra
 147   arguments discarded.
 148 \end{cfuncdesc}
 149
 150 \begin{cfuncdesc}{void}{PyErr_SetNone}{PyObject *type}
 151   This is a shorthand for \samp{PyErr_SetObject(\var{type},
 152   Py_None)}.
 153 \end{cfuncdesc}
 154
 155 \begin{cfuncdesc}{int}{PyErr_BadArgument}{}
 156   This is a shorthand for \samp{PyErr_SetString(PyExc_TypeError,
 157   \var{message})}, where \var{message} indicates that a built-in
 158   operation was invoked with an illegal argument.  It is mostly for
 159   internal use.
 160 \end{cfuncdesc}
 161
 162 \begin{cfuncdesc}{PyObject*}{PyErr_NoMemory}{}
 163   This is a shorthand for \samp{PyErr_SetNone(PyExc_MemoryError)}; it
 164   returns \NULL{} so an object allocation function can write
 165   \samp{return PyErr_NoMemory();} when it runs out of memory.
 166 \end{cfuncdesc}
 167
 168 \begin{cfuncdesc}{PyObject*}{PyErr_SetFromErrno}{PyObject *type}
 169   This is a convenience function to raise an exception when a C
 170   library function has returned an error and set the C variable
 171   \cdata{errno}.  It constructs a tuple object whose first item is the
 172   integer \cdata{errno} value and whose second item is the
 173   corresponding error message (gotten from
 174   \cfunction{strerror()}\ttindex{strerror()}), and then calls
 175   \samp{PyErr_SetObject(\var{type}, \var{object})}.  On \UNIX, when
 176   the \cdata{errno} value is \constant{EINTR}, indicating an
 177   interrupted system call, this calls
 178   \cfunction{PyErr_CheckSignals()}, and if that set the error
 179   indicator, leaves it set to that.  The function always returns
 180   \NULL, so a wrapper function around a system call can write
 181   \samp{return PyErr_SetFromErrno();} when  the system call returns an
 182   error.
 183 \end{cfuncdesc}
 184
 185 \begin{cfuncdesc}{PyObject*}{PyErr_SetFromErrnoWithFilename}{PyObject *type,
 186                                                              char *filename}
 187   Similar to \cfunction{PyErr_SetFromErrno()}, with the additional
 188   behavior that if \var{filename} is not \NULL, it is passed to the
 189   constructor of \var{type} as a third parameter.  In the case of
 190   exceptions such as \exception{IOError} and \exception{OSError}, this
 191   is used to define the \member{filename} attribute of the exception
 192   instance.
 193 \end{cfuncdesc}
 194
 195 \begin{cfuncdesc}{void}{PyErr_BadInternalCall}{}
 196   This is a shorthand for \samp{PyErr_SetString(PyExc_TypeError,
 197   \var{message})}, where \var{message} indicates that an internal
 198   operation (e.g. a Python/C API function) was invoked with an illegal
 199   argument.  It is mostly for internal use.
 200 \end{cfuncdesc}
 201
 202 \begin{cfuncdesc}{int}{PyErr_Warn}{PyObject *category, char *message}
 203   Issue a warning message.  The \var{category} argument is a warning
 204   category (see below) or \NULL; the \var{message} argument is a
 205   message string.
 206
 207   This function normally prints a warning message to \var{sys.stderr};
 208   however, it is also possible that the user has specified that
 209   warnings are to be turned into errors, and in that case this will
 210   raise an exception.  It is also possible that the function raises an
 211   exception because of a problem with the warning machinery (the
 212   implementation imports the \module{warnings} module to do the heavy
 213   lifting).  The return value is \code{0} if no exception is raised,
 214   or \code{-1} if an exception is raised.  (It is not possible to
 215   determine whether a warning message is actually printed, nor what
 216   the reason is for the exception; this is intentional.)  If an
 217   exception is raised, the caller should do its normal exception
 218   handling (for example, \cfunction{Py_DECREF()} owned references and
 219   return an error value).
 220
 221   Warning categories must be subclasses of \cdata{Warning}; the
 222   default warning category is \cdata{RuntimeWarning}.  The standard
 223   Python warning categories are available as global variables whose
 224   names are \samp{PyExc_} followed by the Python exception name.
 225   These have the type \ctype{PyObject*}; they are all class objects.
 226   Their names are \cdata{PyExc_Warning}, \cdata{PyExc_UserWarning},
 227   \cdata{PyExc_DeprecationWarning}, \cdata{PyExc_SyntaxWarning}, and
 228   \cdata{PyExc_RuntimeWarning}.  \cdata{PyExc_Warning} is a subclass
 229   of \cdata{PyExc_Exception}; the other warning categories are
 230   subclasses of \cdata{PyExc_Warning}.
 231
 232   For information about warning control, see the documentation for the
 233   \module{warnings} module and the \programopt{-W} option in the
 234   command line documentation.  There is no C API for warning control.
 235 \end{cfuncdesc}
 236
 237 \begin{cfuncdesc}{int}{PyErr_WarnExplicit}{PyObject *category, char *message,
 238                 char *filename, int lineno, char *module, PyObject *registry}
 239   Issue a warning message with explicit control over all warning
 240   attributes.  This is a straightforward wrapper around the Python
 241   function \function{warnings.warn_explicit()}, see there for more
 242   information.  The \var{module} and \var{registry} arguments may be
 243   set to \NULL{} to get the default effect described there.
 244 \end{cfuncdesc}
 245
 246 \begin{cfuncdesc}{int}{PyErr_CheckSignals}{}
 247   This function interacts with Python's signal handling.  It checks
 248   whether a signal has been sent to the processes and if so, invokes
 249   the corresponding signal handler.  If the
 250   \module{signal}\refbimodindex{signal} module is supported, this can
 251   invoke a signal handler written in Python.  In all cases, the
 252   default effect for \constant{SIGINT}\ttindex{SIGINT} is to raise the
 253   \withsubitem{(built-in exception)}{\ttindex{KeyboardInterrupt}}
 254   \exception{KeyboardInterrupt} exception.  If an exception is raised
 255   the error indicator is set and the function returns \code{1};
 256   otherwise the function returns \code{0}.  The error indicator may or
 257   may not be cleared if it was previously set.
 258 \end{cfuncdesc}
 259
 260 \begin{cfuncdesc}{void}{PyErr_SetInterrupt}{}
 261   This function is obsolete.  It simulates the effect of a
 262   \constant{SIGINT}\ttindex{SIGINT} signal arriving --- the next time
 263   \cfunction{PyErr_CheckSignals()} is called,
 264   \withsubitem{(built-in exception)}{\ttindex{KeyboardInterrupt}}
 265   \exception{KeyboardInterrupt} will be raised.  It may be called
 266   without holding the interpreter lock.
 267 \end{cfuncdesc}
 268
 269 \begin{cfuncdesc}{PyObject*}{PyErr_NewException}{char *name,
 270                                                  PyObject *base,
 271                                                  PyObject *dict}
 272   This utility function creates and returns a new exception object.
 273   The \var{name} argument must be the name of the new exception, a C
 274   string of the form \code{module.class}.  The \var{base} and
 275   \var{dict} arguments are normally \NULL.  This creates a class
 276   object derived from the root for all exceptions, the built-in name
 277   \exception{Exception} (accessible in C as \cdata{PyExc_Exception}).
 278   The \member{__module__} attribute of the new class is set to the
 279   first part (up to the last dot) of the \var{name} argument, and the
 280   class name is set to the last part (after the last dot).  The
 281   \var{base} argument can be used to specify an alternate base class.
 282   The \var{dict} argument can be used to specify a dictionary of class
 283   variables and methods.
 284 \end{cfuncdesc}
 285
 286 \begin{cfuncdesc}{void}{PyErr_WriteUnraisable}{PyObject *obj}
 287   This utility function prints a warning message to \code{sys.stderr}
 288   when an exception has been set but it is impossible for the
 289   interpreter to actually raise the exception.  It is used, for
 290   example, when an exception occurs in an \method{__del__()} method.
 291
 292   The function is called with a single argument \var{obj} that
 293   identifies where the context in which the unraisable exception
 294   occurred.  The repr of \var{obj} will be printed in the warning
 295   message.
 296 \end{cfuncdesc}
 297
 298 \section{Standard Exceptions \label{standardExceptions}}
 299
 300 All standard Python exceptions are available as global variables whose
 301 names are \samp{PyExc_} followed by the Python exception name.  These
 302 have the type \ctype{PyObject*}; they are all class objects.  For
 303 completeness, here are all the variables:
 304
 305 \begin{tableiii}{l|l|c}{cdata}{C Name}{Python Name}{Notes}
 306   \lineiii{PyExc_Exception}{\exception{Exception}}{(1)}
 307   \lineiii{PyExc_StandardError}{\exception{StandardError}}{(1)}
 308   \lineiii{PyExc_ArithmeticError}{\exception{ArithmeticError}}{(1)}
 309   \lineiii{PyExc_LookupError}{\exception{LookupError}}{(1)}
 310   \lineiii{PyExc_AssertionError}{\exception{AssertionError}}{}
 311   \lineiii{PyExc_AttributeError}{\exception{AttributeError}}{}
 312   \lineiii{PyExc_EOFError}{\exception{EOFError}}{}
 313   \lineiii{PyExc_EnvironmentError}{\exception{EnvironmentError}}{(1)}
 314   \lineiii{PyExc_FloatingPointError}{\exception{FloatingPointError}}{}
 315   \lineiii{PyExc_IOError}{\exception{IOError}}{}
 316   \lineiii{PyExc_ImportError}{\exception{ImportError}}{}
 317   \lineiii{PyExc_IndexError}{\exception{IndexError}}{}
 318   \lineiii{PyExc_KeyError}{\exception{KeyError}}{}
 319   \lineiii{PyExc_KeyboardInterrupt}{\exception{KeyboardInterrupt}}{}
 320   \lineiii{PyExc_MemoryError}{\exception{MemoryError}}{}
 321   \lineiii{PyExc_NameError}{\exception{NameError}}{}
 322   \lineiii{PyExc_NotImplementedError}{\exception{NotImplementedError}}{}
 323   \lineiii{PyExc_OSError}{\exception{OSError}}{}
 324   \lineiii{PyExc_OverflowError}{\exception{OverflowError}}{}
 325   \lineiii{PyExc_ReferenceError}{\exception{ReferenceError}}{(2)}
 326   \lineiii{PyExc_RuntimeError}{\exception{RuntimeError}}{}
 327   \lineiii{PyExc_SyntaxError}{\exception{SyntaxError}}{}
 328   \lineiii{PyExc_SystemError}{\exception{SystemError}}{}
 329   \lineiii{PyExc_SystemExit}{\exception{SystemExit}}{}
 330   \lineiii{PyExc_TypeError}{\exception{TypeError}}{}
 331   \lineiii{PyExc_ValueError}{\exception{ValueError}}{}
 332   \lineiii{PyExc_WindowsError}{\exception{WindowsError}}{(3)}
 333   \lineiii{PyExc_ZeroDivisionError}{\exception{ZeroDivisionError}}{}
 334 \end{tableiii}
 335
 336 \noindent
 337 Notes:
 338 \begin{description}
 339 \item[(1)]
 340   This is a base class for other standard exceptions.
 341
 342 \item[(2)]
 343   This is the same as \exception{weakref.ReferenceError}.
 344
 345 \item[(3)]
 346   Only defined on Windows; protect code that uses this by testing that
 347   the preprocessor macro \code{MS_WINDOWS} is defined.
 348 \end{description}
 349
 350
 351 \section{Deprecation of String Exceptions}
 352
 353 All exceptions built into Python or provided in the standard library
 354 are derived from \exception{Exception}.
 355 \withsubitem{(built-in exception)}{\ttindex{Exception}}
 356
 357 String exceptions are still supported in the interpreter to allow
 358 existing code to run unmodified, but this will also change in a future
 359 release.