PEP: 3109 Title: Raising Exceptions in Python 3000 Version: $Revision$ Last-Modified: $Date$ Author: Collin Winter Status: Final Type: Standards Track Content-Type: text/x-rst Created: 19-Jan-2006 Python-Version: 3.0 Post-History: Abstract ======== This PEP introduces changes to Python's mechanisms for raising exceptions intended to reduce both line noise and the size of the language. Rationale ========= One of Python's guiding maxims is :pep:`"there should be one -- and preferably only one -- obvious way to do it" <20>`. Python 2.x's ``raise`` statement violates this principle, permitting multiple ways of expressing the same thought. For example, these statements are equivalent: :: raise E, V raise E(V) There is a third form of the ``raise`` statement, allowing arbitrary tracebacks to be attached to an exception [#grammar]_: :: raise E, V, T where T is a traceback. As specified in :pep:`344`, exception objects in Python 3.x will possess a ``__traceback__`` attribute, admitting this translation of the three-expression ``raise`` statement: :: raise E, V, T is translated to :: e = E(V) e.__traceback__ = T raise e Using these translations, we can reduce the ``raise`` statement from four forms to two: 1. ``raise`` (with no arguments) is used to re-raise the active exception in an ``except`` suite. 2. ``raise EXCEPTION`` is used to raise a new exception. This form has two sub-variants: ``EXCEPTION`` may be an exception class or an instance of an exception class; valid exception classes are BaseException and its subclasses (:pep:`352`). If ``EXCEPTION`` is a subclass, it will be called with no arguments to obtain an exception instance. To raise anything else is an error. There is a further, more tangible benefit to be obtained through this consolidation, as noted by A.M. Kuchling [#amk-line-noise]_. :: PEP 8 doesn't express any preference between the two forms of raise statements: raise ValueError, 'blah' raise ValueError("blah") I like the second form better, because if the exception arguments are long or include string formatting, you don't need to use line continuation characters because of the containing parens. The BDFL has concurred [#guido-declaration]_ and endorsed the consolidation of the several ``raise`` forms. Grammar Changes =============== In Python 3, the grammar for ``raise`` statements will change from [#grammar]_ :: raise_stmt: 'raise' [test [',' test [',' test]]] to :: raise_stmt: 'raise' [test] Changes to Builtin Types ======================== Because of its relation to exception raising, the signature for the ``throw()`` method on generator objects will change, dropping the optional second and third parameters. The signature thus changes (:pep:`342`) from :: generator.throw(E, [V, [T]]) to :: generator.throw(EXCEPTION) Where ``EXCEPTION`` is either a subclass of ``BaseException`` or an instance of a subclass of ``BaseException``. Semantic Changes ================ In Python 2, the following ``raise`` statement is legal :: raise ((E1, (E2, E3)), E4), V The interpreter will take the tuple's first element as the exception type (recursively), making the above fully equivalent to :: raise E1, V As of Python 3.0, support for raising tuples like this will be dropped. This change will bring ``raise`` statements into line with the ``throw()`` method on generator objects, which already disallows this. Compatibility Issues ==================== All two- and three-expression ``raise`` statements will require modification, as will all two- and three-expression ``throw()`` calls on generators. Fortunately, the translation from Python 2.x to Python 3.x in this case is simple and can be handled mechanically by Guido van Rossum's 2to3 utility [#2to3]_ using the ``raise`` and ``throw`` fixers ([#raise-fixer]_, [#throw-fixer]_). The following translations will be performed: 1. Zero- and one-expression ``raise`` statements will be left intact. 2. Two-expression ``raise`` statements will be converted from :: raise E, V to :: raise E(V) Two-expression ``throw()`` calls will be converted from :: generator.throw(E, V) to :: generator.throw(E(V)) See point #5 for a caveat to this transformation. 3. Three-expression ``raise`` statements will be converted from :: raise E, V, T to :: e = E(V) e.__traceback__ = T raise e Three-expression ``throw()`` calls will be converted from :: generator.throw(E, V, T) to :: e = E(V) e.__traceback__ = T generator.throw(e) See point #5 for a caveat to this transformation. 4. Two- and three-expression ``raise`` statements where ``E`` is a tuple literal can be converted automatically using ``2to3``'s ``raise`` fixer. ``raise`` statements where ``E`` is a non-literal tuple, e.g., the result of a function call, will need to be converted manually. 5. Two- and three-expression ``raise`` statements where ``E`` is an exception class and ``V`` is an exception instance will need special attention. These cases break down into two camps: 1. ``raise E, V`` as a long-hand version of the zero-argument ``raise`` statement. As an example, assuming F is a subclass of E :: try: something() except F as V: raise F(V) except E as V: handle(V) This would be better expressed as :: try: something() except F: raise except E as V: handle(V) 2. ``raise E, V`` as a way of "casting" an exception to another class. Taking an example from distutils.compiler.unixcompiler :: try: self.spawn(pp_args) except DistutilsExecError as msg: raise CompileError(msg) This would be better expressed as :: try: self.spawn(pp_args) except DistutilsExecError as msg: raise CompileError from msg Using the ``raise ... from ...`` syntax introduced in :pep:`344`. Implementation ============== This PEP was implemented in revision 57783 [#r57783]_. References ========== .. [#grammar] http://docs.python.org/reference/simple_stmts.html#raise .. [#amk-line-noise] https://mail.python.org/pipermail/python-dev/2005-August/055187.html .. [#guido-declaration] https://mail.python.org/pipermail/python-dev/2005-August/055190.html .. [#2to3] http://svn.python.org/view/sandbox/trunk/2to3/ .. [#raise-fixer] http://svn.python.org/view/sandbox/trunk/2to3/fixes/fix_raise.py .. [#throw-fixer] http://svn.python.org/view/sandbox/trunk/2to3/fixes/fix_throw.py .. [#r57783] http://svn.python.org/view/python/branches/py3k/Include/?rev=57783&view=rev 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 coding: utf-8 End: