Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libexcs.tex @ 21467:4e35fa5d5708 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add documentation for the help() built-in; contributed by Ka-Ping Yee. This is part of SF patch #494622.
author Fred Drake <fdrake@acm.org>
date Tue, 18 Dec 2001 16:31:08 +0000
parents bc02c3b09626
children a7a60b141d1d 84684fc02da0
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
1 \section{Built-in Exceptions}
10703
e4e800a78d8d Make internal module references hyperlinks wherever it makes sense.
Fred Drake <fdrake@acm.org>
parents: 10290
diff changeset
2
8719
8175c6e1e613 Use the new module synopsis syntax, even though we don't need a synopsis table
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
3 \declaremodule{standard}{exceptions}
8175c6e1e613 Use the new module synopsis syntax, even though we don't need a synopsis table
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
4 \modulesynopsis{Standard exceptions classes.}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
5
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8165
diff changeset
6
14484
34f9a017ce63 Minor clarifications in the introductory paragraph.
Fred Drake <fdrake@acm.org>
parents: 14455
diff changeset
7 Exceptions can be class objects or string objects. Though most
34f9a017ce63 Minor clarifications in the introductory paragraph.
Fred Drake <fdrake@acm.org>
parents: 14455
diff changeset
8 exceptions have been string objects in past versions of Python, in
34f9a017ce63 Minor clarifications in the introductory paragraph.
Fred Drake <fdrake@acm.org>
parents: 14455
diff changeset
9 Python 1.5 and newer versions, all standard exceptions have been
34f9a017ce63 Minor clarifications in the introductory paragraph.
Fred Drake <fdrake@acm.org>
parents: 14455
diff changeset
10 converted to class objects, and users are encouraged to do the same.
34f9a017ce63 Minor clarifications in the introductory paragraph.
Fred Drake <fdrake@acm.org>
parents: 14455
diff changeset
11 The exceptions are defined in the module \module{exceptions}. This
34f9a017ce63 Minor clarifications in the introductory paragraph.
Fred Drake <fdrake@acm.org>
parents: 14455
diff changeset
12 module never needs to be imported explicitly: the exceptions are
20026
7c5cd685c1de Added reference to Tutorial section on user-defined exceptions for
Fred Drake <fdrake@acm.org>
parents: 18835
diff changeset
13 provided in the built-in namespace as well as the \module{exceptions}
7c5cd685c1de Added reference to Tutorial section on user-defined exceptions for
Fred Drake <fdrake@acm.org>
parents: 18835
diff changeset
14 module.
6384
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
15
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
16 Two distinct string objects with the same value are considered different
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
17 exceptions. This is done to force programmers to use exception names
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
18 rather than their string value when specifying exception handlers.
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
19 The string value of all built-in exceptions is their name, but this is
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
20 not a requirement for user-defined exceptions or exceptions defined by
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
21 library modules.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
22
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
23 For class exceptions, in a \keyword{try}\stindex{try} statement with
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
24 an \keyword{except}\stindex{except} clause that mentions a particular
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
25 class, that clause also handles any exception classes derived from
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
26 that class (but not exception classes from which \emph{it} is
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
27 derived). Two exception classes that are not related via subclassing
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
28 are never equivalent, even if they have the same name.
6384
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
29
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
30 The built-in exceptions listed below can be generated by the
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
31 interpreter or built-in functions. Except where mentioned, they have
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
32 an ``associated value'' indicating the detailed cause of the error.
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
33 This may be a string or a tuple containing several items of
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
34 information (e.g., an error code and a string explaining the code).
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
35 The associated value is the second argument to the
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
36 \keyword{raise}\stindex{raise} statement. For string exceptions, the
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
37 associated value itself will be stored in the variable named as the
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
38 second argument of the \keyword{except} clause (if any). For class
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
39 exceptions, that variable receives the exception instance. If the
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
40 exception class is derived from the standard root class
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
41 \exception{Exception}, the associated value is present as the
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
42 exception instance's \member{args} attribute, and possibly on other
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
43 attributes as well.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
44
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
45 User code can raise built-in exceptions. This can be used to test an
6384
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
46 exception handler or to report an error condition ``just like'' the
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
47 situation in which the interpreter raises the same exception; but
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
48 beware that there is nothing to prevent user code from raising an
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
49 inappropriate error.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
50
20026
7c5cd685c1de Added reference to Tutorial section on user-defined exceptions for
Fred Drake <fdrake@acm.org>
parents: 18835
diff changeset
51 The built-in exception classes can be sub-classed to define new
7c5cd685c1de Added reference to Tutorial section on user-defined exceptions for
Fred Drake <fdrake@acm.org>
parents: 18835
diff changeset
52 exceptions; programmers are encouraged to at least derive new
7c5cd685c1de Added reference to Tutorial section on user-defined exceptions for
Fred Drake <fdrake@acm.org>
parents: 18835
diff changeset
53 exceptions from the \exception{Exception} base class. More
7c5cd685c1de Added reference to Tutorial section on user-defined exceptions for
Fred Drake <fdrake@acm.org>
parents: 18835
diff changeset
54 information on defining exceptions is available in the
7c5cd685c1de Added reference to Tutorial section on user-defined exceptions for
Fred Drake <fdrake@acm.org>
parents: 18835
diff changeset
55 \citetitle[../tut/tut.html]{Python Tutorial} under the heading
7c5cd685c1de Added reference to Tutorial section on user-defined exceptions for
Fred Drake <fdrake@acm.org>
parents: 18835
diff changeset
56 ``User-defined Exceptions.''
7c5cd685c1de Added reference to Tutorial section on user-defined exceptions for
Fred Drake <fdrake@acm.org>
parents: 18835
diff changeset
57
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 7140
diff changeset
58 \setindexsubitem{(built-in exception base class)}
6384
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
59
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
60 The following exceptions are only used as base classes for other
12270
f6b58b021e56 Revised / removed comments about string exceptions (relating to the
Fred Drake <fdrake@acm.org>
parents: 12268
diff changeset
61 exceptions.
6384
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
62
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
63 \begin{excdesc}{Exception}
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
64 The root class for exceptions. All built-in exceptions are derived
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
65 from this class. All user-defined exceptions should also be derived
8721
d7ca429ef1ab Logical markup.
Fred Drake <fdrake@acm.org>
parents: 8719
diff changeset
66 from this class, but this is not (yet) enforced. The \function{str()}
6384
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
67 function, when applied to an instance of this class (or most derived
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
68 classes) returns the string value of the argument or arguments, or an
6420
abed754c7b7f The sequence behavior is now on the Exception root class rather than
Guido van Rossum <guido@python.org>
parents: 6384
diff changeset
69 empty string if no arguments were given to the constructor. When used
abed754c7b7f The sequence behavior is now on the Exception root class rather than
Guido van Rossum <guido@python.org>
parents: 6384
diff changeset
70 as a sequence, this accesses the arguments given to the constructor
8723
6794294eb014 Added descriptions of EnvironmentError and OSError; updated IOError to
Barry Warsaw <barry@python.org>
parents: 8721
diff changeset
71 (handy for backward compatibility with old code). The arguments are
8724
5d6bf60cb736 Fix up Barry's markup, which didn't pass the latex test. ;-)
Fred Drake <fdrake@acm.org>
parents: 8723
diff changeset
72 also available on the instance's \member{args} attribute, as a tuple.
6384
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
73 \end{excdesc}
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
74
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
75 \begin{excdesc}{StandardError}
10290
5cc7122671ae Document the correct class hierarchy for SystemExit. It is not an
Barry Warsaw <barry@python.org>
parents: 10076
diff changeset
76 The base class for all built-in exceptions except
18811
29e661c52c0b Add StopIteration to the list of exceptions *not* derived from StandardError.
Fred Drake <fdrake@acm.org>
parents: 18488
diff changeset
77 \exception{StopIteration} and \exception{SystemExit}.
29e661c52c0b Add StopIteration to the list of exceptions *not* derived from StandardError.
Fred Drake <fdrake@acm.org>
parents: 18488
diff changeset
78 \exception{StandardError} itself is derived from the root class
8721
d7ca429ef1ab Logical markup.
Fred Drake <fdrake@acm.org>
parents: 8719
diff changeset
79 \exception{Exception}.
6384
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
80 \end{excdesc}
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
81
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
82 \begin{excdesc}{ArithmeticError}
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
83 The base class for those built-in exceptions that are raised for
8721
d7ca429ef1ab Logical markup.
Fred Drake <fdrake@acm.org>
parents: 8719
diff changeset
84 various arithmetic errors: \exception{OverflowError},
d7ca429ef1ab Logical markup.
Fred Drake <fdrake@acm.org>
parents: 8719
diff changeset
85 \exception{ZeroDivisionError}, \exception{FloatingPointError}.
6384
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
86 \end{excdesc}
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
87
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
88 \begin{excdesc}{LookupError}
8723
6794294eb014 Added descriptions of EnvironmentError and OSError; updated IOError to
Barry Warsaw <barry@python.org>
parents: 8721
diff changeset
89 The base class for the exceptions that are raised when a key or
8721
d7ca429ef1ab Logical markup.
Fred Drake <fdrake@acm.org>
parents: 8719
diff changeset
90 index used on a mapping or sequence is invalid: \exception{IndexError},
15333
d5157c8bb11a Since LookupError can be raised by sys.setdefaultencoding(), we should not
Fred Drake <fdrake@acm.org>
parents: 14484
diff changeset
91 \exception{KeyError}. This can be raised directly by
d5157c8bb11a Since LookupError can be raised by sys.setdefaultencoding(), we should not
Fred Drake <fdrake@acm.org>
parents: 14484
diff changeset
92 \function{sys.setdefaultencoding()}.
6384
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
93 \end{excdesc}
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
94
8723
6794294eb014 Added descriptions of EnvironmentError and OSError; updated IOError to
Barry Warsaw <barry@python.org>
parents: 8721
diff changeset
95 \begin{excdesc}{EnvironmentError}
6794294eb014 Added descriptions of EnvironmentError and OSError; updated IOError to
Barry Warsaw <barry@python.org>
parents: 8721
diff changeset
96 The base class for exceptions that
6794294eb014 Added descriptions of EnvironmentError and OSError; updated IOError to
Barry Warsaw <barry@python.org>
parents: 8721
diff changeset
97 can occur outside the Python system: \exception{IOError},
6794294eb014 Added descriptions of EnvironmentError and OSError; updated IOError to
Barry Warsaw <barry@python.org>
parents: 8721
diff changeset
98 \exception{OSError}. When exceptions of this type are created with a
6794294eb014 Added descriptions of EnvironmentError and OSError; updated IOError to
Barry Warsaw <barry@python.org>
parents: 8721
diff changeset
99 2-tuple, the first item is available on the instance's \member{errno}
6794294eb014 Added descriptions of EnvironmentError and OSError; updated IOError to
Barry Warsaw <barry@python.org>
parents: 8721
diff changeset
100 attribute (it is assumed to be an error number), and the second item
6794294eb014 Added descriptions of EnvironmentError and OSError; updated IOError to
Barry Warsaw <barry@python.org>
parents: 8721
diff changeset
101 is available on the \member{strerror} attribute (it is usually the
6794294eb014 Added descriptions of EnvironmentError and OSError; updated IOError to
Barry Warsaw <barry@python.org>
parents: 8721
diff changeset
102 associated error message). The tuple itself is also available on the
6794294eb014 Added descriptions of EnvironmentError and OSError; updated IOError to
Barry Warsaw <barry@python.org>
parents: 8721
diff changeset
103 \member{args} attribute.
10076
cbf5503b32d5 Move \versionadded macros to end of descriptions.
Fred Drake <fdrake@acm.org>
parents: 10057
diff changeset
104 \versionadded{1.5.2}
8723
6794294eb014 Added descriptions of EnvironmentError and OSError; updated IOError to
Barry Warsaw <barry@python.org>
parents: 8721
diff changeset
105
6794294eb014 Added descriptions of EnvironmentError and OSError; updated IOError to
Barry Warsaw <barry@python.org>
parents: 8721
diff changeset
106 When an \exception{EnvironmentError} exception is instantiated with a
6794294eb014 Added descriptions of EnvironmentError and OSError; updated IOError to
Barry Warsaw <barry@python.org>
parents: 8721
diff changeset
107 3-tuple, the first two items are available as above, while the third
6794294eb014 Added descriptions of EnvironmentError and OSError; updated IOError to
Barry Warsaw <barry@python.org>
parents: 8721
diff changeset
108 item is available on the \member{filename} attribute. However, for
6794294eb014 Added descriptions of EnvironmentError and OSError; updated IOError to
Barry Warsaw <barry@python.org>
parents: 8721
diff changeset
109 backwards compatibility, the \member{args} attribute contains only a
6794294eb014 Added descriptions of EnvironmentError and OSError; updated IOError to
Barry Warsaw <barry@python.org>
parents: 8721
diff changeset
110 2-tuple of the first two constructor arguments.
6794294eb014 Added descriptions of EnvironmentError and OSError; updated IOError to
Barry Warsaw <barry@python.org>
parents: 8721
diff changeset
111
6794294eb014 Added descriptions of EnvironmentError and OSError; updated IOError to
Barry Warsaw <barry@python.org>
parents: 8721
diff changeset
112 The \member{filename} attribute is \code{None} when this exception is
6794294eb014 Added descriptions of EnvironmentError and OSError; updated IOError to
Barry Warsaw <barry@python.org>
parents: 8721
diff changeset
113 created with other than 3 arguments. The \member{errno} and
6794294eb014 Added descriptions of EnvironmentError and OSError; updated IOError to
Barry Warsaw <barry@python.org>
parents: 8721
diff changeset
114 \member{strerror} attributes are also \code{None} when the instance was
6794294eb014 Added descriptions of EnvironmentError and OSError; updated IOError to
Barry Warsaw <barry@python.org>
parents: 8721
diff changeset
115 created with other than 2 or 3 arguments. In this last case,
6794294eb014 Added descriptions of EnvironmentError and OSError; updated IOError to
Barry Warsaw <barry@python.org>
parents: 8721
diff changeset
116 \member{args} contains the verbatim constructor arguments as a tuple.
6794294eb014 Added descriptions of EnvironmentError and OSError; updated IOError to
Barry Warsaw <barry@python.org>
parents: 8721
diff changeset
117 \end{excdesc}
6794294eb014 Added descriptions of EnvironmentError and OSError; updated IOError to
Barry Warsaw <barry@python.org>
parents: 8721
diff changeset
118
14455
6919d8e14a30 Remove comment about -X and string exceptions. Error noted by
Fred Drake <fdrake@acm.org>
parents: 14033
diff changeset
119
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 7140
diff changeset
120 \setindexsubitem{(built-in exception)}
6384
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
121
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
122 The following exceptions are the exceptions that are actually raised.
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
123
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
124 \begin{excdesc}{AssertionError}
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
125 \stindex{assert}
8721
d7ca429ef1ab Logical markup.
Fred Drake <fdrake@acm.org>
parents: 8719
diff changeset
126 Raised when an \keyword{assert} statement fails.
6384
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
127 \end{excdesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
128
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
129 \begin{excdesc}{AttributeError}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
130 % xref to attribute reference?
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
131 Raised when an attribute reference or assignment fails. (When an
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
132 object does not support attribute references or attribute assignments
8721
d7ca429ef1ab Logical markup.
Fred Drake <fdrake@acm.org>
parents: 8719
diff changeset
133 at all, \exception{TypeError} is raised.)
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
134 \end{excdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
135
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
136 \begin{excdesc}{EOFError}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
137 % XXXJH xrefs here
8721
d7ca429ef1ab Logical markup.
Fred Drake <fdrake@acm.org>
parents: 8719
diff changeset
138 Raised when one of the built-in functions (\function{input()} or
21062
bc02c3b09626 Clean up some markup cruft. A number of the macros that take no
Fred Drake <fdrake@acm.org>
parents: 20290
diff changeset
139 \function{raw_input()}) hits an end-of-file condition (\EOF) without
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
140 reading any data.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
141 % XXXJH xrefs here
8721
d7ca429ef1ab Logical markup.
Fred Drake <fdrake@acm.org>
parents: 8719
diff changeset
142 (N.B.: the \method{read()} and \method{readline()} methods of file
21062
bc02c3b09626 Clean up some markup cruft. A number of the macros that take no
Fred Drake <fdrake@acm.org>
parents: 20290
diff changeset
143 objects return an empty string when they hit \EOF.)
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
144 \end{excdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
145
6384
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
146 \begin{excdesc}{FloatingPointError}
8766
058417071b0e Mark the new & changed items.
Fred Drake <fdrake@acm.org>
parents: 8724
diff changeset
147 Raised when a floating point operation fails. This exception is
058417071b0e Mark the new & changed items.
Fred Drake <fdrake@acm.org>
parents: 8724
diff changeset
148 always defined, but can only be raised when Python is configured
12380
37d9ded5ab91 Make use of \longprogramopt where appropriate.
Fred Drake <fdrake@acm.org>
parents: 12270
diff changeset
149 with the \longprogramopt{with-fpectl} option, or the
8766
058417071b0e Mark the new & changed items.
Fred Drake <fdrake@acm.org>
parents: 8724
diff changeset
150 \constant{WANT_SIGFPE_HANDLER} symbol is defined in the
18835
2dea40e40d9d Patch #411138: Rename config.h to pyconfig.h. Closes bug #231774.
Martin v. Löwis <martin@v.loewis.de>
parents: 18811
diff changeset
151 \file{pyconfig.h} file.
6384
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
152 \end{excdesc}
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
153
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
154 \begin{excdesc}{IOError}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
155 % XXXJH xrefs here
8766
058417071b0e Mark the new & changed items.
Fred Drake <fdrake@acm.org>
parents: 8724
diff changeset
156 Raised when an I/O operation (such as a \keyword{print} statement,
058417071b0e Mark the new & changed items.
Fred Drake <fdrake@acm.org>
parents: 8724
diff changeset
157 the built-in \function{open()} function or a method of a file
058417071b0e Mark the new & changed items.
Fred Drake <fdrake@acm.org>
parents: 8724
diff changeset
158 object) fails for an I/O-related reason, e.g., ``file not found'' or
058417071b0e Mark the new & changed items.
Fred Drake <fdrake@acm.org>
parents: 8724
diff changeset
159 ``disk full''.
6384
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
160
9774
770b40fed5f7 Added missing "from" in IOError description.
Fred Drake <fdrake@acm.org>
parents: 9575
diff changeset
161 This class is derived from \exception{EnvironmentError}. See the
8766
058417071b0e Mark the new & changed items.
Fred Drake <fdrake@acm.org>
parents: 8724
diff changeset
162 discussion above for more information on exception instance
058417071b0e Mark the new & changed items.
Fred Drake <fdrake@acm.org>
parents: 8724
diff changeset
163 attributes.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
164 \end{excdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
165
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
166 \begin{excdesc}{ImportError}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
167 % XXXJH xref to import statement?
8721
d7ca429ef1ab Logical markup.
Fred Drake <fdrake@acm.org>
parents: 8719
diff changeset
168 Raised when an \keyword{import} statement fails to find the module
9536
3e50c1ddab3a Fix remaining {\rm ...} construct.
Fred Drake <fdrake@acm.org>
parents: 8766
diff changeset
169 definition or when a \code{from \textrm{\ldots} import} fails to find a
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
170 name that is to be imported.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
171 \end{excdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
172
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
173 \begin{excdesc}{IndexError}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
174 % XXXJH xref to sequences
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
175 Raised when a sequence subscript is out of range. (Slice indices are
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
176 silently truncated to fall in the allowed range; if an index is not a
8721
d7ca429ef1ab Logical markup.
Fred Drake <fdrake@acm.org>
parents: 8719
diff changeset
177 plain integer, \exception{TypeError} is raised.)
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
178 \end{excdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
179
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
180 \begin{excdesc}{KeyError}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
181 % XXXJH xref to mapping objects?
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
182 Raised when a mapping (dictionary) key is not found in the set of
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
183 existing keys.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
184 \end{excdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
185
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
186 \begin{excdesc}{KeyboardInterrupt}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
187 Raised when the user hits the interrupt key (normally
18488
9977cf206532 Follow the recommended practices for keystroke representation; this
Fred Drake <fdrake@acm.org>
parents: 17663
diff changeset
188 \kbd{Control-C} or \kbd{Delete}). During execution, a check for
8165
f3c8fbc793fe Use of \key and \kbd were isolated to one instance each in this file;
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
189 interrupts is made regularly.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
190 % XXXJH xrefs here
8165
f3c8fbc793fe Use of \key and \kbd were isolated to one instance each in this file;
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
191 Interrupts typed when a built-in function \function{input()} or
f3c8fbc793fe Use of \key and \kbd were isolated to one instance each in this file;
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
192 \function{raw_input()}) is waiting for input also raise this
8723
6794294eb014 Added descriptions of EnvironmentError and OSError; updated IOError to
Barry Warsaw <barry@python.org>
parents: 8721
diff changeset
193 exception.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
194 \end{excdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
195
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
196 \begin{excdesc}{MemoryError}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
197 Raised when an operation runs out of memory but the situation may
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
198 still be rescued (by deleting some objects). The associated value is
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
199 a string indicating what kind of (internal) operation ran out of memory.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
200 Note that because of the underlying memory management architecture
12270
f6b58b021e56 Revised / removed comments about string exceptions (relating to the
Fred Drake <fdrake@acm.org>
parents: 12268
diff changeset
201 (C's \cfunction{malloc()} function), the interpreter may not
8721
d7ca429ef1ab Logical markup.
Fred Drake <fdrake@acm.org>
parents: 8719
diff changeset
202 always be able to completely recover from this situation; it
d7ca429ef1ab Logical markup.
Fred Drake <fdrake@acm.org>
parents: 8719
diff changeset
203 nevertheless raises an exception so that a stack traceback can be
d7ca429ef1ab Logical markup.
Fred Drake <fdrake@acm.org>
parents: 8719
diff changeset
204 printed, in case a run-away program was the cause.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
205 \end{excdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
206
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
207 \begin{excdesc}{NameError}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
208 Raised when a local or global name is not found. This applies only
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
209 to unqualified names. The associated value is the name that could
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
210 not be found.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
211 \end{excdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
212
9575
cdf5617c2022 Moved NotImplementedError into alphabetical order, and reword
Barry Warsaw <barry@python.org>
parents: 9574
diff changeset
213 \begin{excdesc}{NotImplementedError}
cdf5617c2022 Moved NotImplementedError into alphabetical order, and reword
Barry Warsaw <barry@python.org>
parents: 9574
diff changeset
214 This exception is derived from \exception{RuntimeError}. In user
cdf5617c2022 Moved NotImplementedError into alphabetical order, and reword
Barry Warsaw <barry@python.org>
parents: 9574
diff changeset
215 defined base classes, abstract methods should raise this exception
cdf5617c2022 Moved NotImplementedError into alphabetical order, and reword
Barry Warsaw <barry@python.org>
parents: 9574
diff changeset
216 when they require derived classes to override the method.
10076
cbf5503b32d5 Move \versionadded macros to end of descriptions.
Fred Drake <fdrake@acm.org>
parents: 10057
diff changeset
217 \versionadded{1.5.2}
9575
cdf5617c2022 Moved NotImplementedError into alphabetical order, and reword
Barry Warsaw <barry@python.org>
parents: 9574
diff changeset
218 \end{excdesc}
cdf5617c2022 Moved NotImplementedError into alphabetical order, and reword
Barry Warsaw <barry@python.org>
parents: 9574
diff changeset
219
8723
6794294eb014 Added descriptions of EnvironmentError and OSError; updated IOError to
Barry Warsaw <barry@python.org>
parents: 8721
diff changeset
220 \begin{excdesc}{OSError}
6794294eb014 Added descriptions of EnvironmentError and OSError; updated IOError to
Barry Warsaw <barry@python.org>
parents: 8721
diff changeset
221 %xref for os module
8724
5d6bf60cb736 Fix up Barry's markup, which didn't pass the latex test. ;-)
Fred Drake <fdrake@acm.org>
parents: 8723
diff changeset
222 This class is derived from \exception{EnvironmentError} and is used
10703
e4e800a78d8d Make internal module references hyperlinks wherever it makes sense.
Fred Drake <fdrake@acm.org>
parents: 10290
diff changeset
223 primarily as the \refmodule{os} module's \code{os.error} exception.
10057
075f871d80b5 OSError description: "as the by the" --> "as the"
Fred Drake <fdrake@acm.org>
parents: 9774
diff changeset
224 See \exception{EnvironmentError} above for a description of the
075f871d80b5 OSError description: "as the by the" --> "as the"
Fred Drake <fdrake@acm.org>
parents: 9774
diff changeset
225 possible associated values.
10076
cbf5503b32d5 Move \versionadded macros to end of descriptions.
Fred Drake <fdrake@acm.org>
parents: 10057
diff changeset
226 \versionadded{1.5.2}
8723
6794294eb014 Added descriptions of EnvironmentError and OSError; updated IOError to
Barry Warsaw <barry@python.org>
parents: 8721
diff changeset
227 \end{excdesc}
6794294eb014 Added descriptions of EnvironmentError and OSError; updated IOError to
Barry Warsaw <barry@python.org>
parents: 8721
diff changeset
228
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
229 \begin{excdesc}{OverflowError}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
230 % XXXJH reference to long's and/or int's?
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
231 Raised when the result of an arithmetic operation is too large to be
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
232 represented. This cannot occur for long integers (which would rather
8721
d7ca429ef1ab Logical markup.
Fred Drake <fdrake@acm.org>
parents: 8719
diff changeset
233 raise \exception{MemoryError} than give up). Because of the lack of
12270
f6b58b021e56 Revised / removed comments about string exceptions (relating to the
Fred Drake <fdrake@acm.org>
parents: 12268
diff changeset
234 standardization of floating point exception handling in C, most
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
235 floating point operations also aren't checked. For plain integers,
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
236 all operations that can overflow are checked except left shift, where
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
237 typical applications prefer to drop bits than raise an exception.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
238 \end{excdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
239
20290
acd8378216c3 Update the documentation to reflect the changes to ReferenceError.
Fred Drake <fdrake@acm.org>
parents: 20026
diff changeset
240 \begin{excdesc}{ReferenceError}
acd8378216c3 Update the documentation to reflect the changes to ReferenceError.
Fred Drake <fdrake@acm.org>
parents: 20026
diff changeset
241 This exception is raised when a weak reference proxy, created by the
acd8378216c3 Update the documentation to reflect the changes to ReferenceError.
Fred Drake <fdrake@acm.org>
parents: 20026
diff changeset
242 \function{\refmodule{weakref}.proxy()} function, is used to access
acd8378216c3 Update the documentation to reflect the changes to ReferenceError.
Fred Drake <fdrake@acm.org>
parents: 20026
diff changeset
243 an attribute of the referent after it has been garbage collected.
acd8378216c3 Update the documentation to reflect the changes to ReferenceError.
Fred Drake <fdrake@acm.org>
parents: 20026
diff changeset
244 For more information on weak references, see the \refmodule{weakref}
acd8378216c3 Update the documentation to reflect the changes to ReferenceError.
Fred Drake <fdrake@acm.org>
parents: 20026
diff changeset
245 module.
acd8378216c3 Update the documentation to reflect the changes to ReferenceError.
Fred Drake <fdrake@acm.org>
parents: 20026
diff changeset
246 \versionadded[Previously known as the
acd8378216c3 Update the documentation to reflect the changes to ReferenceError.
Fred Drake <fdrake@acm.org>
parents: 20026
diff changeset
247 \exception{\refmodule{weakref}.ReferenceError}
acd8378216c3 Update the documentation to reflect the changes to ReferenceError.
Fred Drake <fdrake@acm.org>
parents: 20026
diff changeset
248 exception]{2.2}
acd8378216c3 Update the documentation to reflect the changes to ReferenceError.
Fred Drake <fdrake@acm.org>
parents: 20026
diff changeset
249 \end{excdesc}
acd8378216c3 Update the documentation to reflect the changes to ReferenceError.
Fred Drake <fdrake@acm.org>
parents: 20026
diff changeset
250
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
251 \begin{excdesc}{RuntimeError}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
252 Raised when an error is detected that doesn't fall in any of the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
253 other categories. The associated value is a string indicating what
6384
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
254 precisely went wrong. (This exception is mostly a relic from a
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
255 previous version of the interpreter; it is not used very much any
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
256 more.)
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
257 \end{excdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
258
17662
5b6d5961c9e3 Add documentation for the StopIteration exception.
Fred Drake <fdrake@acm.org>
parents: 15618
diff changeset
259 \begin{excdesc}{StopIteration}
5b6d5961c9e3 Add documentation for the StopIteration exception.
Fred Drake <fdrake@acm.org>
parents: 15618
diff changeset
260 Raised by an iterator's \method{next()} method to signal that there
5b6d5961c9e3 Add documentation for the StopIteration exception.
Fred Drake <fdrake@acm.org>
parents: 15618
diff changeset
261 are no further values.
5b6d5961c9e3 Add documentation for the StopIteration exception.
Fred Drake <fdrake@acm.org>
parents: 15618
diff changeset
262 This is derived from \exception{Exception} rather than
5b6d5961c9e3 Add documentation for the StopIteration exception.
Fred Drake <fdrake@acm.org>
parents: 15618
diff changeset
263 \exception{StandardError}, since this is not considered an error in
5b6d5961c9e3 Add documentation for the StopIteration exception.
Fred Drake <fdrake@acm.org>
parents: 15618
diff changeset
264 its normal application.
17663
d76649bd38d0 The general iteration support is part of 2.2, not 2.1 -- fixed the version
Fred Drake <fdrake@acm.org>
parents: 17662
diff changeset
265 \versionadded{2.2}
17662
5b6d5961c9e3 Add documentation for the StopIteration exception.
Fred Drake <fdrake@acm.org>
parents: 15618
diff changeset
266 \end{excdesc}
5b6d5961c9e3 Add documentation for the StopIteration exception.
Fred Drake <fdrake@acm.org>
parents: 15618
diff changeset
267
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
268 \begin{excdesc}{SyntaxError}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
269 % XXXJH xref to these functions?
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
270 Raised when the parser encounters a syntax error. This may occur in
8721
d7ca429ef1ab Logical markup.
Fred Drake <fdrake@acm.org>
parents: 8719
diff changeset
271 an \keyword{import} statement, in an \keyword{exec} statement, in a call
d7ca429ef1ab Logical markup.
Fred Drake <fdrake@acm.org>
parents: 8719
diff changeset
272 to the built-in function \function{eval()} or \function{input()}, or
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
273 when reading the initial script or standard input (also
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
274 interactively).
6384
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
275
20026
7c5cd685c1de Added reference to Tutorial section on user-defined exceptions for
Fred Drake <fdrake@acm.org>
parents: 18835
diff changeset
276 Instances of this class have atttributes \member{filename},
7c5cd685c1de Added reference to Tutorial section on user-defined exceptions for
Fred Drake <fdrake@acm.org>
parents: 18835
diff changeset
277 \member{lineno}, \member{offset} and \member{text} for easier access
7c5cd685c1de Added reference to Tutorial section on user-defined exceptions for
Fred Drake <fdrake@acm.org>
parents: 18835
diff changeset
278 to the details. \function{str()} of the exception instance returns
7c5cd685c1de Added reference to Tutorial section on user-defined exceptions for
Fred Drake <fdrake@acm.org>
parents: 18835
diff changeset
279 only the message.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
280 \end{excdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
281
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
282 \begin{excdesc}{SystemError}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
283 Raised when the interpreter finds an internal error, but the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
284 situation does not look so serious to cause it to abandon all hope.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
285 The associated value is a string indicating what went wrong (in
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
286 low-level terms).
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
287
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
288 You should report this to the author or maintainer of your Python
20026
7c5cd685c1de Added reference to Tutorial section on user-defined exceptions for
Fred Drake <fdrake@acm.org>
parents: 18835
diff changeset
289 interpreter. Be sure to report the version of the Python
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
290 interpreter (\code{sys.version}; it is also printed at the start of an
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
291 interactive Python session), the exact error message (the exception's
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
292 associated value) and if possible the source of the program that
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
293 triggered the error.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
294 \end{excdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
295
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
296 \begin{excdesc}{SystemExit}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
297 % XXXJH xref to module sys?
8721
d7ca429ef1ab Logical markup.
Fred Drake <fdrake@acm.org>
parents: 8719
diff changeset
298 This exception is raised by the \function{sys.exit()} function. When it
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
299 is not handled, the Python interpreter exits; no stack traceback is
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
300 printed. If the associated value is a plain integer, it specifies the
12270
f6b58b021e56 Revised / removed comments about string exceptions (relating to the
Fred Drake <fdrake@acm.org>
parents: 12268
diff changeset
301 system exit status (passed to C's \cfunction{exit()} function); if it is
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
302 \code{None}, the exit status is zero; if it has another type (such as
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
303 a string), the object's value is printed and the exit status is one.
6384
238a8b6096e1 Documented new exceptions and exception classes.
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
304
12270
f6b58b021e56 Revised / removed comments about string exceptions (relating to the
Fred Drake <fdrake@acm.org>
parents: 12268
diff changeset
305 Instances have an attribute \member{code} which is set to the
f6b58b021e56 Revised / removed comments about string exceptions (relating to the
Fred Drake <fdrake@acm.org>
parents: 12268
diff changeset
306 proposed exit status or error message (defaulting to \code{None}).
f6b58b021e56 Revised / removed comments about string exceptions (relating to the
Fred Drake <fdrake@acm.org>
parents: 12268
diff changeset
307 Also, this exception derives directly from \exception{Exception} and
f6b58b021e56 Revised / removed comments about string exceptions (relating to the
Fred Drake <fdrake@acm.org>
parents: 12268
diff changeset
308 not \exception{StandardError}, since it is not technically an error.
f6b58b021e56 Revised / removed comments about string exceptions (relating to the
Fred Drake <fdrake@acm.org>
parents: 12268
diff changeset
309
8721
d7ca429ef1ab Logical markup.
Fred Drake <fdrake@acm.org>
parents: 8719
diff changeset
310 A call to \function{sys.exit()} is translated into an exception so that
d7ca429ef1ab Logical markup.
Fred Drake <fdrake@acm.org>
parents: 8719
diff changeset
311 clean-up handlers (\keyword{finally} clauses of \keyword{try} statements)
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
312 can be executed, and so that a debugger can execute a script without
8721
d7ca429ef1ab Logical markup.
Fred Drake <fdrake@acm.org>
parents: 8719
diff changeset
313 running the risk of losing control. The \function{os._exit()} function
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
314 can be used if it is absolutely positively necessary to exit
18811
29e661c52c0b Add StopIteration to the list of exceptions *not* derived from StandardError.
Fred Drake <fdrake@acm.org>
parents: 18488
diff changeset
315 immediately (for example, in the child process after a call to
29e661c52c0b Add StopIteration to the list of exceptions *not* derived from StandardError.
Fred Drake <fdrake@acm.org>
parents: 18488
diff changeset
316 \function{fork()}).
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
317 \end{excdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
318
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
319 \begin{excdesc}{TypeError}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
320 Raised when a built-in operation or function is applied to an object
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
321 of inappropriate type. The associated value is a string giving
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
322 details about the type mismatch.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
323 \end{excdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
324
12270
f6b58b021e56 Revised / removed comments about string exceptions (relating to the
Fred Drake <fdrake@acm.org>
parents: 12268
diff changeset
325 \begin{excdesc}{UnboundLocalError}
f6b58b021e56 Revised / removed comments about string exceptions (relating to the
Fred Drake <fdrake@acm.org>
parents: 12268
diff changeset
326 Raised when a reference is made to a local variable in a function or
f6b58b021e56 Revised / removed comments about string exceptions (relating to the
Fred Drake <fdrake@acm.org>
parents: 12268
diff changeset
327 method, but no value has been bound to that variable. This is a
f6b58b021e56 Revised / removed comments about string exceptions (relating to the
Fred Drake <fdrake@acm.org>
parents: 12268
diff changeset
328 subclass of \exception{NameError}.
13222
5dd381aeb23b Update version numbering from 1.6 to 2.0.
Fred Drake <fdrake@acm.org>
parents: 12410
diff changeset
329 \versionadded{2.0}
12270
f6b58b021e56 Revised / removed comments about string exceptions (relating to the
Fred Drake <fdrake@acm.org>
parents: 12268
diff changeset
330 \end{excdesc}
f6b58b021e56 Revised / removed comments about string exceptions (relating to the
Fred Drake <fdrake@acm.org>
parents: 12268
diff changeset
331
12268
9e1f60976209 Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
332 \begin{excdesc}{UnicodeError}
9e1f60976209 Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
333 Raised when a Unicode-related encoding or decoding error occurs. It
9e1f60976209 Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
334 is a subclass of \exception{ValueError}.
13222
5dd381aeb23b Update version numbering from 1.6 to 2.0.
Fred Drake <fdrake@acm.org>
parents: 12410
diff changeset
335 \versionadded{2.0}
12268
9e1f60976209 Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
336 \end{excdesc}
9e1f60976209 Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
337
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
338 \begin{excdesc}{ValueError}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
339 Raised when a built-in operation or function receives an argument
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
340 that has the right type but an inappropriate value, and the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
341 situation is not described by a more precise exception such as
8721
d7ca429ef1ab Logical markup.
Fred Drake <fdrake@acm.org>
parents: 8719
diff changeset
342 \exception{IndexError}.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
343 \end{excdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
344
12410
5b870c0ea7b6 Added documentation for WindowsError; omission noted by Michal Bozon
Fred Drake <fdrake@acm.org>
parents: 12380
diff changeset
345 \begin{excdesc}{WindowsError}
5b870c0ea7b6 Added documentation for WindowsError; omission noted by Michal Bozon
Fred Drake <fdrake@acm.org>
parents: 12380
diff changeset
346 Raised when a Windows-specific error occurs or when the error number
5b870c0ea7b6 Added documentation for WindowsError; omission noted by Michal Bozon
Fred Drake <fdrake@acm.org>
parents: 12380
diff changeset
347 does not correspond to an \cdata{errno} value. The
5b870c0ea7b6 Added documentation for WindowsError; omission noted by Michal Bozon
Fred Drake <fdrake@acm.org>
parents: 12380
diff changeset
348 \member{errno} and \member{strerror} values are created from the
5b870c0ea7b6 Added documentation for WindowsError; omission noted by Michal Bozon
Fred Drake <fdrake@acm.org>
parents: 12380
diff changeset
349 return values of the \cfunction{GetLastError()} and
5b870c0ea7b6 Added documentation for WindowsError; omission noted by Michal Bozon
Fred Drake <fdrake@acm.org>
parents: 12380
diff changeset
350 \cfunction{FormatMessage()} functions from the Windows Platform API.
5b870c0ea7b6 Added documentation for WindowsError; omission noted by Michal Bozon
Fred Drake <fdrake@acm.org>
parents: 12380
diff changeset
351 This is a subclass of \exception{OSError}.
13222
5dd381aeb23b Update version numbering from 1.6 to 2.0.
Fred Drake <fdrake@acm.org>
parents: 12410
diff changeset
352 \versionadded{2.0}
12410
5b870c0ea7b6 Added documentation for WindowsError; omission noted by Michal Bozon
Fred Drake <fdrake@acm.org>
parents: 12380
diff changeset
353 \end{excdesc}
5b870c0ea7b6 Added documentation for WindowsError; omission noted by Michal Bozon
Fred Drake <fdrake@acm.org>
parents: 12380
diff changeset
354
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
355 \begin{excdesc}{ZeroDivisionError}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
356 Raised when the second argument of a division or modulo operation is
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
357 zero. The associated value is a string indicating the type of the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
358 operands and the operation.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
359 \end{excdesc}
15618
d3e86ff893b1 Document warning categories.
Guido van Rossum <guido@python.org>
parents: 15333
diff changeset
360
d3e86ff893b1 Document warning categories.
Guido van Rossum <guido@python.org>
parents: 15333
diff changeset
361
20026
7c5cd685c1de Added reference to Tutorial section on user-defined exceptions for
Fred Drake <fdrake@acm.org>
parents: 18835
diff changeset
362 \setindexsubitem{(built-in warning)}
15618
d3e86ff893b1 Document warning categories.
Guido van Rossum <guido@python.org>
parents: 15333
diff changeset
363
d3e86ff893b1 Document warning categories.
Guido van Rossum <guido@python.org>
parents: 15333
diff changeset
364 The following exceptions are used as warning categories; see the
d3e86ff893b1 Document warning categories.
Guido van Rossum <guido@python.org>
parents: 15333
diff changeset
365 \module{warnings} module for more information.
d3e86ff893b1 Document warning categories.
Guido van Rossum <guido@python.org>
parents: 15333
diff changeset
366
d3e86ff893b1 Document warning categories.
Guido van Rossum <guido@python.org>
parents: 15333
diff changeset
367 \begin{excdesc}{Warning}
d3e86ff893b1 Document warning categories.
Guido van Rossum <guido@python.org>
parents: 15333
diff changeset
368 Base class for warning categories.
d3e86ff893b1 Document warning categories.
Guido van Rossum <guido@python.org>
parents: 15333
diff changeset
369 \end{excdesc}
d3e86ff893b1 Document warning categories.
Guido van Rossum <guido@python.org>
parents: 15333
diff changeset
370
d3e86ff893b1 Document warning categories.
Guido van Rossum <guido@python.org>
parents: 15333
diff changeset
371 \begin{excdesc}{UserWarning}
d3e86ff893b1 Document warning categories.
Guido van Rossum <guido@python.org>
parents: 15333
diff changeset
372 Base class for warnings generated by user code.
d3e86ff893b1 Document warning categories.
Guido van Rossum <guido@python.org>
parents: 15333
diff changeset
373 \end{excdesc}
d3e86ff893b1 Document warning categories.
Guido van Rossum <guido@python.org>
parents: 15333
diff changeset
374
d3e86ff893b1 Document warning categories.
Guido van Rossum <guido@python.org>
parents: 15333
diff changeset
375 \begin{excdesc}{DeprecationWarning}
d3e86ff893b1 Document warning categories.
Guido van Rossum <guido@python.org>
parents: 15333
diff changeset
376 Base class for warnings about deprecated features.
d3e86ff893b1 Document warning categories.
Guido van Rossum <guido@python.org>
parents: 15333
diff changeset
377 \end{excdesc}
d3e86ff893b1 Document warning categories.
Guido van Rossum <guido@python.org>
parents: 15333
diff changeset
378
d3e86ff893b1 Document warning categories.
Guido van Rossum <guido@python.org>
parents: 15333
diff changeset
379 \begin{excdesc}{SyntaxWarning}
d3e86ff893b1 Document warning categories.
Guido van Rossum <guido@python.org>
parents: 15333
diff changeset
380 Base class for warnings about dubious syntax
d3e86ff893b1 Document warning categories.
Guido van Rossum <guido@python.org>
parents: 15333
diff changeset
381 \end{excdesc}
d3e86ff893b1 Document warning categories.
Guido van Rossum <guido@python.org>
parents: 15333
diff changeset
382
d3e86ff893b1 Document warning categories.
Guido van Rossum <guido@python.org>
parents: 15333
diff changeset
383 \begin{excdesc}{RuntimeWarning}
d3e86ff893b1 Document warning categories.
Guido van Rossum <guido@python.org>
parents: 15333
diff changeset
384 Base class for warnings about dubious runtime behavior.
d3e86ff893b1 Document warning categories.
Guido van Rossum <guido@python.org>
parents: 15333
diff changeset
385 \end{excdesc}