Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit df3dba0

Browse files
gvanrossumgvanrossum
committed
Documented new exceptions and exception classes.
1 parent 5344d4f commit df3dba0

2 files changed

Lines changed: 234 additions & 40 deletions

File tree

‎Doc/lib/libexcs.tex‎

Lines changed: 117 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,99 @@
11
\section{Built-in Exceptions}
22

3-
Exceptions are string objects. Two distinct string objects with the
4-
same value are different exceptions. This is done to force programmers
5-
to use exception names rather than their string value when specifying
6-
exception handlers. The string value of all built-in exceptions is
7-
their name, but this is not a requirement for user-defined exceptions
8-
or exceptions defined by library modules.
9-
10-
The following exceptions can be generated by the interpreter or
11-
built-in functions. Except where mentioned, they have an `associated
12-
value' indicating the detailed cause of the error. This may be a
13-
string or a tuple containing several items of information (e.g., an
14-
error code and a string explaining the code).
3+
Exceptions can be class objects or string objects. While
4+
traditionally, most exceptions have been string objects, in Python
5+
1.5a4, all standard exceptions have been converted to class objects,
6+
and users are encouraged to the the same. The source code for those
7+
exceptions is present in the standard library module
8+
\code{exceptions}; this module never needs to be imported explicitly.
9+
10+
For backward compatibility, when Python is invoked with the \code{-X}
11+
option, the standard exceptions are strings. This may be needed to
12+
run some code that breaks because of the different semantics of class
13+
based exceptions. The \code{-X} option will become obsolete in future
14+
Python versions, so the recommended solution is to fix the code.
15+
16+
Two distinct string objects with the same value are considered different
17+
exceptions. This is done to force programmers to use exception names
18+
rather than their string value when specifying exception handlers.
19+
The string value of all built-in exceptions is their name, but this is
20+
not a requirement for user-defined exceptions or exceptions defined by
21+
library modules.
22+
23+
For class exceptions, in a \code{try} statement with an\code{except}
24+
clause that mentions a particular class, that clause also handles
25+
any exception classes derived from that class (but not exception
26+
classes from which \emph{it} is derived). Two exception classes
27+
that are not related via subclassing are never equivalent, even if
28+
they have the same name.
29+
\stindex{try}
30+
\stindex{except}
31+
32+
The built-in exceptions listed below can be generated by the
33+
interpreter or built-in functions. Except where mentioned, they have
34+
an ``associated value'' indicating the detailed cause of the error.
35+
This may be a string or a tuple containing several items of
36+
information (e.g., an error code and a string explaining the code).
37+
The associated value is the second argument to the \code{raise}
38+
statement. For string exceptions, the associated value itself will be
39+
stored in the variable named as the second argument of the
40+
\code{except} clause (if any). For class exceptions derived from
41+
the root class \code{Exception}, that variable receives the exception
42+
instance, and the associated value is present as the exception
43+
instance's \code{args} attribute; this is a tuple even if the second
44+
argument to \code{raise} was not (then it is a singleton tuple).
45+
\stindex{raise}
1546

1647
User code can raise built-in exceptions. This can be used to test an
17-
exception handler or to report an error condition `just like' the
48+
exception handler or to report an error condition ``just like'' the
1849
situation in which the interpreter raises the same exception; but
1950
beware that there is nothing to prevent user code from raising an
2051
inappropriate error.
2152

22-
\renewcommand{\indexsubitem}{(built-in exception)}
53+
\renewcommand{\indexsubitem}{(built-in exception base class)}
54+
55+
The following exceptions are only used as base classes for other
56+
exceptions. When string-based standard exceptions are used, they
57+
are tuples containing the directly derived classes.
58+
59+
\begin{excdesc}{Exception}
60+
The root class for exceptions. All built-in exceptions are derived
61+
from this class. All user-defined exceptions should also be derived
62+
from this class, but this is not (yet) enforced. The \code{str()}
63+
function, when applied to an instance of this class (or most derived
64+
classes) returns the string value of the argument or arguments, or an
65+
empty string if no arguments were given to the constructor.
66+
\end{excdesc}
67+
68+
\begin{excdesc}{StandardError}
69+
The base class for built-in exceptions. All built-in exceptions are
70+
derived from this class, which is itself derived from the root class
71+
\code{Exception}. For backward compatibility, when used as a
72+
sequence, this accesses the arguments given to the constructor.
73+
\end{excdesc}
74+
75+
\begin{excdesc}{ArithmeticError}
76+
The base class for those built-in exceptions that are raised for
77+
various arithmetic errors: \code{OverflowError},
78+
\code{ZeroDivisionError}, \code{FloatingPointError}.
79+
\end{excdesc}
80+
81+
\begin{excdesc}{LookupError}
82+
The base class for thise exceptions that are raised when a key or
83+
index used on a mapping or sequence is invalid: \code{IndexError},
84+
\code{KeyError}.
85+
\end{excdesc}
86+
87+
\renewcommand{\indexsubitem}{(built-in exception base class)}
88+
89+
The following exceptions are the exceptions that are actually raised.
90+
They are class objects, except when the \code{-X} option is used to
91+
revert back to string-based standard exceptions.
92+
93+
\begin{excdesc}{AssertionError}
94+
Raised when an \code{assert} statement fails.
95+
\stindex{assert}
96+
\end{excdesc}
2397

