[Python-checkins] python/dist/src/Doc/ref ref4.tex, 1.37, 1.38 ref7.tex, 1.42, 1.43

[mwh at users.sourceforge.net]

Update of /cvsroot/python/python/dist/src/Doc/ref
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv23191

Modified Files:
	ref4.tex ref7.tex 
Log Message:
Updates to the exceptions documentation (this is my patch #1156102).


Index: ref4.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/ref/ref4.tex,v
retrieving revision 1.37
retrieving revision 1.38
diff -u -d -r1.37 -r1.38
--- ref4.tex	11 Dec 2003 19:45:53 -0000	1.37
+++ ref4.tex	4 Mar 2005 14:33:32 -0000	1.38
@@ -182,16 +182,20 @@
 \exception{SystemExit}\withsubitem{(built-in
 exception)}{\ttindex{SystemExit}}.
 
-Exceptions are identified by class instances.
-Selection of a matching except clause is based on object identity.
-The \keyword{except} clause must reference the same class or a base
-class of it.
+Exceptions are identified by class instances.  The \keyword{except}
+clause is selected depending on the class of the instance: it must
+reference the class of the instance or a base class thereof.  The
+instance can be received by the handler and can carry additional
+information about the exceptional condition.
 
-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.
+Exceptions can also be identified by strings, in which case the
+\keyword{except} clause is selected by object identity.  An arbitrary
+value can be raised along with the identifying string which can be
+passed to the handler.
+
+\deprecated{2.5}{String exceptions should not be used in new code.
+They will not be supported in a future version of Python.  Old code
+should be rewritten to use class exceptions instead.}
 
 \begin{notice}[warning]
 Messages to exceptions are not part of the Python API.  Their contents may

Index: ref7.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/ref/ref7.tex,v
retrieving revision 1.42
retrieving revision 1.43
diff -u -d -r1.42 -r1.43
--- ref7.tex	2 Nov 2004 19:18:20 -0000	1.42
+++ ref7.tex	4 Mar 2005 14:33:32 -0000	1.43
@@ -223,11 +223,11 @@
 except clause with an expression, that expression is evaluated, and the
 clause matches the exception if the resulting object is ``compatible''
 with the exception.  An object is compatible with an exception if it
-is either the object that identifies the exception, or (for exceptions
-that are classes) it is a base class of the exception, or it is a
-tuple containing an item that is compatible with the exception.  Note
-that the object identities must match, i.e. it must be the same
-object, not just an object with the same value.
+is the class or a base class of the exception object, a tuple
+containing an item compatible with the exception, or, in the
+(deprecated) case of string exceptions, is the raised string itself
+(note that the object identities must match, i.e. it must be the same
+string object, not just a string with the same value).
 \kwindex{except}
 
 If no except clause matches the exception, the search for an exception
@@ -239,14 +239,14 @@
 on the call stack (it is treated as if the entire \keyword{try} statement
 raised the exception).
 
-When a matching except clause is found, the exception's parameter is
-assigned to the target specified in that except clause, if present,
-and the except clause's suite is executed.  All except clauses must
-have an executable block.  When the end of this block
-is reached, execution continues normally after the entire try
-statement.  (This means that if two nested handlers exist for the same
-exception, and the exception occurs in the try clause of the inner
-handler, the outer handler will not handle the exception.)
+When a matching except clause is found, the exception is assigned to
+the target specified in that except clause, if present, and the except
+clause's suite is executed.  All except clauses must have an
+executable block.  When the end of this block is reached, execution
+continues normally after the entire try statement.  (This means that
+if two nested handlers exist for the same exception, and the exception
+occurs in the try clause of the inner handler, the outer handler will
+not handle the exception.)
 
 Before an except clause's suite is executed, details about the
 exception are assigned to three variables in the