[Python-checkins] python/nondist/peps pep-0348.txt,1.1,1.2

[bcannon@users.sourceforge.net]

Update of /cvsroot/python/python/nondist/peps
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv9052

Modified Files:
	pep-0348.txt 
Log Message:
Finish moving to BaseException/Exception naming.  Also leave in StandardError
so as to provide a base Error exception that inherits from Exception.  Also
allows Warning to inherit from Exception without being put at the same level as
any *Error exceptions.


Index: pep-0348.txt
===================================================================
RCS file: /cvsroot/python/python/nondist/peps/pep-0348.txt,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -d -r1.1 -r1.2
--- pep-0348.txt	4 Aug 2005 03:18:57 -0000	1.1
+++ pep-0348.txt	4 Aug 2005 03:33:03 -0000	1.2
@@ -19,7 +19,7 @@
 Along with this reorganization, adding a requirement that all objects passed to
 a ``raise`` statement must inherit from a specific superclass is proposed.
 Lastly, bare ``except`` clauses will catch only exceptions inheriting from
-StandardError.
+Exception.
 
 
 Rationale
@@ -43,7 +43,7 @@
 Exception [python-dev3]_.
 While currently used to catch all exceptions, that use is rather far reaching
 and typically not desired.
-Catching only exceptions inheriting from StandardError allows exceptions that
+Catching only exceptions inheriting from Exception allows exceptions that
 should not be caught unless explicitly desired to continue to propagate up the
 execution stack.
 
@@ -66,6 +66,8 @@
 Having to look up what an exception is meant to be used for because the name does not proper reflect its usage is annoying and slows down debugging.
 Having a proper name also makes debugging easier on new programmers.
 But for simplicity of existing user's and for transitioning to Python 3.0, only exceptions whose names were fairly out of alignment with their stated purpose have been renamed.
+It was also made sure the exceptions dealing with errors had the "Error"
+suffix.
 
 New Hierarchy
 =============
@@ -86,36 +88,37 @@
     +-- StopIteration (broader inheritance)
     +-- SystemExit (broader inheritance)
  +-- Exception
-    +-- ArithmeticError
-        +-- DivideByZeroError
-        +-- FloatingPointError
-        +-- OverflowError
-    +-- AssertionError
-    +-- AttributeError
-    +-- EnvironmentError
-	+-- IOError
-	    +-- EOFError (broader inheritance)
-	+-- OSError
-    +-- ImportError
-    +-- LookupError
-        +-- IndexError
-        +-- KeyError
-    +-- NamespaceError (rename of NameError)
-	+-- UnboundFreeError (new)
-        +-- UnboundGlobalError (new)
-        +-- UnboundLocalError
-    +-- NotImplementedError (stricter inheritance)
-    +-- SyntaxError
-        +-- IndentationError
-            +-- TabError
-    +-- TypeError
-    +-- UserError (rename of RuntimeError)
-    +-- UnicodeError
-        +-- UnicodeDecodeError
-        +-- UnicodeEncodeError
-        +-- UnicodeTranslateError
-    +-- ValueError
-    +-- Warning (broader inheritance, including subclasses)
+    +-- StandardError
+	+-- ArithmeticError
+	    +-- DivideByZeroError
+	    +-- FloatingPointError
+	    +-- OverflowError
+	+-- AssertionError
+	+-- AttributeError
+	+-- EnvironmentError
+	    +-- IOError
+		+-- EOFError (broader inheritance)
+	    +-- OSError
+	+-- ImportError
+	+-- LookupError
+	    +-- IndexError
+	    +-- KeyError
+	+-- NamespaceError (rename of NameError)
+	    +-- UnboundFreeError (new)
+	    +-- UnboundGlobalError (new)
+	    +-- UnboundLocalError
+	+-- NotImplementedError (stricter inheritance)
+	+-- SyntaxError
+	    +-- IndentationError
+		+-- TabError
+	+-- TypeError
+	+-- UserError (rename of RuntimeError)
+	+-- UnicodeError
+	    +-- UnicodeDecodeError
+	    +-- UnicodeEncodeError
+	    +-- UnicodeTranslateError
+	+-- ValueError
+    +-- Warning
 	+-- AnyDeprecationWarning (new; broader inheritance for subclasses)
 	    +-- PendingDeprecationWarning
 	    +-- DeprecationWarning
@@ -144,6 +147,12 @@
 New Exceptions
 --------------
 
+BaseException
+'''''''''''''
+
+The superclass that all exceptions must inherit from.
+
+
 CriticalError
 '''''''''''''
 
@@ -159,7 +168,7 @@
 
 This exception exists as a superclass for all exceptions that directly deal
 with control flow.
-Inheriting from Exception instead of StandardError prevents them from being caught accidently when one wants to catch errors.
+Inheriting from BaseException instead of Exception prevents them from being caught accidently when one wants to catch errors.
 The name, by not mentioning "Error", does not lead to one to confuse the subclasses as errors.
 
 
@@ -214,7 +223,7 @@
 The name also keeps it in line with UserWarning.
 
 If a user wants an exception that is not to be used as an error, raising