2498
\begin{excdesc}{AttributeError}
2599
% xref to attribute reference?
@@ -38,11 +112,24 @@ \section{Built-in Exceptions}
38112
objects return an empty string when they hit \EOF{}.) No associated value.
39113
\end{excdesc}
40114

115+
\begin{excdesc}{FloatingPointError}
116+
Raised when a floating point operation fails. This exception is
117+
always defined, but can only be raised when Python is configured with
118+
the \code{--with-fpectl} option, or the \code{WANT_SIGFPE_HANDLER}
119+
symbol is defined in the \file{config.h} file.
120+
\end{excdesc}
121+
41122
\begin{excdesc}{IOError}
42123
% XXXJH xrefs here
43124
Raised when an I/O operation (such as a \code{print} statement, the
44125
built-in \code{open()} function or a method of a file object) fails
45-
for an I/O-related reason, e.g., `file not found', `disk full'.
126+
for an I/O-related reason, e.g., ``file not found'' or ``disk full''.
127+
128+
When class exceptions are used, and this exception is instantiated as
129+
\code{IOError(errno, strerror)}, the instance has two additional
130+
attributes \code{errno} and \code{strerror} set to the error code and
131+
the error message, respectively. These attributes default to
132+
\code{None}.
46133
\end{excdesc}
47134

48135
\begin{excdesc}{ImportError}
@@ -106,10 +193,9 @@ \section{Built-in Exceptions}
106193
\begin{excdesc}{RuntimeError}
107194
Raised when an error is detected that doesn't fall in any of the
108195
other categories. The associated value is a string indicating what
109-
precisely went wrong. (This exception is a relic from a previous
110-
version of the interpreter; it is not used any more except by some
111-
extension modules that haven't been converted to define their own
112-
exceptions yet.)
196+
precisely went wrong. (This exception is mostly a relic from a
197+
previous version of the interpreter; it is not used very much any
198+
more.)
113199
\end{excdesc}
114200

115201
\begin{excdesc}{SyntaxError}
@@ -119,6 +205,13 @@ \section{Built-in Exceptions}
119205
to the built-in function \code{eval()} or \code{input()}, or
120206
when reading the initial script or standard input (also
121207
interactively).
208+
209+
When class exceptions are used, instances of this class have
210+
atttributes \code{filename}, \code{lineno}, \code{offset} and
211+
\code{text} for easier access to the details; for string exceptions,
212+
the associated value is usually a tuple of the form
213+
\code{(message, (filename, lineno, offset, text))}.
214+
For class exceptions, \code{str()} returns only the message.
122215
\end{excdesc}
123216

