editorial tweaks

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
+since it has been intended since at least Python 1.5, when the
-exception types were changed to classes [1]_.
+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
+presence of two kinds of exception complicates the language without
-compensation.  Instance exceptions are superior because, for example,
+any compensation.  Instance exceptions are superior because, for
+example,
 
-*   the class-instance relationship more naturally expresses the
+* the class-instance relationship more naturally expresses the
-    relationship between the exception type and value,
+  relationship between the exception type and value,
 
-*   they can be organized naturally using superclass-subclass
+* they can be organized naturally using superclass-subclass
-    relationships, and
+  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 [...]
+    called the "compatibility forms" of the raise statement [...]  The
-    The motivation for introducing the compatibility forms was to allow
+    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
+exception type is not a string in any version of the software which
-code must support -- there is no good reason to instantiate implicitly,
+the code must support -- there is no good reason to instantiate
-and it is clearer not to.  For example:
+implicitly, and it is clearer not to.  For example:
 
-1.  In the code ::
+1. In the code ::
 
-        try:
+       try:
-            raise MyError, raised
+           raise MyError, raised
-        except MyError, caught:
+       except MyError, caught:
-            pass
+           pass
 
-    the syntactic parallel between the ``raise`` and ``except``
+   the syntactic parallel between the ``raise`` and ``except``
-    statements strongly suggests that ``raised`` and ``caught`` refer
+   statements strongly suggests that ``raised`` and ``caught`` refer
-    to the same object.  For string exceptions this actually is the
+   to the same object.  For string exceptions this actually is the
-    case, but for instance exceptions it is not.
+   case, but for instance exceptions it is not.
 
-2.  When instantiation is implicit, it is not obvious when it occurs,
+2. When instantiation is implicit, it is not obvious when it occurs,
-    for example, whether it occurs when the exception is raised or when
+   for example, whether it occurs when the exception is raised or when
-    it is caught.  Since it actually happens at the ``raise``, the code
+   it is caught.  Since it actually happens at the ``raise``, the code
-    should say so.
+   should say so.
 
-    (Note that at the level of the C API, an exception can be "raised"
+   (Note that at the level of the C API, an exception can be "raised"
-    and "caught" without being instantiated; this is used as an
+   and "caught" without being instantiated; this is used as an
-    optimization by, for example, ``PyIter_Next``.  But in Python, no
+   optimization by, for example, ``PyIter_Next``.  But in Python, no
-    such optimization is or should be available.)
+   such optimization is or should be available.)
 
-3.  An implicitly instantiating ``raise`` statement with no arguments,
+3. An implicitly instantiating ``raise`` statement with no arguments,
-    such as ::
+   such as ::
 
        raise MyError
 
-    simply does not do what it says: it does not raise the named
+   simply does not do what it says: it does not raise the named
-    object.
+   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
+   conflates classes and instances, creating a possible source of
-    confusion for beginners.  (Moreover, it is not clear that the
+   confusion for beginners.  (Moreover, it is not clear that the
-    interpreter could distinguish between a new-style class and an
+   interpreter could distinguish between a new-style class and an
-    instance of such a class, so implicit instantiation may be an
+   instance of such a class, so implicit instantiation may be an
-    obstacle to any future plan to let exceptions be new-style
+   obstacle to any future plan to let exceptions be new-style
-    objects.)
+   objects.)
 
-In short, implicit instantiation has no advantages other than backwards
+In short, implicit instantiation has no advantages other than
-compatibility, and so should be phased out along with what it exists to
+backwards compatibility, and so should be phased out along with what
-ensure compatibility with, namely, string exceptions.
+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 exception type, and the instance itself is the exception value.
-the raised object is not an instance -- for example, if it is a class
+If the raised object is not an instance -- for example, if it is a
-or string -- a ``TypeError`` is raised.
+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
+to be issued to point out uses of ``raise`` which will become
-under the proposed changes.
+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
+which the first expression evaluates to a string.  The message for
-warning is::
+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
+should be added at the top of the module.  Note that adding this
-statement also turns the other two warnings into errors, so the changes
+future statement also turns the other two warnings into errors, so the
-described in the previous examples must also be applied.
+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
+implicitly instantiates is not executed in production or testing
-the phase-in period for this PEP.  In that case, it will not issue any
+during the phase-in period for this PEP.  In that case, it will not
-warnings, but will instead suddenly fail one day in Python 3.0 or a
+issue any warnings, but will instead suddenly fail one day in Python
-subsequent version.  (The failure is that the wrong exception gets
+3.0 or a subsequent version.  (The failure is that the wrong exception
-raised, namely a ``TypeError`` complaining about the arguments to
+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