-Exception directly should be sufficient as StandardError, as UserError inherits
+BaseException directly should be sufficient as Exception, as UserError inherits
 from, is only used for errors.
 
 
@@ -255,11 +264,11 @@
 KeyboardInterrupt, MemoryError, and SystemError
 '''''''''''''''''''''''''''''''''''''''''''''''
 
-Inherit from CriticalError instead of StandardError.
+Inherit from CriticalError instead of Exception.
 
 The three above-mentioned exceptions are not standard errors by any means.
 They are raised asynchronously by the interpreter when something specific has
-occurred.  Thus they warrant not inheriting from StandardError but from an
+occurred.  Thus they warrant not inheriting from Exception but from an
 entirely separate exception that will not be caught by a bare ``except``
 clause.
 
@@ -267,11 +276,11 @@
 NotImplementedError
 '''''''''''''''''''
 
-Inherits from StandardError instead of RuntimeError (renamed UserError).
+Inherits from Exception instead of RuntimeError (renamed UserError).
 
 Originally inheriting from RuntimeError, NotImplementedError does not have any
 direct relation to the exception meant for use in user code as a
-quick-and-dirty exception.  Thus it now directly inherits from StandardError.
+quick-and-dirty exception.  Thus it now directly inherits from Exception.
 
 
 EOFError
@@ -282,15 +291,6 @@
 Since an EOF comes from I/O it only makes sense that it be considered an I/O error.
 
 
-Warning
-'''''''
-
-Inherits from StandardError instead of Exception.
-
-In order for Warning to be caught by bare ``except`` clauses, it needs to
-inherit from StandardError as specified in this PEP.
-
-
 Required Superclass for ``raise``
 =================================
 
@@ -298,7 +298,7 @@
 If PEP 342 [PEP344]_ is accepted, the attributes outlined there will be guaranteed to be on all exceptions raised.
 This should help facilitate debugging by making the querying of information from exceptions much easier.
 
-The proposed hierarchy has Exception as the required class that one must inherit from.
+The proposed hierarchy has BaseException as the required class that one must inherit from.
 
 
 Implementation
@@ -310,8 +310,8 @@
 exception will have the same inheritance check.
 
 
-Bare ``except`` Clauses Catching StandardError Only
-===================================================
+Bare ``except`` Clauses Catching Exception Only
+===============================================
 
 While Python does have its "explicit is better than implicit" tenant, it is not
 necessary if a default behavior is reasonable.  In the case of a bare
@@ -322,15 +322,15 @@
 though, this is not what is truly desired.
 More often than not one wants to catch all error exceptions that do not signify
 a bad state of the interpreter.  In the new exception hierarchy this is
-embodied by StandardError.  Thus bare ``except`` clauses will catch only
-exceptions inheriting from StandardError.
+embodied by Exception.  Thus bare ``except`` clauses will catch only
+exceptions inheriting from Exception.
 
 
 Implementation
 --------------
 
 In the compiler, when a bare ``except`` clause is reached, the code for
-``except StandardError`` will be emitted.
+``except Exception`` will be emitted.
 
 
 Transition Plan
@@ -414,17 +414,14 @@
 CriticalException.  It also keeps the name of the exception from being "CriticalError".
 
 
-Renaming Exception to Raisable, StandardError to Exception
-----------------------------------------------------------
-
-While the naming makes sense and emphasizes the required superclass as what
-must be inherited from for raising an object, the naming is not required.
-Keeping the existing names minimizes code change to use the new names.
+Other Names for BaseException and Exception
+-------------------------------------------
 
-It has been argued that changing StandardError to Exception might actually
-reflect how users use Exception more accurately, that has not been considered a
-strong enough argument.  It entails guessing as to what users think in general
-and does technically lead to a change that is not backwards-compatible.
+Alternative names for BaseException/Exception have been Raisable/Exception and
+Exception/StandardError.  The former has been rejected on the basis that
+Raisable does not reflect how it is an exception well enough.  The latter was
+rejected based on the fact that it did not reflect current use as the chosen
+names do.
 
 
 DeprecationWarning Inheriting From PendingDeprecationWarning
@@ -472,12 +469,12 @@
 removed since CriticalException signifies this better.
 
 
-ControlFlowException Under StandardError
-----------------------------------------
+ControlFlowException Under Exception
+------------------------------------
 
-It has been suggested that ControlFlowException inherit from StandardError.
+It has been suggested that ControlFlowException inherit from Exception.
 This idea has been rejected based on the thinking that control flow exceptions
-are typically not desired to be caught in a generic fashion as StandardError
+are typically not desired to be caught in a generic fashion as Exception 
 will usually be used.
 
 
@@ -498,8 +495,8 @@
 It has been suggested that ControlFlowException is not needed.
 Since the desire to catch any control flow exception will be atypical, the
 suggestion is to just remove the exception and let the exceptions that
-inherited from it inherit directly from Exception.  This still preserves the
-seperation from StandardError which is one of the driving factors behind the
+inherited from it inherit directly from BaseException.  This still preserves the
+seperation from Exception which is one of the driving factors behind the
 introduction of the exception.