[Python-checkins] python/nondist/peps pep-0317.txt,1.1,1.2

Sun, 08 Jun 2003 21:43:42 -0700

Update of /cvsroot/python/python/nondist/peps
In directory sc8-pr-cvs1:/tmp/cvs-serv6601

Modified Files:
	pep-0317.txt 
Log Message:
editorial tweaks

Index: pep-0317.txt
===================================================================
RCS file: /cvsroot/python/python/nondist/peps/pep-0317.txt,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** pep-0317.txt	9 Jun 2003 04:04:31 -0000	1.1
--- pep-0317.txt	9 Jun 2003 04:43:39 -0000	1.2
***************
*** 18,22 ****
      is recommended (i.e. make an explicit call to the constructor)."

!                                     -- Guido van Rossum, in 1997 [1]_

  This PEP proposes the formal deprecation and eventual elimination of
--- 18,22 ----
      is recommended (i.e. make an explicit call to the constructor)."

!     -- Guido van Rossum, in 1997 [1]_

  This PEP proposes the formal deprecation and eventual elimination of
***************
*** 50,72 ****
  ==========

- 
  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]_.

  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,

! *   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 encapsulate error-reporting behaviour (for example).

--- 50,72 ----
  ==========

  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]_.

  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,

! * 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 encapsulate error-reporting behaviour (for example).

***************
*** 79,84 ****
      "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
      backward compatibility with old code that raised a standard
      exception."
--- 79,84 ----
      "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
      backward compatibility with old code that raised a standard
      exception."
***************
*** 93,145 ****

  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:

! 1.  In the code ::

!         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.

! 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.)

! 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.

! 4.  The equivalence of ::

!         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.)

! 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.

--- 93,145 ----

  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:

! 1. In the code ::

!        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.

! 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.)

! 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.

! 4. The equivalence of ::

!        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.)

! 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.

***************
*** 166,172 ****

  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.

  If the substituted traceback is not ``None``, it must be a traceback
--- 166,172 ----

  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.

  If the substituted traceback is not ``None``, it must be a traceback
***************
*** 179,187 ****
  =======================

- 
  Migration Plan
  --------------

- 
  Future Statement
  ''''''''''''''''
--- 179,185 ----
***************
*** 204,213 ****

  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.

  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::

      raising strings will be impossible in the future
--- 202,211 ----

  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.

  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::

      raising strings will be impossible in the future
***************
*** 233,237 ****
  --------

- 
  Code Using Implicit Instantiation
  '''''''''''''''''''''''''''''''''
--- 231,234 ----
***************
*** 277,282 ****
      raise MyError, 'spam', mytraceback

! will issue a warning when compiled.  The statement should be changed to
! ::

      raise MyError('spam'), mytraceback
--- 274,279 ----
      raise MyError, 'spam', mytraceback

! will issue a warning when compiled.  The statement should be changed
! to ::

      raise MyError('spam'), mytraceback
***************
*** 286,292 ****
      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.

  The special case ::
--- 283,289 ----
      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.

  The special case ::
***************
*** 304,312 ****

  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
  ``raise``, instead of the exception intended.)

--- 301,309 ----

  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
  ``raise``, instead of the exception intended.)