editorial tweaks
This commit is contained in:
David Goodger
parent
6284b30f13
commit
5cf7e0227a
135
pep-0317.txt
135
pep-0317.txt
|
|
@ -17,7 +17,7 @@ Abstract
|
|||
"For clarity in new code, the form ``raise class(argument, ...)``
|
||||
is recommended (i.e. make an explicit call to the constructor)."
|
||||
|
||||
-- Guido van Rossum, in 1997 [1]_
|
||||
-- Guido van Rossum, in 1997 [1]_
|
||||
|
||||
This PEP proposes the formal deprecation and eventual elimination of
|
||||
forms of the ``raise`` statement which implicitly instantiate an
|
||||
|
|
@ -49,25 +49,25 @@ comply with the guidelines of PEP 5 [2]_.)
|
|||
Motivation
|
||||
==========
|
||||
|
||||
|
||||
String Exceptions
|
||||
-----------------
|
||||
|
||||
It is assumed that removing string exceptions will be uncontroversial,
|
||||
since it has been intended since at least Python 1.5, when the standard
|
||||
exception types were changed to classes [1]_.
|
||||
since it has been intended since at least Python 1.5, when the
|
||||
standard exception types were changed to classes [1]_.
|
||||
|
||||
For the record: string exceptions should be removed because the
|
||||
presence of two kinds of exception complicates the language without any
|
||||
compensation. Instance exceptions are superior because, for example,
|
||||
presence of two kinds of exception complicates the language without
|
||||
any compensation. Instance exceptions are superior because, for
|
||||
example,
|
||||
|
||||
* the class-instance relationship more naturally expresses the
|
||||
relationship between the exception type and value,
|
||||
* the class-instance relationship more naturally expresses the
|
||||
relationship between the exception type and value,
|
||||
|
||||
* they can be organized naturally using superclass-subclass
|
||||
relationships, and
|
||||
* they can be organized naturally using superclass-subclass
|
||||
relationships, and
|
||||
|
||||
* they can encapsulate error-reporting behaviour (for example).
|
||||
* they can encapsulate error-reporting behaviour (for example).
|
||||
|
||||
|
||||
Implicit Instantiation
|
||||
|
|
@ -78,8 +78,8 @@ classes makes clear why ``raise`` can instantiate implicitly:
|
|||
|
||||
"The raise statement has been extended to allow raising a class
|
||||
exception without explicit instantiation. The following forms,
|
||||
called the "compatibility forms" of the raise statement [...]
|
||||
The motivation for introducing the compatibility forms was to allow
|
||||
called the "compatibility forms" of the raise statement [...] The
|
||||
motivation for introducing the compatibility forms was to allow
|
||||
backward compatibility with old code that raised a standard
|
||||
exception."
|
||||
|
||||
|
|
@ -92,55 +92,55 @@ would work both on versions of Python in which ``TypeError`` was a
|
|||
string, and on versions in which it was a class.
|
||||
|
||||
When no such consideration obtains -- that is, when the desired
|
||||
exception type is not a string in any version of the software which the
|
||||
code must support -- there is no good reason to instantiate implicitly,
|
||||
and it is clearer not to. For example:
|
||||
exception type is not a string in any version of the software which
|
||||
the code must support -- there is no good reason to instantiate
|
||||
implicitly, and it is clearer not to. For example:
|
||||
|
||||
1. In the code ::
|
||||
1. In the code ::
|
||||
|
||||
try:
|
||||
raise MyError, raised
|
||||
except MyError, caught:
|
||||
pass
|
||||
try:
|
||||
raise MyError, raised
|
||||
except MyError, caught:
|
||||
pass
|
||||
|
||||
the syntactic parallel between the ``raise`` and ``except``
|
||||
statements strongly suggests that ``raised`` and ``caught`` refer
|
||||
to the same object. For string exceptions this actually is the
|
||||
case, but for instance exceptions it is not.
|
||||
the syntactic parallel between the ``raise`` and ``except``
|
||||
statements strongly suggests that ``raised`` and ``caught`` refer
|
||||
to the same object. For string exceptions this actually is the
|
||||
case, but for instance exceptions it is not.
|
||||
|
||||
2. When instantiation is implicit, it is not obvious when it occurs,
|
||||
for example, whether it occurs when the exception is raised or when
|
||||
it is caught. Since it actually happens at the ``raise``, the code
|
||||
should say so.
|
||||
2. When instantiation is implicit, it is not obvious when it occurs,
|
||||
for example, whether it occurs when the exception is raised or when
|
||||
it is caught. Since it actually happens at the ``raise``, the code
|
||||
should say so.
|
||||
|
||||
(Note that at the level of the C API, an exception can be "raised"
|
||||
and "caught" without being instantiated; this is used as an
|
||||
optimization by, for example, ``PyIter_Next``. But in Python, no
|
||||
such optimization is or should be available.)
|
||||
(Note that at the level of the C API, an exception can be "raised"
|
||||
and "caught" without being instantiated; this is used as an
|
||||
optimization by, for example, ``PyIter_Next``. But in Python, no
|
||||
such optimization is or should be available.)
|
||||
|
||||
3. An implicitly instantiating ``raise`` statement with no arguments,
|
||||
such as ::
|
||||
3. An implicitly instantiating ``raise`` statement with no arguments,
|
||||
such as ::
|
||||
|
||||
raise MyError
|
||||
|
||||
simply does not do what it says: it does not raise the named
|
||||
object.
|
||||
simply does not do what it says: it does not raise the named
|
||||
object.
|
||||
|
||||
4. The equivalence of ::
|
||||
4. The equivalence of ::
|
||||
|
||||
raise MyError
|
||||
raise MyError()
|
||||
raise MyError
|
||||
raise MyError()
|
||||
|
||||
conflates classes and instances, creating a possible source of
|
||||
confusion for beginners. (Moreover, it is not clear that the
|
||||
interpreter could distinguish between a new-style class and an
|
||||
instance of such a class, so implicit instantiation may be an
|
||||
obstacle to any future plan to let exceptions be new-style
|
||||
objects.)
|
||||
conflates classes and instances, creating a possible source of
|
||||
confusion for beginners. (Moreover, it is not clear that the
|
||||
interpreter could distinguish between a new-style class and an
|
||||
instance of such a class, so implicit instantiation may be an
|
||||
obstacle to any future plan to let exceptions be new-style
|
||||
objects.)
|
||||
|
||||
In short, implicit instantiation has no advantages other than backwards
|
||||
compatibility, and so should be phased out along with what it exists to
|
||||
ensure compatibility with, namely, string exceptions.
|
||||
In short, implicit instantiation has no advantages other than
|
||||
backwards compatibility, and so should be phased out along with what
|
||||
it exists to ensure compatibility with, namely, string exceptions.
|
||||
|
||||
|
||||
Specification
|
||||
|
|
@ -165,9 +165,9 @@ producing the *substituted traceback*. If no second expression is
|
|||
present, the substituted traceback is ``None``.
|
||||
|
||||
The raised object must be an instance. The class of the instance is
|
||||
the exception type, and the instance itself is the exception value. If
|
||||
the raised object is not an instance -- for example, if it is a class
|
||||
or string -- a ``TypeError`` is raised.
|
||||
the exception type, and the instance itself is the exception value.
|
||||
If the raised object is not an instance -- for example, if it is a
|
||||
class or string -- a ``TypeError`` is raised.
|
||||
|
||||
If the substituted traceback is not ``None``, it must be a traceback
|
||||
object, and it is substituted instead of the current location as the
|
||||
|
|
@ -178,11 +178,9 @@ object nor ``None``, a ``TypeError`` is raised.
|
|||
Backwards Compatibility
|
||||
=======================
|
||||
|
||||
|
||||
Migration Plan
|
||||
--------------
|
||||
|
||||
|
||||
Future Statement
|
||||
''''''''''''''''
|
||||
|
||||
|
|
@ -203,12 +201,12 @@ Warnings
|
|||
''''''''
|
||||
|
||||
Three new warnings [5]_, all of category ``DeprecationWarning``, are
|
||||
to be issued to point out uses of ``raise`` which will become incorrect
|
||||
under the proposed changes.
|
||||
to be issued to point out uses of ``raise`` which will become
|
||||
incorrect under the proposed changes.
|
||||
|
||||
The first warning is issued when a ``raise`` statement is executed in
|
||||
which the first expression evaluates to a string. The message for this
|
||||
warning is::
|
||||
which the first expression evaluates to a string. The message for
|
||||
this warning is::
|
||||
|
||||
raising strings will be impossible in the future
|
||||
|
||||
|
|
@ -232,7 +230,6 @@ These warnings are to appear in Python 2.4, and disappear in Python
|
|||
Examples
|
||||
--------
|
||||
|
||||
|
||||
Code Using Implicit Instantiation
|
||||
'''''''''''''''''''''''''''''''''
|
||||
|
||||
|
|
@ -276,8 +273,8 @@ Code such as ::
|
|||
|
||||
raise MyError, 'spam', mytraceback
|
||||
|
||||
will issue a warning when compiled. The statement should be changed to
|
||||
::
|
||||
will issue a warning when compiled. The statement should be changed
|
||||
to ::
|
||||
|
||||
raise MyError('spam'), mytraceback
|
||||
|
||||
|
|
@ -285,9 +282,9 @@ and the future statement ::
|
|||
|
||||
from __future__ import raise_with_two_args
|
||||
|
||||
should be added at the top of the module. Note that adding this future
|
||||
statement also turns the other two warnings into errors, so the changes
|
||||
described in the previous examples must also be applied.
|
||||
should be added at the top of the module. Note that adding this
|
||||
future statement also turns the other two warnings into errors, so the
|
||||
changes described in the previous examples must also be applied.
|
||||
|
||||
The special case ::
|
||||
|
||||
|
|
@ -303,11 +300,11 @@ A Failure of the Plan
|
|||
'''''''''''''''''''''
|
||||
|
||||
It may occur that a ``raise`` statement which raises a string or
|
||||
implicitly instantiates is not executed in production or testing during
|
||||
the phase-in period for this PEP. In that case, it will not issue any
|
||||
warnings, but will instead suddenly fail one day in Python 3.0 or a
|
||||
subsequent version. (The failure is that the wrong exception gets
|
||||
raised, namely a ``TypeError`` complaining about the arguments to
|
||||
implicitly instantiates is not executed in production or testing
|
||||
during the phase-in period for this PEP. In that case, it will not
|
||||
issue any warnings, but will instead suddenly fail one day in Python
|
||||
3.0 or a subsequent version. (The failure is that the wrong exception
|
||||
gets raised, namely a ``TypeError`` complaining about the arguments to
|
||||
``raise``, instead of the exception intended.)
|
||||
|
||||
Such cases can be made rarer by prolonging the phase-in period; they
|
||||
|
|
|
|||
Loading…
Reference in New Issue