PEP: 352 Title: Required Superclass for Exceptions Version: $Revision$ Last-Modified: $Date$ Author: Brett Cannon Guido van Rossum Status: Final Type: Standards Track Content-Type: text/x-rst Created: 27-Oct-2005 Post-History: Abstract ======== In Python 2.4 and before, any (classic) class can be raised as an exception. The plan is to allow new-style classes starting in Python 2.5, but this makes the problem worse -- it would mean *any* class (or instance) can be raised! (This is not the case in the final version; only built-in exceptions can be new-style which means you need to inherit from a built-in exception to have user-defined exceptions also be new-style) This is a problem because it prevents any guarantees from being made about the interface of exceptions. This PEP proposes introducing a new superclass that all raised objects must inherit from. Imposing the restriction will allow a standard interface for exceptions to exist that can be relied upon. One might counter that requiring a specific base class for a particular interface is unPythonic. However, in the specific case of exceptions there's a good reason (which has generally been agreed to on python-dev): requiring hierarchy helps code that wants to *catch* exceptions by making it possible to catch *all* exceptions explicitly by writing ``except BaseException:`` instead of ``except *:``. [#hierarchy-good]_ Introducing a new superclass for exceptions also gives us the chance to rearrange the exception hierarchy slightly for the better. As it currently stands, all exceptions in the built-in namespace inherit from Exception. This is a problem since this includes two exceptions (KeyboardInterrupt and SystemExit) that often need to be excepted from the application's exception handling: the default behavior of shutting the interpreter down with resp. without a traceback is usually more desirable than whatever the application might do (with the possible exception of applications that emulate Python's interactive command loop with ``>>>`` prompt). Changing it so that these two exceptions inherit from the common superclass instead of Exception will make it easy for people to write ``except`` clauses that are not overreaching and not catch exceptions that should propagate up. This PEP is based on previous work done for PEP 348 [#pep348]_. Requiring a Common Superclass ============================= This PEP proposes introducing a new exception named BaseException that is a new-style class and has a single attribute, ``message`` (that will cause the deprecation of the existing ``args`` attribute) Below is the code as the exception will work in Python 3.0 (how it will work in Python 2.x is covered in the `Transition Plan`_ section):: class BaseException(object): """Superclass representing the base of the exception hierarchy. Provides a 'message' attribute that contains either the single argument to the constructor or the empty string. This attribute is used in both the string and unicode representation for the exception. This is so that it provides the extra details in the traceback. """ def __init__(self, message=''): """Set the 'message' attribute'""" self.message = message def __str__(self): """Return the str of 'message'""" return str(self.message) def __unicode__(self): """Return the unicode of 'message'""" return unicode(self.message) def __repr__(self): return "%s(%s)" % (self.__class__.__name__, repr(self.message)) The ``message`` attribute will contain either the first argument passed in at instantiation of the object or the empty string if no arguments were passed in. The attribute is meant to act as a common location to store any extra information that is to be passed along with the exception that goes beyond the location of the exception within the exception hierarchy and the exception's type. No restriction is placed upon what may be passed in for ``messsage``. This provides backwards-compatibility with how the arguments passed into Exception have no restrictions. The ``args`` attribute is deprecated. While allowing multiple arguments to be passed can be helpful, it is in no way essential. It also does not make it clear which argument is going to be represented by the ``__str__`` method. Restricting initialization to accepting a single argument keeps the API simple and clear. This also means providing a ``__getitem__`` method is unneeded for exceptions and thus will be deprecated as well. The ``raise`` statement will be changed to require that any object passed to it must inherit from BaseException. This will make sure that all exceptions fall within a single hierarchy that is anchored at BaseException [#hierarchy-good]_. This also guarantees a basic interface that is inherited from BaseException. The change to ``raise`` will be enforced starting in Python 3.0 (see the `Transition Plan`_ below). With BaseException being the root of the exception hierarchy, Exception will now inherit from it. Exception Hierarchy Changes =========================== With the exception hierarchy now even more important since it has a basic root, a change to the existing hierarchy is called for. As it stands now, if one wants to catch all exceptions that signal an error *and* do not mean the interpreter should be allowed to exit, you must specify all but two exceptions specifically in an ``except`` clause or catch the two exceptions separately and then re-raise them and have all other exceptions fall through to a bare ``except`` clause:: except (KeyboardInterrupt, SystemExit): raise except: ... That is needlessly explicit. This PEP proposes moving KeyboardInterrupt and SystemExit to inherit directly from BaseException. :: - BaseException |- KeyboardInterrupt |- SystemExit |- Exception |- (all other current built-in exceptions) Doing this makes catching Exception more reasonable. It would catch only exceptions that signify errors. Exceptions that signal that the intepreter should exit will not be caught and thus be allowed to propagate up and allow the interpreter to terminate. KeyboardInterrupt has been moved since users typically expect an application to exit when the press the interrupt key (usually Ctrl-C). If people have overly broad ``except`` clauses the expected behaviour does not occur. SystemExit has been moved for similar reasons. Since the exception is raised when ``sys.exit()`` is called the interpreter should normally be allowed to terminate. Unfortunately overly broad ``except`` clauses can prevent the explicitly requested exit from occurring. To make sure that people catch Exception most of the time, various parts of the documentation and tutorials will need to be updated to strongly suggest that Exception be what programmers want to use. Bare ``except`` clauses or catching BaseException directly should be discouraged based on the fact that KeyboardInterrupt and SystemExit almost always should be allowed to propagate up. Transition Plan =============== Since semantic changes to Python are being proposed, a transition plan is needed. The goal is to end up with the new semantics being used in Python 3.0 while providing a smooth transition for 2.x code. All deprecations mentioned in the plan will lead to the removal of the semantics starting in the version following the introduction of the deprecation and the raising of a DeprecationWarning for the version specifically listed. Here is BaseException as implemented in the 2.x series:: class BaseException(object): """Superclass representing the base of the exception hierarchy. Provides a 'message' attribute that contains any single argument passed in during instantiation. If more than one argument is passed, it is set to the empty string. It is meant to represent any message (usually some text) that should be printed out with the traceback. Unfortunately, for backwards-compatibility, the 'args' attribute (discussed below) is used for printing out to tracebacks. The 'args' attribute and __getitem__ method are provided for backwards-compatibility and will be deprecated at some point. """ def __init__(self, *args): """Set 'message' and 'args' attribute. 'args' will eventually be deprecated. But it is still used when printing out tracebacks for backwards-compatibility. Once 'args' is removed, though, 'message' will be used instead. """ self.args = args self.message = args[0] if args else '' def __str__(self): """Return the str of args[0] or args, depending on length. Once 'args' has been removed, 'message' will be used exclusively for the str representation for exceptions. """ return str(self.args[0] if len(self.args) <= 1 else self.args) def __unicode__(self): """Return the unicode of args[0] or args, depending on length. Once 'args' has been removed, 'message' will be used exclusively for the unicode representation of exceptions. """ return unicode(self.args[0] if len(self.args) <= 1 else self.args) def __repr__(self): func_args = repr(self.args) if self.args else "()" return self.__class__.__name__ + func_args def __getitem__(self, index): """Index into arguments passed in during instantiation. Provided for backwards-compatibility and will be deprecated. """ return self.args[index] Deprecation of features in Python 2.9 is optional. This is because it is not known at this time if Python 2.9 (which is slated to be the last version in the 2.x series) will actively deprecate features that will not be in 3.0 . It is conceivable that no deprecation warnings will be used in 2.9 since there could be such a difference between 2.9 and 3.0 that it would make 2.9 too "noisy" in terms of warnings. Thus the proposed deprecation warnings for Python 2.9 will be revisited when development of that version begins to determine if they are still desired. * Python 2.5 - all standard exceptions become new-style classes - introduce BaseException - Exception, KeyboardInterrupt, and SystemExit inherit from BaseException - deprecate raising string exceptions * Python 2.6 - deprecate catching string exceptions * Python 2.7 - deprecate raising exceptions that do not inherit from BaseException * Python 2.8 - deprecate catching exceptions that do not inherit from BaseException * Python 2.9 - deprecate ``args`` and ``__getitem__`` (optional) * Python 3.0 - drop everything that was deprecated above: + drop string exceptions (could do this sooner?) + all exceptions must inherit from BaseException + drop ``args`` and ``__getitem__`` Implementation ============== The initial implementation of this PEP has been checked into Python 2.5 . References ========== .. [#pep348] PEP 348 (Exception Reorganization for Python 3.0) http://www.python.org/peps/pep-0348.html .. [#hierarchy-good] python-dev Summary for 2004-08-01 through 2004-08-15 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 .. [#SF_1104669] SF patch #1104669 (new-style exceptions) http://www.python.org/sf/1104669 Copyright ========= This document has been placed in the public domain. .. Local Variables: mode: indented-text indent-tabs-mode: nil sentence-end-double-space: t fill-column: 70 End: