Delete the LaTeX doc tree.

1 files changed, 0 insertions, 428 deletions

diff --git a/Doc/api/exceptions.tex b/Doc/api/exceptions.tex
deleted file mode 100644
index 8676963..0000000
--- a/Doc/api/exceptions.tex
+++ /dev/null
@@ -1,428 +0,0 @@
-\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_*()} 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.  It is responsible for either handling the error and
-clearing the exception or returning after cleaning up any resources it
-holds (such as object references or memory allocations); it should
-\emph{not} continue normally if it is not prepared to handle the
-error.  If returning due to an error, it is important to indicate to
-the caller that an error has been set.  If the error is not handled or
-carefully propagated, additional calls into the Python/C API may not
-behave as intended and may fail in mysterious ways.
-
-The error indicator consists of three Python objects corresponding to
-the result of \code{sys.exc_info()}.  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
-  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; use \cfunction{PyErr_Fetch()} to save the current
-  exception state.}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyErr_SetString}{PyObject *type, const 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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyErr_Format}{PyObject *exception,
-                                           const char *format, \moreargs}
-  This function sets the error indicator and returns \NULL.
-  \var{exception} should be a Python exception (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.
-
-  % This should be exactly the same as the table in PyString_FromFormat.
-  % One should just refer to the other.
-
-  % The descriptions for %zd and %zu are wrong, but the truth is complicated
-  % because not all compilers support the %z width modifier -- we fake it
-  % when necessary via interpolating PY_FORMAT_SIZE_T.
-
-  % %u, %lu, %zu should have "new in Python 2.5" blurbs.
-
-  \begin{tableiii}{l|l|l}{member}{Format Characters}{Type}{Comment}
-    \lineiii{\%\%}{\emph{n/a}}{The literal \% character.}
-    \lineiii{\%c}{int}{A single character, represented as an C int.}
-    \lineiii{\%d}{int}{Exactly equivalent to \code{printf("\%d")}.}
-    \lineiii{\%u}{unsigned int}{Exactly equivalent to \code{printf("\%u")}.}
-    \lineiii{\%ld}{long}{Exactly equivalent to \code{printf("\%ld")}.}
-    \lineiii{\%lu}{unsigned long}{Exactly equivalent to \code{printf("\%lu")}.}
-    \lineiii{\%zd}{Py_ssize_t}{Exactly equivalent to \code{printf("\%zd")}.}
-    \lineiii{\%zu}{size_t}{Exactly equivalent to \code{printf("\%zu")}.}
-    \lineiii{\%i}{int}{Exactly equivalent to \code{printf("\%i")}.}
-    \lineiii{\%x}{int}{Exactly equivalent to \code{printf("\%x")}.}
-    \lineiii{\%s}{char*}{A null-terminated C character array.}
-    \lineiii{\%p}{void*}{The hex representation of a C pointer.
-	Mostly equivalent to \code{printf("\%p")} except that it is
-	guaranteed to start with the literal \code{0x} regardless of
-	what the platform's \code{printf} yields.}
-  \end{tableiii}
-
-  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.
-\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(\var{type});} when the system call
-  returns an error.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyErr_SetFromErrnoWithFilename}{PyObject *type,
-                                                             const 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}{PyObject*}{PyErr_SetFromWindowsErr}{int ierr}
-  This is a convenience function to raise \exception{WindowsError}.
-  If called with \var{ierr} of \cdata{0}, the error code returned by a
-  call to \cfunction{GetLastError()} is used instead.  It calls the
-  Win32 function \cfunction{FormatMessage()} to retrieve the Windows
-  description of error code given by \var{ierr} or
-  \cfunction{GetLastError()}, then it constructs a tuple object whose
-  first item is the \var{ierr} value and whose second item is the
-  corresponding error message (gotten from
-  \cfunction{FormatMessage()}), and then calls
-  \samp{PyErr_SetObject(\var{PyExc_WindowsError}, \var{object})}.
-  This function always returns \NULL.
-  Availability: Windows.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyErr_SetExcFromWindowsErr}{PyObject *type,
-	                                                 int ierr}
-  Similar to \cfunction{PyErr_SetFromWindowsErr()}, with an additional
-  parameter specifying the exception type to be raised.
-  Availability: Windows.
-  \versionadded{2.3}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyErr_SetFromWindowsErrWithFilename}{int ierr,
-                                                                const char *filename}
-  Similar to \cfunction{PyErr_SetFromWindowsErr()}, with the
-  additional behavior that if \var{filename} is not \NULL, it is
-  passed to the constructor of \exception{WindowsError} as a third
-  parameter.
-  Availability: Windows.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyErr_SetExcFromWindowsErrWithFilename}
-	{PyObject *type, int ierr, char *filename}
-  Similar to \cfunction{PyErr_SetFromWindowsErrWithFilename()}, with
-  an additional parameter specifying the exception type to be raised.
-  Availability: Windows.
-  \versionadded{2.3}
-\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_WarnEx}{PyObject *category, char *message, int stacklevel}
-  Issue a warning message.  The \var{category} argument is a warning
-  category (see below) or \NULL; the \var{message} argument is a
-  message string.  \var{stacklevel} is a positive number giving a
-  number of stack frames; the warning will be issued from the 
-  currently executing line of code in that stack frame.  A \var{stacklevel}
-  of 1 is the function calling \cfunction{PyErr_WarnEx()}, 2 is 
-  the function above that, and so forth.
-
-  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_UnicodeWarning}, \cdata{PyExc_DeprecationWarning},
-  \cdata{PyExc_SyntaxWarning}, \cdata{PyExc_RuntimeWarning}, and
-  \cdata{PyExc_FutureWarning}.  \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,
-                const char *message, const char *filename, int lineno,
-                const 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 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.
-  % XXX This was described as obsolete, but is used in
-  % thread.interrupt_main() (used from IDLE), so it's still needed.
-\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 \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 alternate base classes;
-  it can either be only one class or a tuple of classes.
-  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 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_BaseException\ttindex{PyExc_BaseException}}{\exception{BaseException}}{(1), (4)}
-  \lineiii{PyExc_Exception\ttindex{PyExc_Exception}}{\exception{Exception}}{(1)}
-  \lineiii{PyExc_ArithmeticError\ttindex{PyExc_ArithmeticError}}{\exception{ArithmeticError}}{(1)}
-  \lineiii{PyExc_LookupError\ttindex{PyExc_LookupError}}{\exception{LookupError}}{(1)}
-  \lineiii{PyExc_AssertionError\ttindex{PyExc_AssertionError}}{\exception{AssertionError}}{}
-  \lineiii{PyExc_AttributeError\ttindex{PyExc_AttributeError}}{\exception{AttributeError}}{}
-  \lineiii{PyExc_EOFError\ttindex{PyExc_EOFError}}{\exception{EOFError}}{}
-  \lineiii{PyExc_EnvironmentError\ttindex{PyExc_EnvironmentError}}{\exception{EnvironmentError}}{(1)}
-  \lineiii{PyExc_FloatingPointError\ttindex{PyExc_FloatingPointError}}{\exception{FloatingPointError}}{}
-  \lineiii{PyExc_IOError\ttindex{PyExc_IOError}}{\exception{IOError}}{}
-  \lineiii{PyExc_ImportError\ttindex{PyExc_ImportError}}{\exception{ImportError}}{}
-  \lineiii{PyExc_IndexError\ttindex{PyExc_IndexError}}{\exception{IndexError}}{}
-  \lineiii{PyExc_KeyError\ttindex{PyExc_KeyError}}{\exception{KeyError}}{}
-  \lineiii{PyExc_KeyboardInterrupt\ttindex{PyExc_KeyboardInterrupt}}{\exception{KeyboardInterrupt}}{}
-  \lineiii{PyExc_MemoryError\ttindex{PyExc_MemoryError}}{\exception{MemoryError}}{}
-  \lineiii{PyExc_NameError\ttindex{PyExc_NameError}}{\exception{NameError}}{}
-  \lineiii{PyExc_NotImplementedError\ttindex{PyExc_NotImplementedError}}{\exception{NotImplementedError}}{}
-  \lineiii{PyExc_OSError\ttindex{PyExc_OSError}}{\exception{OSError}}{}
-  \lineiii{PyExc_OverflowError\ttindex{PyExc_OverflowError}}{\exception{OverflowError}}{}
-  \lineiii{PyExc_ReferenceError\ttindex{PyExc_ReferenceError}}{\exception{ReferenceError}}{(2)}
-  \lineiii{PyExc_RuntimeError\ttindex{PyExc_RuntimeError}}{\exception{RuntimeError}}{}
-  \lineiii{PyExc_SyntaxError\ttindex{PyExc_SyntaxError}}{\exception{SyntaxError}}{}
-  \lineiii{PyExc_SystemError\ttindex{PyExc_SystemError}}{\exception{SystemError}}{}
-  \lineiii{PyExc_SystemExit\ttindex{PyExc_SystemExit}}{\exception{SystemExit}}{}
-  \lineiii{PyExc_TypeError\ttindex{PyExc_TypeError}}{\exception{TypeError}}{}
-  \lineiii{PyExc_ValueError\ttindex{PyExc_ValueError}}{\exception{ValueError}}{}
-  \lineiii{PyExc_WindowsError\ttindex{PyExc_WindowsError}}{\exception{WindowsError}}{(3)}
-  \lineiii{PyExc_ZeroDivisionError\ttindex{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.
-
-\item[(4)]
-  \versionadded{2.5}
-\end{description}
-
-
-\section{Deprecation of String Exceptions}
-
-All exceptions built into Python or provided in the standard library
-are derived from \exception{BaseException}.
-\withsubitem{(built-in exception)}{\ttindex{BaseException}}
-
-String exceptions are still supported in the interpreter to allow
-existing code to run unmodified, but this will also change in a future
-release.