Skip to content
Permalink
main
Switch branches/tags

peps/pep-3109.txt

Go to file
 
 
Cannot retrieve contributors at this time
283 lines (189 sloc) 7.04 KB
Raw Blame
PEP: 3109
Title: Raising Exceptions in Python 3000
Version: $Revision$
Last-Modified: $Date$
Author: Collin Winter <collinwinter@google.com>
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: