Break the Python/C API manual into smaller files by chapter. This manual
has grown beyond what font-lock will work with using the default (X)Emacs
settings.
Indentation of the description has been made consistent, and a number of
smaller markup adjustments have been made as well.
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.