124217
\begin{excdesc}{SystemError}
@@ -143,11 +236,15 @@ \section{Built-in Exceptions}
143236
system exit status (passed to \C{}'s \code{exit()} function); if it is
144237
\code{None}, the exit status is zero; if it has another type (such as
145238
a string), the object's value is printed and the exit status is one.
239+
240+
When class exceptions are used, the instance has an attribute
241+
\code{code} which is set to the proposed exit status or error message
242+
(defaulting to \code{None}).
146243

147244
A call to \code{sys.exit} is translated into an exception so that
148245
clean-up handlers (\code{finally} clauses of \code{try} statements)
149246
can be executed, and so that a debugger can execute a script without
150-
running the risk of losing control. The \code{posix._exit()} function
247+
running the risk of losing control. The \code{os._exit()} function
151248
can be used if it is absolutely positively necessary to exit
152249
immediately (e.g., after a \code{fork()} in the child process).
153250
\end{excdesc}

‎Doc/libexcs.tex‎

Lines changed: 117 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,99 @@
11
\section{Built-in Exceptions}
22

3-
Exceptions are string objects. Two distinct string objects with the
4-
same value are different exceptions. This is done to force programmers
5-
to use exception names rather than their string value when specifying
6-
exception handlers. The string value of all built-in exceptions is
7-
their name, but this is not a requirement for user-defined exceptions
8-
or exceptions defined by library modules.
9-
10-
The following exceptions can be generated by the interpreter or
11-
built-in functions. Except where mentioned, they have an `associated
12-
value' indicating the detailed cause of the error. This may be a
13-
string or a tuple containing several items of information (e.g., an
14-
error code and a string explaining the code).
3+
Exceptions can be class objects or string objects. While
4+
traditionally, most exceptions have been string objects, in Python
5+
1.5a4, all standard exceptions have been converted to class objects,
6+
and users are encouraged to the the same. The source code for those
7+
exceptions is present in the standard library module
8+
\code{exceptions}; this module never needs to be imported explicitly.
9+
10+
For backward compatibility, when Python is invoked with the \code{-X}
11+
option, the standard exceptions are strings. This may be needed to
12+
run some code that breaks because of the different semantics of class
13+
based exceptions. The \code{-X} option will become obsolete in future
14+
Python versions, so the recommended solution is to fix the code.
15+
16+
Two distinct string objects with the same value are considered different
17+
exceptions. This is done to force programmers to use exception names
18+
rather than their string value when specifying exception handlers.
19+
The string value of all built-in exceptions is their name, but this is
20+
not a requirement for user-defined exceptions or exceptions defined by
21+
library modules.
22+
23+
For class exceptions, in a \code{try} statement with an\code{except}
24+
clause that mentions a particular class, that clause also handles
25+
any exception classes derived from that class (but not exception
26+
classes from which \emph{it} is derived). Two exception classes
27+
that are not related via subclassing are never equivalent, even if
28+
they have the same name.
29+
\stindex{try}
30+
\stindex{except}
31+
32+
The built-in exceptions listed below can be generated by the
33+
interpreter or built-in functions. Except where mentioned, they have
34+
an ``associated value'' indicating the detailed cause of the error.
35+
This may be a string or a tuple containing several items of
36+
information (e.g., an error code and a string explaining the code).
37+
The associated value is the second argument to the \code{raise}
38+
statement. For string exceptions, the associated value itself will be
39+
stored in the variable named as the second argument of the
40+
\code{except} clause (if any). For class exceptions derived from
41+
the root class \code{Exception}, that variable receives the exception
42+
instance, and the associated value is present as the exception
43+
instance's \code{args} attribute; this is a tuple even if the second
44+
argument to \code{raise} was not (then it is a singleton tuple).
45+
\stindex{raise}
1546

1647
User code can raise built-in exceptions. This can be used to test an
17-
exception handler or to report an error condition `just like' the
48+
exception handler or to report an error condition ``just like'' the
1849
situation in which the interpreter raises the same exception; but
1950
beware that there is nothing to prevent user code from raising an
2051
inappropriate error.
2152

22-
\renewcommand{\indexsubitem}{(built-in exception)}
53+
\renewcommand{\indexsubitem}{(built-in exception base class)}
54+
55+
The following exceptions are only used as base classes for other
56+
exceptions. When string-based standard exceptions are used, they
57+
are tuples containing the directly derived classes.
58+
59+
\begin{excdesc}{Exception}
60+
The root class for exceptions. All built-in exceptions are derived
61+
from this class. All user-defined exceptions should also be derived
62+
from this class, but this is not (yet) enforced. The \code{str()}
63+
function, when applied to an instance of this class (or most derived
64+
classes) returns the string value of the argument or arguments, or an
65+
empty string if no arguments were given to the constructor.
66+
\end{excdesc}
67+
68+
\begin{excdesc}{StandardError}
69+
The base class for built-in exceptions. All built-in exceptions are
70+
derived from this class, which is itself derived from the root class
71+
\code{Exception}. For backward compatibility, when used as a
72+
sequence, this accesses the arguments given to the constructor.
73+
\end{excdesc}
74+
75+
\begin{excdesc}{ArithmeticError}
76+
The base class for those built-in exceptions that are raised for
77+
various arithmetic errors: \code{OverflowError},
78+
\code{ZeroDivisionError}, \code{FloatingPointError}.
79+
\end{excdesc}
80+
81+
\begin{excdesc}{LookupError}
82+
The base class for thise exceptions that are raised when a key or
83+
index used on a mapping or sequence is invalid: \code{IndexError},
84+
\code{KeyError}.
85+
\end{excdesc}
86+
87+
\renewcommand{\indexsubitem}{(built-in exception base class)}
88+
89+
The following exceptions are the exceptions that are actually raised.
90+
They are class objects, except when the \code{-X} option is used to
91+
revert back to string-based standard exceptions.
92+
93+
\begin{excdesc}{AssertionError}
94+
Raised when an \code{assert} statement fails.
95+
\stindex{assert}
96+
\end{excdesc}
2397

2498
\begin{excdesc}{AttributeError}
2599
% xref to attribute reference?
@@ -38,11 +112,24 @@ \section{Built-in Exceptions}
38112
objects return an empty string when they hit \EOF{}.) No associated value.
39113
\end{excdesc}
40114

