Remove references to string based exceptions in the doc.
indicator is already set, it is cleared first. If the objects are
\NULL, the error indicator is cleared. Do not pass a \NULL{} type
and non-\NULL{} value or traceback. The exception type should be a
- string or class. Do not pass an invalid exception type or value.
+ class. Do not pass an invalid exception type or value.
(Violating these rules will cause subtle problems later.) This call
takes away a reference to each object: you must own a reference to
each object before the call and after the call you no longer own
\begin{cfuncdesc}{PyObject*}{PyErr_Format}{PyObject *exception,
const char *format, \moreargs}
This function sets the error indicator and returns \NULL.
- \var{exception} should be a Python exception (string or class, not
+ \var{exception} should be a Python exception (class, not
an instance). \var{format} should be a string, containing format
codes, similar to \cfunction{printf()}. The \code{width.precision}
before a format code is parsed, but the width part is ignored.
\end{envdesc}
\begin{envdesc}{excdesc}{\p{name}}
- Describe an exception. This may be either a string exception or
- a class exception. In the case of class exceptions, the
+ Describe an exception. In the case of class exceptions, the
constructor parameters are not described; use \env{excclassdesc}
to describe an exception class and its constructor.
\end{envdesc}
\begin{macrodesc}{exindex}{\p{exception}}
Add a reference to an exception named \var{exception}. The
- exception may be either string- or class-based.
+ exception should be class-based.
\end{macrodesc}
\begin{macrodesc}{kwindex}{\p{keyword}}
\modulesynopsis{Standard exception classes.}
-Exceptions can be class objects or string objects. Though most
-exceptions have been string objects in past versions of Python, in
-Python 1.5 and newer versions, all standard exceptions have been
-converted to class objects, and users are encouraged to do the same.
+Exceptions should be class objects.
The exceptions are defined in the module \module{exceptions}. This
module never needs to be imported explicitly: the exceptions are
provided in the built-in namespace as well as the \module{exceptions}
module.
+\begin{notice}
+In past versions of Python string exceptions were supported. In
+Python 1.5 and newer versions, all standard exceptions have been
+converted to class objects and users are encouraged to do the same.
+String exceptions will raise a \code{PendingDeprecationWarning}.
+In future versions, support for string exceptions will be removed.
+
Two distinct string objects with the same value are considered different
exceptions. This is done to force programmers to use exception names
rather than their string value when specifying exception handlers.
The string value of all built-in exceptions is their name, but this is
not a requirement for user-defined exceptions or exceptions defined by
library modules.
+\end{notice}
For class exceptions, in a \keyword{try}\stindex{try} statement with
an \keyword{except}\stindex{except} clause that mentions a particular
containing three \code{None} values is returned. Otherwise, the
values returned are \code{(\var{type}, \var{value},
\var{traceback})}. Their meaning is: \var{type} gets the exception
- type of the exception being handled (a string or class object);
+ type of the exception being handled (a class object);
\var{value} gets the exception parameter (its \dfn{associated value}
or the second argument to \keyword{raise}, which is always a class
instance if the exception type is a class object); \var{traceback}
\exception{SystemExit}\withsubitem{(built-in
exception)}{\ttindex{SystemExit}}.
-Exceptions are identified by string objects or class instances.
-Selection of a matching except clause is based on object identity
-(i.e., two different string objects with the same value represent
-different exceptions!) For string exceptions, the \keyword{except}
-clause must reference the same string object. For class exceptions,
-the \keyword{except} clause must reference the same class or a base
+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
\end{productionlist}
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.
+expression that was active in the current scope. If no exception is
+active in the current scope, an exception is raised indicating this error.
\index{exception}
\indexii{raising}{exception}
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
projects / python / commitdiff