iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Essentially version 3 of this PEP. 

All renamings have been removed.  All new exceptions that were not superclasses
have been removed.  CriticalException has been renamed TerminalException.
SystemError and MemoryError have been moved back under Exception, but while
inheriting from the new exception VMError.  ControlFlowException has been
removed and its subclasses now directly inherit Exception.

Also includes reformatting of the references and some editorial changes as
suggested by David Goodger.
This commit is contained in:
Brett Cannon 2005-08-07 04:14:04 +00:00
parent 9c2cb031b8
commit cbbce90c40
1 changed files with 175 additions and 266 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

373
pep-0348.txt
View File

@ -13,11 +13,11 @@ Post-History: 03-Aug-2005
Abstract Abstract
======== ========
Python, as of version 2.4, has 38 exceptions (including warnings) in Python, as 0of version 2.4, has 38 exceptions (including warnings) in
the built-in namespace in a rather shallow hierarchy. This list of the built-in namespace in a rather shallow hierarchy. This list of
classes has grown over the years without a chance to learn from classes has grown over the years without a chance to learn from
mistakes and clean up the hierarchy. This PEP proposes doing a experience. This PEP proposes doing a reorganization of the hierarchy
reorganization for Python 3.0 when backwards-compatibility is not an for Python 3.0 when backwards-compatibility is not as much of an
issue. Along with this reorganization, adding a requirement that all issue. Along with this reorganization, adding a requirement that all
objects passed to a ``raise`` statement must inherit from a specific objects passed to a ``raise`` statement must inherit from a specific
superclass is proposed. Lastly, bare ``except`` clauses will catch superclass is proposed. Lastly, bare ``except`` clauses will catch
@ -29,63 +29,68 @@ Rationale
Exceptions are a critical part of Python. While exceptions are Exceptions are a critical part of Python. While exceptions are
traditionally used to signal errors in a program, they have also grown traditionally used to signal errors in a program, they have also grown
to be used for flow control for things such as iterators. Their to be used for flow control for things such as iterators.
importance is great.
But the organization of the exception hierarchy is suboptimal to serve While their importance is great, there is lack of structure to them.
the multiple uses of exceptions. Mostly for backwards-compatibility This stems from the fact that any object can be raised as an
reasons, the hierarchy has stayed very flat and old exceptions whose exception. Because of this you have no guarantee in terms of what
usefulness has not been proven have been left in. Making exceptions kind of object will be raised, destroying any possible hierarchy
more hierarchical would help facilitate exception handling by making raised objects might adhere to.
exception catching using inheritance much more logical. This should
also help lead to fewer errors from overly broad exception catching in
``except`` clauses.
A mandatory superclass for all exceptions is also being proposed But exceptions do have a hierarchy, showing the severity of the
[#Summary2004-08-01]_. By requiring any object that is used in a exception. The hierarchy also groups related exceptions together to
``raise`` statement to inherit from a specific superclass, certain simplify catching them in ``except`` clauses. To allow peopele to
attributes (such as those laid out in PEP 344 [#PEP344]_) can be be able to rely on this hierarchy, a common superclasse that all
guaranteed to exist. This also will lead to the planned removal of raise objects must inherit from is being proposed. It also allows
string exceptions. guarantees about the interface to raised objects to be made (see
PEP 344 [#PEP344]_). A discussion about all of this has occurred
before on python-dev [#Summary2004-08-01]_.
Lastly, bare ``except`` clauses are to catch only exceptions that But allowing a guarantee about the hierarchy is not the only place
inherit from ``Exception`` [#python-dev3]_. While currently used to where exceptions can stand improvement. Bare ``except`` clauses are
catch all exceptions, that use is too far-reaching and typically not often used in an inappropriate manner. Since they catch *all* raised
desired. Catching only exceptions that inherit from ``Exception`` objects, they can catch exceptions that should have been allowed to
allows other exceptions (those that should not be caught unless propagate to the top level of the execution stack, leading to the
explicitly desired) to continue to propagate up the execution stack. interpreter terminating execution. Once again, this has been
discussed on python-dev [#python-dev3]_.
To fix this over-reaching of bare ``except`` clauses, it is being
proposed that only objects inheriting from Exception be caught by
bare ``except`` clauses. This will allow the exception hierarchy
to be organized in such a way that bare ``except`` clauses can be
more useful by allowing exceptions that should not normally be caught
to lead to the termination of the interpreter.
Philosophy of Reorganization Philosophy of Reorganization
============================ ============================
There are several goals in this reorganization that defined the For the reorganization of the hierarchy, there was a general
philosophy used to guide the work. One goal was to prune out unneeded philosophy followed that developed from discussion of earlier drafts
exceptions. Extraneous exceptions should not be left in since they of this PEP [#python-dev-thread1]_, [#python-dev-thread2]_,
just serve to clutter the built-in namespace. Unneeded exceptions [#python-dev-thread3]_. First and foremost was to not break anything
also dilute the importance of other exceptions by splitting uses that works. This meant that renaming exceptions was out of the
between several exceptions when all uses should have been under a question unless the name was deemed severely bad. This
single exception. also meant no removal of exceptions unless they were viewed as
truly misplaced. The introduction of new exceptions were only done in
situations where there might be a use for catching a superclass of a
category of exceptions. Lastly, existing exceptions would have their
inheritance tree changed only if it was felt they were truly
misplaced to begin with.
Another goal was to introduce exceptions that were deemed necessary to For all new exceptions, the proper suffix had to be chosen. For
fill holes in the hierarchy. Most new exceptions were added to flesh those that signal an error, "Error" is to be used. If the exception
out the inheritance hierarchy to make it easier to catch a category of is a warning, then "Warning". "Exception" is to be used when none
exceptions with a simpler ``except`` clause. of the other suffixes are proper to use and no specific suffix is
a better fit.
Changing inheritance to make the hierarchy more reasonable was a goal. After that it came down to choosing which exceptions should and
As stated above, having proper inheritance allows for more accurate should not inherit from Exception. This was for the purpose of
``except`` statements when catching exceptions based on the making bare ``except`` clauses more useful.
inheritance tree.
Lastly, some renaming was done to make the usage of certain exceptions Lastly, the entire existing hierarchy had to inherit from the new
more obvious. Having to look up an exception due to the name not exception meant to act as the required superclass for all exceptions
accurately reflecting its intended use is annoying and slows down to inherit from.
debugging. Having accurate names also makes debugging easier for new
programmers. But for simplicity, for the convenience of existing
users, and for the sake of transitioning to Python 3.0, only
exceptions whose names were significantly out of alignment with their
stated purpose have been renamed. All exceptions dealing with errors
will be named with an "Error" suffix.
New Hierarchy New Hierarchy
@ -94,19 +99,16 @@ New Hierarchy
.. Note:: Exceptions flagged with "stricter inheritance" will no .. Note:: Exceptions flagged with "stricter inheritance" will no
longer inherit from a certain class. A "broader inheritance" flag longer inherit from a certain class. A "broader inheritance" flag
means a class has been added to the exception's inheritance tree. means a class has been added to the exception's inheritance tree.
All comparisons are against the Python 2.4 exception hierarchy.
.. parsed-literal:: .. parsed-literal::
BaseException +-- BaseException (new; broader inheritance for subclasses)
+-- CriticalError (new) +-- TerminalException (new; stricter inheritance for subclasses)
+-- KeyboardInterrupt (stricter inheritance) +-- KeyboardInterrupt
+-- MemoryError (stricter inheritance) +-- SystemExit
+-- SystemError (stricter inheritance)
+-- ControlFlowException (new)
+-- GeneratorExit (defined in PEP 342 [#PEP342]_)
+-- StopIteration (stricter inheritance)
+-- SystemExit (stricter inheritance)
+-- Exception +-- Exception
+-- GeneratorExit (defined in PEP 342 [#PEP342]_)
+-- StandardError +-- StandardError
+-- ArithmeticError +-- ArithmeticError
+-- DivideByZeroError +-- DivideByZeroError
@ -122,48 +124,42 @@ New Hierarchy
+-- LookupError +-- LookupError
+-- IndexError +-- IndexError
+-- KeyError +-- KeyError
+-- NamespaceError (renamed from NameError) +-- NameError
+-- UnboundFreeError (new)
+-- UnboundGlobalError (new)
+-- UnboundLocalError +-- UnboundLocalError
+-- NotImplementedError (stricter inheritance) +-- NotImplementedError (stricter inheritance)
+-- SyntaxError +-- SyntaxError
+-- IndentationError +-- IndentationError
+-- TabError +-- TabError
+-- TypeError +-- TypeError
+-- UserError (renamed from RuntimeError) +-- RuntimeError
+-- UnicodeError +-- UnicodeError
+-- UnicodeDecodeError +-- UnicodeDecodeError
+-- UnicodeEncodeError +-- UnicodeEncodeError
+-- UnicodeTranslateError +-- UnicodeTranslateError
+-- ValueError +-- ValueError
+-- VMError (new; broader inheritance for subclasses)
+-- MemoryError
+-- SystemError
+-- ReferenceError
+-- StopIteration
+-- Warning +-- Warning
+-- AnyDeprecationWarning (new; broader inheritance for subclasses) +-- AnyDeprecationWarning (new; broader inheritance for subclasses)
+-- PendingDeprecationWarning +-- PendingDeprecationWarning
+-- DeprecationWarning +-- DeprecationWarning
+-- FutureWarning +-- FutureWarning
+-- SyntaxWarning +-- SyntaxWarning
+-- SemanticsWarning (renamed from RuntimeWarning) +-- RuntimeWarning
+-- UserWarning +-- UserWarning
+-- WeakReferenceError (renamed from ReferenceError)
Differences Compared to Python 2.4 Differences Compared to Python 2.4
================================== ==================================
Changes to exceptions from Python 2.4 can take shape in three forms: A more thorough explanation of terms is needed when discussing
removal, renaming, or change of position in the hierarchy. There are inheritance changes. Inheritance changes result in either broader or
also new exceptions introduced in the proposed hierarchy. more restrictive inheritance. "Broader" is when a class has an
inheritance tree like ``cls, A`` and then becomes ``cls, B, A``.
In terms of new exceptions, almost all are added to flesh out the "Stricter is the reverse.
inheritance tree. Those that are leaf classes are added to alleviate
the overloading of another exception.
Positional changes result in either broader or more restrictive
inheritance. The broader inheritance typically occurred to allow for
a more reasonable superclass to group related exceptions together.
Stricter inheritance happened when the pre-existing inheritance was
deemed incorrect and needed correction.
New Exceptions New Exceptions
@ -175,35 +171,19 @@ BaseException
The superclass that all exceptions must inherit from. The superclass that all exceptions must inherit from.
CriticalError TerminalException
''''''''''''' '''''''''''''''''
The superclass for severe error exceptions; typically, one would not Superclass for exceptions that are meant to the termination of the
want to recover from such an exception. The name is meant to reflect interpreter. It does not inherit from Exception so that
that these exceptions are raised asynchronously by the interpreter subclasses are not caught by bare ``except`` clauses.
when a critical event has occured.
ControlFlowException VMError
'''''''''''''''''''' '''''''
This exception exists as a superclass for all exceptions that directly Superclass for exceptions that deal directly with the virtual
deal with control flow. Inheriting from BaseException instead of machine.
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.
UnboundGlobalError
''''''''''''''''''
Raised when a global variable was not found.
UnboundFreeError
''''''''''''''''
Raised when a free variable is not found.
AnyDeprecationWarning AnyDeprecationWarning
@ -226,92 +206,14 @@ WindowsError
Too OS-specific to be kept in the built-in exception hierarchy. Too OS-specific to be kept in the built-in exception hierarchy.
Renamed Exceptions
------------------
RuntimeError
''''''''''''
Renamed to UserError.
Meant as a generic exception for use when neither a new exception
class nor inheritance-based exception catching is desired,
RuntimeError is poorly named. Its name in Python 2.4 seems to suggest
an error that occurred at runtime, possibly an error in the VM.
Renaming the exception to UserError more clearly states the purpose of
the exception as a quick-and-dirty error exception. The name also
keeps it in line with UserWarning.
If a user wants an non-error exception, raising BaseException directly
should be sufficient since Exception, which UserError inherits from,
is only used for errors.
ReferenceError
''''''''''''''
Renamed to WeakReferenceError.
ReferenceError was added to the built-in exception hierarchy in Python
2.2 [#exceptions-stdlib]_. Its name comes directly from the time when
it resided in the ``weakref`` module. Unfortunately its name does not
suggest its connection to weak references and thus deserves a
renaming.
NameError
'''''''''
Renamed to NamespaceError.
While NameError suggests its common use, it is not entirely apparent.
Making it a superclass for namespace-related exceptions warrants a
renaming to make its use abundantly clear. Plus the documentation of
the exception module [#exceptions-stdlib]_ states that it was actually
meant for global names and not for just any exception.
RuntimeWarning
''''''''''''''
Renamed to SemanticsWarning.
RuntimeWarning is supposed to represent semantic changes coming in the
future. But while saying that it affects the "runtime" is true,
flat-out stating that it is a semantic change is much clearer,
eliminating any possible association of the term "runtime" with the
virtual machine.
Change of Position in the Exception Hierarchy Change of Position in the Exception Hierarchy
--------------------------------------------- ---------------------------------------------
KeyboardInterrupt, MemoryError, and SystemError
'''''''''''''''''''''''''''''''''''''''''''''''
Inherit from CriticalError instead of from Exception.
These three 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 Exception but from an
entirely separate exception that will not be caught by a bare
``except`` clause.
StopIteration and SystemExit
''''''''''''''''''''''''''''
Inherit from ControlFlowException instead of from Exception.
By having these exceptions no longer inherit from Exception they will
not be accidentally caught by a bare ``except`` clause.
NotImplementedError NotImplementedError
''''''''''''''''''' '''''''''''''''''''
Inherits from Exception instead of from RuntimeError (renamed to Inherits from Exception instead of from RuntimeError.
UserError).
Originally inheriting from RuntimeError, NotImplementedError does not Originally inheriting from RuntimeError, NotImplementedError does not
have any direct relation to the exception meant for use in user code have any direct relation to the exception meant for use in user code
@ -387,20 +289,6 @@ pre-existing objects with the same name will mask the new exceptions,
preserving backwards-compatibility. preserving backwards-compatibility.
Renamed Exceptions
''''''''''''''''''
Renamed exceptions will directly subclass the new names. When the old
exceptions are instantiated (which occurs when an exception is caught,
either by a ``try`` statement or by propagating to the top of the
execution stack), a PendingDeprecationWarning will be raised.
This should properly preserve backwards-compatibility as old usage
won't change and the new names can also be used to catch exceptions
using the old names. The warning of the deprecation is also kept
simple.
New Inheritance for Old Exceptions New Inheritance for Old Exceptions
'''''''''''''''''''''''''''''''''' ''''''''''''''''''''''''''''''''''
@ -428,21 +316,23 @@ due for removal in Python 3.0.
Required Superclass for ``raise`` Required Superclass for ``raise``
--------------------------------- ---------------------------------
A SemanticsWarning will be raised when an object is passed to A DeprecationWarning will be raised when an object is passed to
``raise`` that does not have the proper inheritance. ``raise`` that does not have the proper inheritance.
Removal of Bare ``except`` Clauses Removal of Bare ``except`` Clauses
---------------------------------- ----------------------------------
A SemanticsWarning will be raised for all bare ``except`` clauses. A RuntimeWarning will be raised for all bare ``except`` clauses that
catch an exception that does not inherit from Exception.
Rejected Ideas Rejected Ideas
============== ==============
Threads on python-dev discussing this PEP can be found at Multiple threads on python-dev discussing this PEP have lead to
[#python-dev-thread1]_ and [#python-dev-thread2]_ various ideas being rejected [#python-dev-thread1]_,
[#python-dev-thread2]_, [#python-dev-thread3]_.
KeyboardInterrupt inheriting from ControlFlowException KeyboardInterrupt inheriting from ControlFlowException
@ -452,8 +342,7 @@ KeyboardInterrupt has been a contentious point within this hierarchy.
Some view the exception more as control flow being caused by the user. Some view the exception more as control flow being caused by the user.
But with its asynchronous cause (the user is able to trigger the But with its asynchronous cause (the user is able to trigger the
exception at any point in code) its proper place is inheriting from exception at any point in code) its proper place is inheriting from
CriticalException. It also keeps the name of the exception from being CriticalError.
"CriticalError".
Other Names for BaseException and Exception Other Names for BaseException and Exception
@ -508,7 +397,7 @@ SystemError Subclassing SystemExit
---------------------------------- ----------------------------------
Proposed because a SystemError is meant to lead to a system exit, the Proposed because a SystemError is meant to lead to a system exit, the
idea was removed since CriticalException indicates this better. idea was removed since CriticalError indicates this better.
ControlFlowException Under Exception ControlFlowException Under Exception
@ -529,18 +418,33 @@ Guido has said this is too weak of an argument since other areas of
Python have default behavior [#python-dev3]_. Python have default behavior [#python-dev3]_.
Open Issues Rename NameError to NamespaceError
=========== ----------------------------------
Remove ControlFlowException? NameError is considered more succinct and leaves open no possible mistyping of
the capitalization of "Namespace" [#python-dev5]_.
Renaming RuntimeError or Introducing SimpleError
''''''''''''''''''''''''''''''''''''''''''''''''
The thinking was that RuntimeError was in no way an obvious name for
an exception meant to be used when a situation did not call for the
creation of a new exception. The renaming was rejected on the basis
that the exception is already used throughout the interpreter [#python-dev6]_.
Rejection of SimpleError was founded on the thought that people
should be free to use whatever exception they choose and not have one
so blatently suggested [#python-dev7]_.
Renaming Existing Exceptions
---------------------------- ----------------------------
It has been suggested that ControlFlowException is not needed. Since Various renamings were suggested but non garnered more than a +0 vote
the desire to catch any control flow exception will be atypical, the (renaming ReferenceError to WeakReferenceError). The thinking was
suggestion is to just remove the exception and let the exceptions that that the existing names were fine and no one had actively complained
inherited from it inherit directly from BaseException. This still about them ever. To minimize backwards-compatibility issues and
preserves the seperation from Exception which is one of the driving causing existing Python programmers extra pain, the renamings were
factors behind the introduction of ControlFlowException. removed.
Acknowledgements Acknowledgements
@ -548,51 +452,56 @@ Acknowledgements
Thanks to Robert Brewer, Josiah Carlson, Nick Coghlan, Timothy Thanks to Robert Brewer, Josiah Carlson, Nick Coghlan, Timothy
Delaney, Jack Diedrich, Fred L. Drake, Jr., Philip J. Eby, Greg Ewing, Delaney, Jack Diedrich, Fred L. Drake, Jr., Philip J. Eby, Greg Ewing,
James Y. Knight, MA Lemburg, Guido van Rossum, Stephen J. Turnbull and James Y. Knight, MA Lemburg, Guido van Rossum, Stephen J. Turnbull,
everyone else I missed for participating in the discussion. Raymond Hettinger, and everyone else I missed for participating in the
discussion.
References References
========== ==========
.. [#PEP342] PEP 342 (Coroutines via Enhanced Generators) .. [#PEP342] PEP 342 (Coroutines via Enhanced Generators)
(http://www.python.org/peps/pep-0342.html) http://www.python.org/peps/pep-0342.html
.. [#PEP344] PEP 344 (Exception Chaining and Embedded Tracebacks) .. [#PEP344] PEP 344 (Exception Chaining and Embedded Tracebacks)
(http://www.python.org/peps/pep-0344.html) http://www.python.org/peps/pep-0344.html
.. [#Summary2004-08-01] python-dev Summary (An exception is an .. [#Summary2004-08-01] python-dev Summary (An exception is an
exception, unless it doesn't inherit from Exception) exception, unless it doesn't inherit from Exception)
(http://www.python.org/dev/summary/2004-08-01_2004-08-15.html#an-exception-is-an-exception-unless-it-doesn-t-inherit-from-exception) http://www.python.org/dev/summary/2004-08-01_2004-08-15.html#an-exception-is-an-exception-unless-it-doesn-t-inherit-from-exception
.. [#Summary2004-09-01] python-dev Summary (Cleaning the Exception House)
(http://www.python.org/dev/summary/2004-09-01_2004-09-15.html#cleaning-the-exception-house)
.. [#python-dev1] python-dev email (Exception hierarchy)
(http://mail.python.org/pipermail/python-dev/2004-August/047908.html)
.. [#python-dev2] python-dev email (Dangerous exceptions)
(http://mail.python.org/pipermail/python-dev/2004-September/048681.html)
.. [#python-dev3] python-dev email (PEP, take 2: Exception .. [#python-dev3] python-dev email (PEP, take 2: Exception
Reorganization for Python 3.0) Reorganization for Python 3.0)
(http://mail.python.org/pipermail/python-dev/2005-August/055116.html) http://mail.python.org/pipermail/python-dev/2005-August/055116.html
.. [#exceptions-stdlib] exceptions module .. [#exceptions-stdlib] exceptions module
(http://docs.python.org/lib/module-exceptions.html) http://docs.python.org/lib/module-exceptions.html
.. [#python-dev-thread1] python-dev thread (Pre-PEP: Exception .. [#python-dev-thread1] python-dev thread (Pre-PEP: Exception
Reorganization for Python 3.0) Reorganization for Python 3.0)
(http://mail.python.org/pipermail/python-dev/2005-July/055020.html, http://mail.python.org/pipermail/python-dev/2005-July/055020.html,
http://mail.python.org/pipermail/python-dev/2005-August/055065.html) http://mail.python.org/pipermail/python-dev/2005-August/055065.html
.. [#python-dev-thread2] python-dev thread (PEP, take 2: Exception .. [#python-dev-thread2] python-dev thread (PEP, take 2: Exception
Reorganization for Python 3.0) Reorganization for Python 3.0)
(http://mail.python.org/pipermail/python-dev/2005-August/055103.html) http://mail.python.org/pipermail/python-dev/2005-August/055103.html
.. [#python-dev-thread3] python-dev thread (Reorg PEP checked in)
http://mail.python.org/pipermail/python-dev/2005-August/055138.html
.. [#python-dev4] python-dev email (Pre-PEP: Exception Reorganization .. [#python-dev4] python-dev email (Pre-PEP: Exception Reorganization
for Python 3.0) for Python 3.0)
(http://mail.python.org/pipermail/python-dev/2005-July/055019.html) http://mail.python.org/pipermail/python-dev/2005-July/055019.html
.. [#python-dev5] python-dev email (PEP, take 2: Exception Reorganization for
Python 3.0)
http://mail.python.org/pipermail/python-dev/2005-August/055159.html
.. [#python-dev6] python-dev email (Exception Reorg PEP checked in)
http://mail.python.org/pipermail/python-dev/2005-August/055149.html
.. [#python-dev7] python-dev email (Exception Reorg PEP checked in)
http://mail.python.org/pipermail/python-dev/2005-August/055175.html
Copyright Copyright