115+
\begin{excdesc}{FloatingPointError}
116+
Raised when a floating point operation fails. This exception is
117+
always defined, but can only be raised when Python is configured with
118+
the \code{--with-fpectl} option, or the \code{WANT_SIGFPE_HANDLER}
119+
symbol is defined in the \file{config.h} file.
120+
\end{excdesc}
121+
41122
\begin{excdesc}{IOError}
42123
% XXXJH xrefs here
43124
Raised when an I/O operation (such as a \code{print} statement, the
44125
built-in \code{open()} function or a method of a file object) fails
45-
for an I/O-related reason, e.g., `file not found', `disk full'.
126+
for an I/O-related reason, e.g., ``file not found'' or ``disk full''.
127+
128+
When class exceptions are used, and this exception is instantiated as
129+
\code{IOError(errno, strerror)}, the instance has two additional
130+
attributes \code{errno} and \code{strerror} set to the error code and
131+
the error message, respectively. These attributes default to
132+
\code{None}.
46133
\end{excdesc}
47134

48135
\begin{excdesc}{ImportError}
@@ -106,10 +193,9 @@ \section{Built-in Exceptions}
106193
\begin{excdesc}{RuntimeError}
107194
Raised when an error is detected that doesn't fall in any of the
108195
other categories. The associated value is a string indicating what
109-
precisely went wrong. (This exception is a relic from a previous
110-
version of the interpreter; it is not used any more except by some
111-
extension modules that haven't been converted to define their own
112-
exceptions yet.)
196+
precisely went wrong. (This exception is mostly a relic from a
197+
previous version of the interpreter; it is not used very much any
198+
more.)
113199
\end{excdesc}
114200

115201
\begin{excdesc}{SyntaxError}
@@ -119,6 +205,13 @@ \section{Built-in Exceptions}
119205
to the built-in function \code{eval()} or \code{input()}, or
120206
when reading the initial script or standard input (also
121207
interactively).
208+
209+
When class exceptions are used, instances of this class have
210+
atttributes \code{filename}, \code{lineno}, \code{offset} and
211+
\code{text} for easier access to the details; for string exceptions,
212+
the associated value is usually a tuple of the form
213+
\code{(message, (filename, lineno, offset, text))}.
214+
For class exceptions, \code{str()} returns only the message.
122215
\end{excdesc}
123216

124217
\begin{excdesc}{SystemError}
@@ -143,11 +236,15 @@ \section{Built-in Exceptions}
143236
system exit status (passed to \C{}'s \code{exit()} function); if it is
144237
\code{None}, the exit status is zero; if it has another type (such as
145238
a string), the object's value is printed and the exit status is one.
239+
240+
When class exceptions are used, the instance has an attribute
241+
\code{code} which is set to the proposed exit status or error message
242+
(defaulting to \code{None}).
146243

147244
A call to \code{sys.exit} is translated into an exception so that
148245
clean-up handlers (\code{finally} clauses of \code{try} statements)
149246
can be executed, and so that a debugger can execute a script without
150-
running the risk of losing control. The \code{posix._exit()} function
247+
running the risk of losing control. The \code{os._exit()} function
151248
can be used if it is absolutely positively necessary to exit
152249
immediately (e.g., after a \code{fork()} in the child process).
153250
\end{excdesc}

0 commit comments

Comments
 (0)