Restructured library documentation

1 files changed, 172 insertions, 0 deletions

diff --git a/Doc/libexcs.tex b/Doc/libexcs.tex
new file mode 100644
index 0000000..33083cd
--- /dev/null
+++ b/Doc/libexcs.tex
@@ -0,0 +1,172 @@
+\section{Built-in Exceptions}
+
+Exceptions are string objects.  Two distinct string objects with the
+same value are different exceptions.  This is done to force programmers
+to use exception names rather than their string value when specifying
+exception handlers.  The string value of all built-in exceptions is
+their name, but this is not a requirement for user-defined exceptions
+or exceptions defined by library modules.
+
+The following exceptions can be generated by the interpreter or
+built-in functions.  Except where mentioned, they have an `associated
+value' indicating the detailed cause of the error.  This may be a
+string or a tuple containing several items of information (e.g., an
+error code and a string explaining the code).
+
+User code can raise built-in exceptions.  This can be used to test an
+exception handler or to report an error condition `just like' the
+situation in which the interpreter raises the same exception; but
+beware that there is nothing to prevent user code from raising an
+inappropriate error.
+
+\renewcommand{\indexsubitem}{(built-in exception)}
+
+\begin{excdesc}{AttributeError}
+% xref to attribute reference?
+  Raised when an attribute reference or assignment fails.  (When an
+  object does not support attributes references or attribute assignments
+  at all, \code{TypeError} is raised.)
+\end{excdesc}
+
+\begin{excdesc}{EOFError}
+% XXXJH xrefs here
+  Raised when one of the built-in functions (\code{input()} or
+  \code{raw_input()}) hits an end-of-file condition (\EOF{}) without
+  reading any data.
+% XXXJH xrefs here
+  (N.B.: the \code{read()} and \code{readline()} methods of file
+  objects return an empty string when they hit \EOF{}.)  No associated value.
+\end{excdesc}
+
+\begin{excdesc}{IOError}
+% XXXJH xrefs here
+  Raised when an I/O operation (such as a \code{print} statement, the
+  built-in \code{open()} function or a method of a file object) fails
+  for an I/O-related reason, e.g., `file not found', `disk full'.
+\end{excdesc}
+
+\begin{excdesc}{ImportError}
+% XXXJH xref to import statement?
+  Raised when an \code{import} statement fails to find the module
+  definition or when a \code{from {\rm \ldots} import} fails to find a
+  name that is to be imported.
+\end{excdesc}
+
+\begin{excdesc}{IndexError}
+% XXXJH xref to sequences
+  Raised when a sequence subscript is out of range.  (Slice indices are
+  silently truncated to fall in the allowed range; if an index is not a
+  plain integer, \code{TypeError} is raised.)
+\end{excdesc}
+
+\begin{excdesc}{KeyError}
+% XXXJH xref to mapping objects?
+  Raised when a mapping (dictionary) key is not found in the set of
+  existing keys.
+\end{excdesc}
+
+\begin{excdesc}{KeyboardInterrupt}
+  Raised when the user hits the interrupt key (normally
+  \kbd{Control-C} or
+\key{DEL}).  During execution, a check for interrupts is made regularly.
+% XXXJH xrefs here
+  Interrupts typed when a built-in function \code{input()} or
+  \code{raw_input()}) is waiting for input also raise this exception.  No
+  associated value.
+\end{excdesc}
+
+\begin{excdesc}{MemoryError}
+  Raised when an operation runs out of memory but the situation may
+  still be rescued (by deleting some objects).  The associated value is
+  a string indicating what kind of (internal) operation ran out of memory.
+  Note that because of the underlying memory management architecture
+  (\C{}'s \code{malloc()} function), the interpreter may not always be able
+  to completely recover from this situation; it nevertheless raises an
+  exception so that a stack traceback can be printed, in case a run-away
+  program was the cause.
+\end{excdesc}
+
+\begin{excdesc}{NameError}
+  Raised when a local or global name is not found.  This applies only
+  to unqualified names.  The associated value is the name that could
+  not be found.
+\end{excdesc}
+
+\begin{excdesc}{OverflowError}
+% XXXJH reference to long's and/or int's?
+  Raised when the result of an arithmetic operation is too large to be
+  represented.  This cannot occur for long integers (which would rather
+  raise \code{MemoryError} than give up).  Because of the lack of
+  standardization of floating point exception handling in \C{}, most
+  floating point operations also aren't checked.  For plain integers,
+  all operations that can overflow are checked except left shift, where
+  typical applications prefer to drop bits than raise an exception.
+\end{excdesc}
+
+\begin{excdesc}{RuntimeError}
+  Raised when an error is detected that doesn't fall in any of the
+  other categories.  The associated value is a string indicating what
+  precisely went wrong.  (This exception is a relic from a previous
+  version of the interpreter; it is not used any more except by some
+  extension modules that haven't been converted to define their own
+  exceptions yet.)
+\end{excdesc}
+
+\begin{excdesc}{SyntaxError}
+% XXXJH xref to these functions?
+  Raised when the parser encounters a syntax error.  This may occur in
+  an \code{import} statement, in an \code{exec} statement, in a call
+  to the built-in function \code{eval()} or \code{input()}, or
+  when reading the initial script or standard input (also
+  interactively).
+\end{excdesc}
+
+\begin{excdesc}{SystemError}
+  Raised when the interpreter finds an internal error, but the
+  situation does not look so serious to cause it to abandon all hope.
+  The associated value is a string indicating what went wrong (in
+  low-level terms).
+  
+  You should report this to the author or maintainer of your Python
+  interpreter.  Be sure to report the version string of the Python
+  interpreter (\code{sys.version}; it is also printed at the start of an
+  interactive Python session), the exact error message (the exception's
+  associated value) and if possible the source of the program that
+  triggered the error.
+\end{excdesc}
+
+\begin{excdesc}{SystemExit}
+% XXXJH xref to module sys?
+  This exception is raised by the \code{sys.exit()} function.  When it
+  is not handled, the Python interpreter exits; no stack traceback is
+  printed.  If the associated value is a plain integer, it specifies the
+  system exit status (passed to \C{}'s \code{exit()} function); if it is
+  \code{None}, the exit status is zero; if it has another type (such as
+  a string), the object's value is printed and the exit status is one.
+  
+  A call to \code{sys.exit} is translated into an exception so that
+  clean-up handlers (\code{finally} clauses of \code{try} statements)
+  can be executed, and so that a debugger can execute a script without
+  running the risk of losing control.  The \code{posix._exit()} function
+  can be used if it is absolutely positively necessary to exit
+  immediately (e.g., after a \code{fork()} in the child process).
+\end{excdesc}
+
+\begin{excdesc}{TypeError}
+  Raised when a built-in operation or function is applied to an object
+  of inappropriate type.  The associated value is a string giving
+  details about the type mismatch.
+\end{excdesc}
+
+\begin{excdesc}{ValueError}
+  Raised when a built-in operation or function receives an argument
+  that has the right type but an inappropriate value, and the
+  situation is not described by a more precise exception such as
+  \code{IndexError}.
+\end{excdesc}
+
+\begin{excdesc}{ZeroDivisionError}
+  Raised when the second argument of a division or modulo operation is
+  zero.  The associated value is a string indicating the type of the
+  operands and the operation.
+\end{excdesc}