[Python-checkins] r42748 - in python/trunk: Doc/api/exceptions.tex Doc/lib/libexcs.tex Doc/tut/tut.tex Python/exceptions.c

brett.cannon python-checkins at python.org
Wed Mar 1 23:10:51 CET 2006


Author: brett.cannon
Date: Wed Mar  1 23:10:49 2006
New Revision: 42748

Modified:
   python/trunk/Doc/api/exceptions.tex
   python/trunk/Doc/lib/libexcs.tex
   python/trunk/Doc/tut/tut.tex
   python/trunk/Python/exceptions.c
Log:
Document PEP 352 changes.  Also added GeneratorExit.


Modified: python/trunk/Doc/api/exceptions.tex
==============================================================================
--- python/trunk/Doc/api/exceptions.tex	(original)
+++ python/trunk/Doc/api/exceptions.tex	Wed Mar  1 23:10:49 2006
@@ -346,6 +346,7 @@
 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 @@
 \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 

Modified: python/trunk/Doc/lib/libexcs.tex
==============================================================================
--- python/trunk/Doc/lib/libexcs.tex	(original)
+++ python/trunk/Doc/lib/libexcs.tex	Wed Mar  1 23:10:49 2006
@@ -14,7 +14,8 @@
 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 @@
 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 @@
 
 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 @@
 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 @@
   \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 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 @@
   \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 @@
 \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 @@
 
   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 @@
   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 @@
 
 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}

Modified: python/trunk/Doc/tut/tut.tex
==============================================================================
--- python/trunk/Doc/tut/tut.tex	(original)
+++ python/trunk/Doc/tut/tut.tex	Wed Mar  1 23:10:49 2006
@@ -3512,6 +3512,12 @@
 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')

Modified: python/trunk/Python/exceptions.c
==============================================================================
--- python/trunk/Python/exceptions.c	(original)
+++ python/trunk/Python/exceptions.c	Wed Mar  1 23:10:49 2006
@@ -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 @@
 \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 */
 );
 
 


More information about the Python-checkins mailing list