Document PEP 352 changes. Also added GeneratorExit.

This commit is contained in:
Brett Cannon 2006-03-01 22:10:49 +00:00
parent 65b3dab50e
commit 54ac29497e
4 changed files with 63 additions and 74 deletions

View File

@ -346,6 +346,7 @@ 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_StandardError\ttindex{PyExc_StandardError}}{\exception{StandardError}}{(1)}
\lineiii{PyExc_ArithmeticError\ttindex{PyExc_ArithmeticError}}{\exception{ArithmeticError}}{(1)}
@ -388,14 +389,17 @@ Notes:
\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{Exception}.
\withsubitem{(built-in exception)}{\ttindex{Exception}}
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

View File

@ -14,7 +14,8 @@ module.
In past versions of Python string exceptions were supported. In
Python 1.5 and newer versions, all standard exceptions have been
converted to class objects and users are encouraged to do the same.
String exceptions will raise a \code{PendingDeprecationWarning}.
String exceptions will raise a \code{DeprecationWarning} in Python 2.5 and
newer.
In future versions, support for string exceptions will be removed.
Two distinct string objects with the same value are considered different
@ -43,9 +44,9 @@ associated value itself will be stored in the variable named as the
second argument of the \keyword{except} clause (if any). For class
exceptions, that variable receives the exception instance. If the
exception class is derived from the standard root class
\exception{Exception}, the associated value is present as the
exception instance's \member{args} attribute, and possibly on other
attributes as well.
\exception{BaseException}, the associated value is present as the
exception instance's \member{args} attribute. If there is a single argument
(as is preferred), it is bound to the \member{message} attribute.
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
@ -55,7 +56,8 @@ inappropriate error.
The built-in exception classes can be sub-classed to define new
exceptions; programmers are encouraged to at least derive new
exceptions from the \exception{Exception} base class. More
exceptions from the \exception{Exception} class and not
\exception{BaseException}. More
information on defining exceptions is available in the
\citetitle[../tut/tut.html]{Python Tutorial} under the heading
``User-defined Exceptions.''
@ -65,23 +67,33 @@ information on defining exceptions is available in the
The following exceptions are only used as base classes for other
exceptions.
\begin{excdesc}{BaseException}
The base class for all built-in exceptions. It is not meant to be directly
inherited by user-defined classes (for that use \exception{Exception}). If
\function{str()} or \function{unicode()} is called on an instance of this
class, the representation of the argument(s) to the instance are returned or
the emptry string when there were no arguments. If only a single argument is
passed in, it is stored in the \member{message} attribute. If more than one
argument is passed in, \member{message} is set to the empty string. These
semantics are meant to reflect the fact that \member{message} is to store a
text message explaining why the exception had been raised. If more data needs
to be attached to the exception, attach it through arbitrary attributes on the
instance. All arguments are also stored in \member{args} as a tuple, but it will
eventually be deprecated and thus its use is discouraged.
\versionchanged[Changed to inherit from \exception{BaseException}]{2.5}
\versionadded{2.5}
\begin{excdesc}{Exception}
The root class for exceptions. All built-in exceptions are derived
All built-in, non-system-exiting exceptions are derived
from this class. All user-defined exceptions should also be derived
from this class, but this is not (yet) enforced. The \function{str()}
function, when applied to an instance of this class (or most derived
classes) returns the string value of the argument or arguments, or an
empty string if no arguments were given to the constructor. When used
as a sequence, this accesses the arguments given to the constructor
(handy for backward compatibility with old code). The arguments are
also available on the instance's \member{args} attribute, as a tuple.
from this class.
\end{excdesc}
\begin{excdesc}{StandardError}
The base class for all built-in exceptions except
\exception{StopIteration} and \exception{SystemExit}.
\exception{StandardError} itself is derived from the root class
\exception{Exception}.
\exception{StopIteration}, \exception{GeneratorExit},
\exception{KeyboardInterrupt} and \exception{SystemExit}.
\exception{StandardError} itself is derived from \exception{Exception}.
\end{excdesc}
\begin{excdesc}{ArithmeticError}
@ -156,6 +168,12 @@ Raised when an \keyword{assert} statement fails.
\file{pyconfig.h} file.
\end{excdesc}
\begin{excdesv}{GeneratorExit}
Raise when a generator's \method{close()} method is called.
It directly inherits from \exception{Exception} instead of
\exception{StandardError} since it is technically not an error.
\versionadded{2.5}
\begin{excdesc}{IOError}
% XXXJH xrefs here
Raised when an I/O operation (such as a \keyword{print} statement,
@ -192,10 +210,14 @@ Raised when an \keyword{assert} statement fails.
Raised when the user hits the interrupt key (normally
\kbd{Control-C} or \kbd{Delete}). During execution, a check for
interrupts is made regularly.
% XXXJH xrefs here
% XXX(hylton) xrefs here
Interrupts typed when a built-in function \function{input()} or
\function{raw_input()} is waiting for input also raise this
exception.
The exception inherits from \exception{BaseException} so as to not be
accidentally caught by code that catches \exception{Exception} and thus
prevent the interpreter from exiting.
\versionchanged[Changed to inherit from \exception{BaseException}]{2.5}
\end{excdesc}
\begin{excdesc}{MemoryError}
@ -270,6 +292,7 @@ Raised when an \keyword{assert} statement fails.
\versionadded{2.2}
\end{excdesc}
\begin{excdesc}{SyntaxError}
% XXXJH xref to these functions?
Raised when the parser encounters a syntax error. This may occur in
@ -299,7 +322,7 @@ Raised when an \keyword{assert} statement fails.
\end{excdesc}
\begin{excdesc}{SystemExit}
% XXXJH xref to module sys?
% XXX(hylton) xref to module sys?
This exception is raised by the \function{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
@ -309,7 +332,7 @@ Raised when an \keyword{assert} statement fails.
Instances have an attribute \member{code} which is set to the
proposed exit status or error message (defaulting to \code{None}).
Also, this exception derives directly from \exception{Exception} and
Also, this exception derives directly from \exception{BaseException} and
not \exception{StandardError}, since it is not technically an error.
A call to \function{sys.exit()} is translated into an exception so that
@ -319,6 +342,12 @@ Raised when an \keyword{assert} statement fails.
can be used if it is absolutely positively necessary to exit
immediately (for example, in the child process after a call to
\function{fork()}).
The exception inherits from \exception{BaseException} instead of
\exception{StandardError} or \exception{Exception} so that it is not
accidentally caught by code that catches \exception{Exception}. This allows
the exception to properly propagate up and cause the interpreter to exit.
\versionchanged[Changed to inherit from \exception{BaseException}]{2.5}
\end{excdesc}
\begin{excdesc}{TypeError}
@ -418,49 +447,4 @@ in the future.
The class hierarchy for built-in exceptions is:
\begin{verbatim}
Exception
+-- SystemExit
+-- StopIteration
+-- StandardError
| +-- KeyboardInterrupt
| +-- ImportError
| +-- EnvironmentError
| | +-- IOError
| | +-- OSError
| | +-- WindowsError
| +-- EOFError
| +-- RuntimeError
| | +-- NotImplementedError
| +-- NameError
| | +-- UnboundLocalError
| +-- AttributeError
| +-- SyntaxError
| | +-- IndentationError
| | +-- TabError
| +-- TypeError
| +-- AssertionError
| +-- LookupError
| | +-- IndexError
| | +-- KeyError
| +-- ArithmeticError
| | +-- OverflowError
| | +-- ZeroDivisionError
| | +-- FloatingPointError
| +-- ValueError
| | +-- UnicodeError
| | +-- UnicodeEncodeError
| | +-- UnicodeDecodeError
| | +-- UnicodeTranslateError
| +-- ReferenceError
| +-- SystemError
| +-- MemoryError
+---Warning
+-- UserWarning
+-- DeprecationWarning
+-- PendingDeprecationWarning
+-- SyntaxWarning
+-- OverflowWarning (not generated in 2.4; won't exist in 2.5)
+-- RuntimeWarning
+-- FutureWarning
\end{verbatim}
\verbatiminput{../../Lib/test/exception_hierarchy.txt}

View File

@ -3512,6 +3512,12 @@ in \code{instance.args}. For convenience, the exception instance
defines \method{__getitem__} and \method{__str__} so the arguments can
be accessed or printed directly without having to reference \code{.args}.
But use of \code{.args} is discouraged. Instead, the preferred use is to pass
a single argument to an exception (which can be a tuple if multiple arguments
are needed) and have it bound to the \code{message} attribute. One my also
instantiate an exception first before raising it and add any attributes to it
as desired.
\begin{verbatim}
>>> try:
... raise Exception('spam', 'eggs')

View File

@ -7,11 +7,6 @@
* By moving the exceptions into C and statically linking, we can guarantee
* that the standard exceptions will always be available.
*
* history:
* 98-08-19 fl created (for pyexe)
* 00-02-08 fl updated for 1.5.2
* 26-May-2000 baw vetted for Python 1.6
* XXX
*
* written by Fredrik Lundh
* modifications, additions, cleanups, and proofreading by Barry Warsaw
@ -36,11 +31,11 @@ PyDoc_STRVAR(module__doc__,
\n\
Exceptions found here are defined both in the exceptions module and the \n\
built-in namespace. It is recommended that user-defined exceptions inherit \n\
from Exception.\n\
from Exception. See the documentation for the exception inheritance hierarchy.\n\
"
/* keep string pieces "small" */
/* XXX exception hierarchy from Lib/test/exception_hierarchy.txt */
/* XXX(bcannon): exception hierarchy in Lib/test/exception_hierarchy.txt */
);