From a2a9888f22a7811938d2f708344e01dfc000841c Mon Sep 17 00:00:00 2001
From: "Michael W. Hudson" <mwh@python.net>
Date: Fri, 4 Mar 2005 14:33:32 +0000
Subject: Updates to the exceptions documentation (this is my patch #1156102).

---
 Doc/ref/ref4.tex | 24 ++++++++++++++----------
 Doc/ref/ref7.tex | 26 +++++++++++++-------------
 2 files changed, 27 insertions(+), 23 deletions(-)

diff --git a/Doc/ref/ref4.tex b/Doc/ref/ref4.tex
index dbd6a2f..6a3a4ef 100644
--- a/Doc/ref/ref4.tex
+++ b/Doc/ref/ref4.tex
@@ -182,16 +182,20 @@ either case, it prints a stack backtrace, except when the exception is
 \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.
-
-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 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.
+
+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
diff --git a/Doc/ref/ref7.tex b/Doc/ref/ref7.tex
index 5e50a74..7459412 100644
--- a/Doc/ref/ref7.tex
+++ b/Doc/ref/ref7.tex
@@ -223,11 +223,11 @@ clause, if present, must be last; it matches any exception.  For an
 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 @@ and a search starts for the new exception in the surrounding code and
 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
-- 
cgit v0.12