CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="color-scheme" content="light dark"> <title>PEP 352 – Required Superclass for Exceptions | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0352/"> <link rel="stylesheet" href="../_static/style.css" type="text/css"> <link rel="stylesheet" href="../_static/mq.css" type="text/css"> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light"> <link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark"> <link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss"> <meta property="og:title" content='PEP 352 – Required Superclass for Exceptions | peps.python.org'> <meta property="og:description" content="In Python 2.4 and before, any (classic) class can be raised as an exception. The plan for 2.5 was to allow new-style classes, but this makes the problem worse – it would mean any class (or instance) can be raised! This is a problem as it prevents any g..."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0352/"> <meta property="og:site_name" content="Python Enhancement Proposals (PEPs)"> <meta property="og:image" content="https://peps.python.org/_static/og-image.png"> <meta property="og:image:alt" content="Python PEPs"> <meta property="og:image:width" content="200"> <meta property="og:image:height" content="200"> <meta name="description" content="In Python 2.4 and before, any (classic) class can be raised as an exception. The plan for 2.5 was to allow new-style classes, but this makes the problem worse – it would mean any class (or instance) can be raised! This is a problem as it prevents any g..."> <meta name="theme-color" content="#3776ab"> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all"> <title>Following system colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="9"></circle> <path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path> </svg> </symbol> <symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all"> <title>Selected dark colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <path stroke="none" d="M0 0h24v24H0z" fill="none"></path> <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path> </svg> </symbol> <symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all"> <title>Selected light colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="5"></circle> <line x1="12" y1="1" x2="12" y2="3"></line> <line x1="12" y1="21" x2="12" y2="23"></line> <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> <line x1="1" y1="12" x2="3" y2="12"></line> <line x1="21" y1="12" x2="23" y2="12"></line> <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> </svg> </symbol> </svg> <script> document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto" </script> <section id="pep-page-section"> <header> <h1>Python Enhancement Proposals</h1> <ul class="breadcrumbs"> <li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li> <li><a href="../pep-0000/">PEP Index</a> » </li> <li>PEP 352</li> </ul> <button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())"> <svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg> Toggle light / dark / auto colour theme </button> </header> <article> <section id="pep-content"> <h1 class="page-title">PEP 352 – Required Superclass for Exceptions</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author:</dt> <dd class="field-odd">Brett Cannon, Guido van Rossum</dd> <dt class="field-even">Status:</dt> <dd class="field-even"><abbr title="Accepted and implementation complete, or no longer active">Final</abbr></dd> <dt class="field-odd">Type:</dt> <dd class="field-odd"><abbr title="Normative PEP with a new feature for Python, implementation change for CPython or interoperability standard for the ecosystem">Standards Track</abbr></dd> <dt class="field-even">Created:</dt> <dd class="field-even">27-Oct-2005</dd> <dt class="field-odd">Python-Version:</dt> <dd class="field-odd">2.5</dd> <dt class="field-even">Post-History:</dt> <dd class="field-even"></dd> </dl> <hr class="docutils" /> <section id="contents"> <details><summary>Table of Contents</summary><ul class="simple"> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#requiring-a-common-superclass">Requiring a Common Superclass</a></li> <li><a class="reference internal" href="#exception-hierarchy-changes">Exception Hierarchy Changes</a></li> <li><a class="reference internal" href="#transition-plan">Transition Plan</a></li> <li><a class="reference internal" href="#retracted-ideas">Retracted Ideas</a></li> <li><a class="reference internal" href="#references">References</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> </details></section> <section id="abstract"> <h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2> In Python 2.4 and before, any (classic) class can be raised as an exception. The plan for 2.5 was to allow new-style classes, but this makes the problem worse – it would mean any class (or instance) can be raised! This is a problem as 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. It also leads to a known hierarchy for all exceptions to adhere to. 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 <code class="docutils literal notranslate">except BaseException:</code> instead of <code class="docutils literal notranslate">except *:</code>. <a class="footnote-reference brackets" href="#hierarchy-good" id="id1">[1]</a> 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 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 <code class="docutils literal notranslate">>>></code> prompt). Changing it so that these two exceptions inherit from the common superclass instead of Exception will make it easy for people to write <code class="docutils literal notranslate">except</code> clauses that are not overreaching and not catch exceptions that should propagate up. This PEP is based on previous work done for <a class="pep reference internal" href="../pep-0348/" title="PEP 348 – Exception Reorganization for Python 3.0">PEP 348</a>. </section> <section id="requiring-a-common-superclass"> <h2><a class="toc-backref" href="#requiring-a-common-superclass" role="doc-backlink">Requiring a Common Superclass</a></h2> This PEP proposes introducing a new exception named BaseException that is a new-style class and has a single attribute, <code class="docutils literal notranslate">args</code>. 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 <a class="reference internal" href="#transition-plan">Transition Plan</a> section): <div class="highlight-default notranslate"><div class="highlight"><pre>class BaseException(object): """Superclass representing the base of the exception hierarchy. Provides an 'args' attribute that contains all arguments passed to the constructor. Suggested practice, though, is that only a single string argument be passed to the constructor. """ def __init__(self, *args): self.args = args def __str__(self): if len(self.args) == 1: return str(self.args[0]) else: return str(self.args) def __repr__(self): return "%s(*%s)" % (self.__class__.__name__, repr(self.args)) </pre></div> </div> No restriction is placed upon what may be passed in for <code class="docutils literal notranslate">args</code> for backwards-compatibility reasons. In practice, though, only a single string argument should be used. This keeps the string representation of the exception to be a useful message about the exception that is human-readable; this is why the <code class="docutils literal notranslate">__str__</code> method special-cases on length-1 <code class="docutils literal notranslate">args</code> value. Including programmatic information (e.g., an error code number) should be stored as a separate attribute in a subclass. The <code class="docutils literal notranslate">raise</code> 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 <a class="footnote-reference brackets" href="#hierarchy-good" id="id2">[1]</a>. This also guarantees a basic interface that is inherited from BaseException. The change to <code class="docutils literal notranslate">raise</code> will be enforced starting in Python 3.0 (see the <a class="reference internal" href="#transition-plan">Transition Plan</a> below). With BaseException being the root of the exception hierarchy, Exception will now inherit from it. </section> <section id="exception-hierarchy-changes"> <h2><a class="toc-backref" href="#exception-hierarchy-changes" role="doc-backlink">Exception Hierarchy Changes</a></h2> 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 <code class="docutils literal notranslate">except</code> clause or catch the two exceptions separately and then re-raise them and have all other exceptions fall through to a bare <code class="docutils literal notranslate">except</code> clause: <div class="highlight-default notranslate"><div class="highlight"><pre>except (KeyboardInterrupt, SystemExit): raise except: ... </pre></div> </div> That is needlessly explicit. This PEP proposes moving KeyboardInterrupt and SystemExit to inherit directly from BaseException. <div class="highlight-default notranslate"><div class="highlight"><pre>- BaseException |- KeyboardInterrupt |- SystemExit |- Exception |- (all other current built-in exceptions) </pre></div> </div> Doing this makes catching Exception more reasonable. It would catch only exceptions that signify errors. Exceptions that signal that the interpreter 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 they press the interrupt key (usually Ctrl-C). If people have overly broad <code class="docutils literal notranslate">except</code> clauses the expected behaviour does not occur. SystemExit has been moved for similar reasons. Since the exception is raised when <code class="docutils literal notranslate">sys.exit()</code> is called the interpreter should normally be allowed to terminate. Unfortunately overly broad <code class="docutils literal notranslate">except</code> 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 <code class="docutils literal notranslate">except</code> clauses or catching BaseException directly should be discouraged based on the fact that KeyboardInterrupt and SystemExit almost always should be allowed to propagate up. </section> <section id="transition-plan"> <h2><a class="toc-backref" href="#transition-plan" role="doc-backlink">Transition Plan</a></h2> 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 initial deprecation. Here is BaseException as implemented in the 2.x series: <div class="highlight-default notranslate"><div class="highlight"><pre>class BaseException(object): """Superclass representing the base of the exception hierarchy. The __getitem__ method is provided for backwards-compatibility and will be deprecated at some point. The 'message' attribute is also deprecated. """ def __init__(self, *args): self.args = args def __str__(self): return str(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] def _get_message(self): """Method for 'message' property.""" warnings.warn("the 'message' attribute has been deprecated " "since Python 2.6") return self.args[0] if len(args) == 1 else '' message = property(_get_message, doc="access the 'message' attribute; " "deprecated and provided only for " "backwards-compatibility") </pre></div> </div> 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. <ul class="simple"> <li>Python 2.5 [done]<ul> <li>all standard exceptions become new-style classes [done]</li> <li>introduce BaseException [done]</li> <li>Exception, KeyboardInterrupt, and SystemExit inherit from BaseException [done]</li> <li>deprecate raising string exceptions [done]</li> </ul> </li> <li>Python 2.6 [done]<ul> <li>deprecate catching string exceptions [done]</li> <li>deprecate <code class="docutils literal notranslate">message</code> attribute (see <a class="reference internal" href="#retracted-ideas">Retracted Ideas</a>) [done]</li> </ul> </li> <li>Python 2.7 [done]<ul> <li>deprecate raising exceptions that do not inherit from BaseException</li> </ul> </li> <li>Python 3.0 [done]<ul> <li>drop everything that was deprecated above:<ul> <li>string exceptions (both raising and catching) [done]</li> <li>all exceptions must inherit from BaseException [done]</li> <li>drop <code class="docutils literal notranslate">__getitem__</code>, <code class="docutils literal notranslate">message</code> [done]</li> </ul> </li> </ul> </li> </ul> </section> <section id="retracted-ideas"> <h2><a class="toc-backref" href="#retracted-ideas" role="doc-backlink">Retracted Ideas</a></h2> A previous version of this PEP that was implemented in Python 2.5 included a ‘message’ attribute on BaseException. Its purpose was to begin a transition to BaseException accepting only a single argument. This was to tighten the interface and to force people to use attributes in subclasses to carry arbitrary information with an exception instead of cramming it all into <code class="docutils literal notranslate">args</code>. Unfortunately, while implementing the removal of the <code class="docutils literal notranslate">args</code> attribute in Python 3.0 at the PyCon 2007 sprint <a class="footnote-reference brackets" href="#pycon2007-sprint-email" id="id3">[3]</a>, it was discovered that the transition was very painful, especially for C extension modules. It was decided that it would be better to deprecate the <code class="docutils literal notranslate">message</code> attribute in Python 2.6 (and remove it in Python 2.7 and Python 3.0) and consider a more long-term transition strategy in Python 3.0 to remove multiple-argument support in BaseException in preference of accepting only a single argument. Thus the introduction of <code class="docutils literal notranslate">message</code> and the original deprecation of <code class="docutils literal notranslate">args</code> has been retracted. </section> <section id="references"> <h2><a class="toc-backref" href="#references" role="doc-backlink">References</a></h2> <aside class="footnote-list brackets"> <aside class="footnote brackets" id="hierarchy-good" role="doc-footnote"> <dt class="label" id="hierarchy-good">[1] (<a href='#id1'>1</a>, <a href='#id2'>2</a>) </dt> <dd>python-dev Summary for 2004-08-01 through 2004-08-15 <a class="reference external" href="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</a></aside> <aside class="footnote brackets" id="sf-1104669" role="doc-footnote"> <dt class="label" id="sf-1104669">[2]</dt> <dd>SF patch #1104669 (new-style exceptions) <a class="reference external" href="https://bugs.python.org/issue1104669">https://bugs.python.org/issue1104669</a></aside> <aside class="footnote brackets" id="pycon2007-sprint-email" role="doc-footnote"> <dt class="label" id="pycon2007-sprint-email">[<a href="#id3">3</a>]</dt> <dd>python-3000 email (“How far to go with cleaning up exceptions”) <a class="reference external" href="https://mail.python.org/pipermail/python-3000/2007-March/005911.html">https://mail.python.org/pipermail/python-3000/2007-March/005911.html</a></aside> </aside> </section> <section id="copyright"> <h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2> This document has been placed in the public domain. </section> </section> <hr class="docutils" /> Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0352.rst">https://github.com/python/peps/blob/main/peps/pep-0352.rst</a> Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0352.rst">2023-09-09 17:39:29 GMT</a> </article> <nav id="pep-sidebar"> <h2>Contents</h2> <ul> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#requiring-a-common-superclass">Requiring a Common Superclass</a></li> <li><a class="reference internal" href="#exception-hierarchy-changes">Exception Hierarchy Changes</a></li> <li><a class="reference internal" href="#transition-plan">Transition Plan</a></li> <li><a class="reference internal" href="#retracted-ideas">Retracted Ideas</a></li> <li><a class="reference internal" href="#references">References</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> <a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0352.rst">Page Source (GitHub)</a> </nav> </section> <script src="../_static/colour_scheme.js"></script> <script src="../_static/wrap_tables.js"></script> <script src="../_static/sticky_banner.js"></script> </body> </html>