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.

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.