diff --git a/pep-0317.txt b/pep-0317.txt index 29e16c32f..fda6b89ea 100644 --- a/pep-0317.txt +++ b/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