[Python-checkins] python/dist/src/Doc/ref ref4.tex,1.31,1.32 ref6.tex,1.53,1.54

[fdrake@users.sourceforge.net]

Update of /cvsroot/python/python/dist/src/Doc/ref
In directory usw-pr-cvs1:/tmp/cvs-serv9419/ref

Modified Files:
	ref4.tex ref6.tex 
Log Message:
Try to improve the explanation of the "raise" statement and how its arguments
are interpreted.
This closes SF bug #532467.


Index: ref4.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/ref/ref4.tex,v
retrieving revision 1.31
retrieving revision 1.32
diff -C2 -d -r1.31 -r1.32
*** ref4.tex	17 Apr 2002 03:41:50 -0000	1.31
--- ref4.tex	20 Jun 2002 20:55:29 -0000	1.32
***************
*** 193,201 ****
  
  When an exception is raised, an object (maybe \code{None}) is passed
! as the exception's ``parameter'' or ``value''; this object does not
! affect the selection of an exception handler, but is passed to the
! selected exception handler as additional information.  For class
! exceptions, this object must be an instance of the exception class
! being raised.
  
  See also the description of the \keyword{try} statement in section
--- 193,200 ----
  
  When an exception is raised, an object (maybe \code{None}) is passed
! as the exception's \emph{value}; this object does not affect the
! selection of an exception handler, but is passed to the selected
! exception handler as additional information.  For class exceptions,
! this object must be an instance of the exception class being raised.
  
  See also the description of the \keyword{try} statement in section

Index: ref6.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/ref/ref6.tex,v
retrieving revision 1.53
retrieving revision 1.54
diff -C2 -d -r1.53 -r1.54
*** ref6.tex	17 Jun 2002 12:51:57 -0000	1.53
--- ref6.tex	20 Jun 2002 20:55:29 -0000	1.54
***************
*** 508,542 ****
  
  If no expressions are present, \keyword{raise} re-raises the last
! expression that was raised in the current scope.
! 
! Otherwise, \keyword{raise} evaluates its first expression, which must yield
! a string, class, or instance object.  If there is a second expression,
! this is evaluated, else \code{None} is substituted.  If the first
! expression is a class object, then the second expression may be an
! instance of that class or one of its derivatives, and then that
! instance is raised.  If the second expression is not such an instance,
! the given class is instantiated.  The argument list for the
! instantiation is determined as follows: if the second expression is a
! tuple, it is used as the argument list; if it is \code{None}, the
! argument list is empty; otherwise, the argument list consists of a
! single argument which is the second expression.  If the first
! expression is an instance object, the second expression must be
! \code{None}.
  \index{exception}
  \indexii{raising}{exception}
  
! If the first object is a string, it then raises the exception
! identified by the first object, with the second one (or \code{None})
! as its parameter.  If the first object is a class or instance,
! it raises the exception identified by the class of the instance
! determined in the previous step, with the instance as
! its parameter.
  
- If a third object is present, and it is not \code{None}, it should be
- a traceback object (see section~\ref{traceback}), and it is
- substituted instead of the current location as the place where the
- exception occurred.  This is useful to re-raise an exception
- transparently in an except clause.
- \obindex{traceback}
  
  
--- 508,549 ----
  
  If no expressions are present, \keyword{raise} re-raises the last
! expression that was active in the current scope.  If no exception has
! been active in the current scope, an exception is raised that
! indicates indicates that this is the error.
  \index{exception}
  \indexii{raising}{exception}
  
! Otherwise, \keyword{raise} evaluates the expressions to get three
! objects, using \code{None} as the value of omitted expressions.  The
! first two objects are used to determine the \emph{type} and
! \emph{value} of the exception.
! 
! If the first object is an instance, the type of the exception is the
! class of the instance, the instance itself if the value, and the
! second object must be \code{None}.
! 
! If the first object is a class, it becomes the type of the exception.
! The second object is used to determine the exception value: If it is
! an instance of the class, the instance becomes the exception value.
! If the second object is a tuple, it is used as the argument list for
! the class constructor; if it is \code{None}, an empty argument list is
! used, and any other object is treated as a single argument to the
! constructor.  The instance so created by calling the constructor is
! used as the exception value.
! 
! If the first object is a string, the string object is the exception
! type, and the second object becomes the exception value.
! 
! If a third object is present and not \code{None}, it must be a
! traceback\obindex{traceback} object (see section~\ref{traceback}), and
! it is substituted instead of the current location as the place where
! the exception occurred.  If the third object is present and not a
! traceback object or \code{None}, a \exception{TypeError} exception is
! raised.  The three-expression form of \keyword{raise} is useful to
! re-raise an exception transparently in an except clause, but
! \keyword{raise} with no expressions should be preferred if the
! exception to be re-raised was the most recently active exception in
! the current scope.