diff options
| -rw-r--r-- | Doc/lib/libexcs.tex | 137 | ||||
| -rw-r--r-- | Doc/libexcs.tex | 137 |
2 files changed, 234 insertions, 40 deletions
diff --git a/Doc/lib/libexcs.tex b/Doc/lib/libexcs.tex index 7cc9195..e5dba34 100644 --- a/Doc/lib/libexcs.tex +++ b/Doc/lib/libexcs.tex @@ -1,25 +1,99 @@ \section{Built-in Exceptions} -Exceptions are string objects. Two distinct string objects with the -same value are 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. - -The following exceptions can be generated by the interpreter or -built-in functions. Except where mentioned, they have an `associated -value' indicating the detailed cause of the error. This may be a -string or a tuple containing several items of information (e.g., an -error code and a string explaining the code). +Exceptions can be class objects or string objects. While +traditionally, most exceptions have been string objects, in Python +1.5a4, all standard exceptions have been converted to class objects, +and users are encouraged to the the same. The source code for those +exceptions is present in the standard library module +\code{exceptions}; this module never needs to be imported explicitly. + +For backward compatibility, when Python is invoked with the \code{-X} +option, the standard exceptions are strings. This may be needed to +run some code that breaks because of the different semantics of class +based exceptions. The \code{-X} option will become obsolete in future +Python versions, so the recommended solution is to fix the code. + +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. + +For class exceptions, in a \code{try} statement with an\code{except} +clause that mentions a particular class, that clause also handles +any exception classes derived from that class (but not exception +classes from which \emph{it} is derived). Two exception classes +that are not related via subclassing are never equivalent, even if +they have the same name. +\stindex{try} +\stindex{except} + +The built-in exceptions listed below can be generated by the +interpreter or built-in functions. Except where mentioned, they have +an ``associated value'' indicating the detailed cause of the error. +This may be a string or a tuple containing several items of +information (e.g., an error code and a string explaining the code). +The associated value is the second argument to the \code{raise} +statement. For string exceptions, the associated value itself will be +stored in the variable named as the second argument of the +\code{except} clause (if any). For class exceptions derived from +the root class \code{Exception}, that variable receives the exception +instance, and the associated value is present as the exception +instance's \code{args} attribute; this is a tuple even if the second +argument to \code{raise} was not (then it is a singleton tuple). +\stindex{raise} User code can raise built-in exceptions. This can be used to test an -exception handler or to report an error condition `just like' the +exception handler or to report an error condition ``just like'' the situation in which the interpreter raises the same exception; but beware that there is nothing to prevent user code from raising an inappropriate error. -\renewcommand{\indexsubitem}{(built-in exception)} +\renewcommand{\indexsubitem}{(built-in exception base class)} + +The following exceptions are only used as base classes for other +exceptions. When string-based standard exceptions are used, they +are tuples containing the directly derived classes. + +\begin{excdesc}{Exception} +The root class for exceptions. All built-in exceptions are derived +from this class. All user-defined exceptions should also be derived +from this class, but this is not (yet) enforced. The \code{str()} +function, when applied to an instance of this class (or most derived +classes) returns the string value of the argument or arguments, or an +empty string if no arguments were given to the constructor. +\end{excdesc} + +\begin{excdesc}{StandardError} +The base class for built-in exceptions. All built-in exceptions are +derived from this class, which is itself derived from the root class +\code{Exception}. For backward compatibility, when used as a +sequence, this accesses the arguments given to the constructor. +\end{excdesc} + +\begin{excdesc}{ArithmeticError} +The base class for those built-in exceptions that are raised for +various arithmetic errors: \code{OverflowError}, +\code{ZeroDivisionError}, \code{FloatingPointError}. +\end{excdesc} + +\begin{excdesc}{LookupError} +The base class for thise exceptions that are raised when a key or +index used on a mapping or sequence is invalid: \code{IndexError}, +\code{KeyError}. +\end{excdesc} + +\renewcommand{\indexsubitem}{(built-in exception base class)} + +The following exceptions are the exceptions that are actually raised. +They are class objects, except when the \code{-X} option is used to +revert back to string-based standard exceptions. + +\begin{excdesc}{AssertionError} +Raised when an \code{assert} statement fails. +\stindex{assert} +\end{excdesc} \begin{excdesc}{AttributeError} % xref to attribute reference? @@ -38,11 +112,24 @@ inappropriate error. objects return an empty string when they hit \EOF{}.) No associated value. \end{excdesc} +\begin{excdesc}{FloatingPointError} +Raised when a floating point operation fails. This exception is +always defined, but can only be raised when Python is configured with +the \code{--with-fpectl} option, or the \code{WANT_SIGFPE_HANDLER} +symbol is defined in the \file{config.h} file. +\end{excdesc} + \begin{excdesc}{IOError} % XXXJH xrefs here Raised when an I/O operation (such as a \code{print} statement, the built-in \code{open()} function or a method of a file object) fails - for an I/O-related reason, e.g., `file not found', `disk full'. + for an I/O-related reason, e.g., ``file not found'' or ``disk full''. + +When class exceptions are used, and this exception is instantiated as +\code{IOError(errno, strerror)}, the instance has two additional +attributes \code{errno} and \code{strerror} set to the error code and +the error message, respectively. These attributes default to +\code{None}. \end{excdesc} \begin{excdesc}{ImportError} @@ -106,10 +193,9 @@ inappropriate error. \begin{excdesc}{RuntimeError} Raised when an error is detected that doesn't fall in any of the other categories. The associated value is a string indicating what - precisely went wrong. (This exception is a relic from a previous - version of the interpreter; it is not used any more except by some - extension modules that haven't been converted to define their own - exceptions yet.) + precisely went wrong. (This exception is mostly a relic from a + previous version of the interpreter; it is not used very much any + more.) \end{excdesc} \begin{excdesc}{SyntaxError} @@ -119,6 +205,13 @@ inappropriate error. to the built-in function \code{eval()} or \code{input()}, or when reading the initial script or standard input (also interactively). + +When class exceptions are used, instances of this class have +atttributes \code{filename}, \code{lineno}, \code{offset} and +\code{text} for easier access to the details; for string exceptions, +the associated value is usually a tuple of the form +\code{(message, (filename, lineno, offset, text))}. +For class exceptions, \code{str()} returns only the message. \end{excdesc} \begin{excdesc}{SystemError} @@ -143,11 +236,15 @@ inappropriate error. system exit status (passed to \C{}'s \code{exit()} function); if it is \code{None}, the exit status is zero; if it has another type (such as a string), the object's value is printed and the exit status is one. + +When class exceptions are used, the instance has an attribute +\code{code} which is set to the proposed exit status or error message +(defaulting to \code{None}). A call to \code{sys.exit} is translated into an exception so that clean-up handlers (\code{finally} clauses of \code{try} statements) can be executed, and so that a debugger can execute a script without - running the risk of losing control. The \code{posix._exit()} function + running the risk of losing control. The \code{os._exit()} function can be used if it is absolutely positively necessary to exit immediately (e.g., after a \code{fork()} in the child process). \end{excdesc} diff --git a/Doc/libexcs.tex b/Doc/libexcs.tex index 7cc9195..e5dba34 100644 --- a/Doc/libexcs.tex +++ b/Doc/libexcs.tex @@ -1,25 +1,99 @@ \section{Built-in Exceptions} -Exceptions are string objects. Two distinct string objects with the -same value are 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. - -The following exceptions can be generated by the interpreter or -built-in functions. Except where mentioned, they have an `associated -value' indicating the detailed cause of the error. This may be a -string or a tuple containing several items of information (e.g., an -error code and a string explaining the code). +Exceptions can be class objects or string objects. While +traditionally, most exceptions have been string objects, in Python +1.5a4, all standard exceptions have been converted to class objects, +and users are encouraged to the the same. The source code for those +exceptions is present in the standard library module +\code{exceptions}; this module never needs to be imported explicitly. + +For backward compatibility, when Python is invoked with the \code{-X} +option, the standard exceptions are strings. This may be needed to +run some code that breaks because of the different semantics of class +based exceptions. The \code{-X} option will become obsolete in future +Python versions, so the recommended solution is to fix the code. + +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. + +For class exceptions, in a \code{try} statement with an\code{except} +clause that mentions a particular class, that clause also handles +any exception classes derived from that class (but not exception +classes from which \emph{it} is derived). Two exception classes +that are not related via subclassing are never equivalent, even if +they have the same name. +\stindex{try} +\stindex{except} + +The built-in exceptions listed below can be generated by the +interpreter or built-in functions. Except where mentioned, they have +an ``associated value'' indicating the detailed cause of the error. +This may be a string or a tuple containing several items of +information (e.g., an error code and a string explaining the code). +The associated value is the second argument to the \code{raise} +statement. For string exceptions, the associated value itself will be +stored in the variable named as the second argument of the +\code{except} clause (if any). For class exceptions derived from +the root class \code{Exception}, that variable receives the exception +instance, and the associated value is present as the exception +instance's \code{args} attribute; this is a tuple even if the second +argument to \code{raise} was not (then it is a singleton tuple). +\stindex{raise} User code can raise built-in exceptions. This can be used to test an -exception handler or to report an error condition `just like' the +exception handler or to report an error condition ``just like'' the situation in which the interpreter raises the same exception; but beware that there is nothing to prevent user code from raising an inappropriate error. -\renewcommand{\indexsubitem}{(built-in exception)} +\renewcommand{\indexsubitem}{(built-in exception base class)} + +The following exceptions are only used as base classes for other +exceptions. When string-based standard exceptions are used, they +are tuples containing the directly derived classes. + +\begin{excdesc}{Exception} +The root class for exceptions. All built-in exceptions are derived +from this class. All user-defined exceptions should also be derived +from this class, but this is not (yet) enforced. The \code{str()} +function, when applied to an instance of this class (or most derived +classes) returns the string value of the argument or arguments, or an +empty string if no arguments were given to the constructor. +\end{excdesc} + +\begin{excdesc}{StandardError} +The base class for built-in exceptions. All built-in exceptions are +derived from this class, which is itself derived from the root class +\code{Exception}. For backward compatibility, when used as a +sequence, this accesses the arguments given to the constructor. +\end{excdesc} + +\begin{excdesc}{ArithmeticError} +The base class for those built-in exceptions that are raised for +various arithmetic errors: \code{OverflowError}, +\code{ZeroDivisionError}, \code{FloatingPointError}. +\end{excdesc} + +\begin{excdesc}{LookupError} +The base class for thise exceptions that are raised when a key or +index used on a mapping or sequence is invalid: \code{IndexError}, +\code{KeyError}. +\end{excdesc} + +\renewcommand{\indexsubitem}{(built-in exception base class)} + +The following exceptions are the exceptions that are actually raised. +They are class objects, except when the \code{-X} option is used to +revert back to string-based standard exceptions. + +\begin{excdesc}{AssertionError} +Raised when an \code{assert} statement fails. +\stindex{assert} +\end{excdesc} \begin{excdesc}{AttributeError} % xref to attribute reference? @@ -38,11 +112,24 @@ inappropriate error. objects return an empty string when they hit \EOF{}.) No associated value. \end{excdesc} +\begin{excdesc}{FloatingPointError} +Raised when a floating point operation fails. This exception is +always defined, but can only be raised when Python is configured with +the \code{--with-fpectl} option, or the \code{WANT_SIGFPE_HANDLER} +symbol is defined in the \file{config.h} file. +\end{excdesc} + \begin{excdesc}{IOError} % XXXJH xrefs here Raised when an I/O operation (such as a \code{print} statement, the built-in \code{open()} function or a method of a file object) fails - for an I/O-related reason, e.g., `file not found', `disk full'. + for an I/O-related reason, e.g., ``file not found'' or ``disk full''. + +When class exceptions are used, and this exception is instantiated as +\code{IOError(errno, strerror)}, the instance has two additional +attributes \code{errno} and \code{strerror} set to the error code and +the error message, respectively. These attributes default to +\code{None}. \end{excdesc} \begin{excdesc}{ImportError} @@ -106,10 +193,9 @@ inappropriate error. \begin{excdesc}{RuntimeError} Raised when an error is detected that doesn't fall in any of the other categories. The associated value is a string indicating what - precisely went wrong. (This exception is a relic from a previous - version of the interpreter; it is not used any more except by some - extension modules that haven't been converted to define their own - exceptions yet.) + precisely went wrong. (This exception is mostly a relic from a + previous version of the interpreter; it is not used very much any + more.) \end{excdesc} \begin{excdesc}{SyntaxError} @@ -119,6 +205,13 @@ inappropriate error. to the built-in function \code{eval()} or \code{input()}, or when reading the initial script or standard input (also interactively). + +When class exceptions are used, instances of this class have +atttributes \code{filename}, \code{lineno}, \code{offset} and +\code{text} for easier access to the details; for string exceptions, +the associated value is usually a tuple of the form +\code{(message, (filename, lineno, offset, text))}. +For class exceptions, \code{str()} returns only the message. \end{excdesc} \begin{excdesc}{SystemError} @@ -143,11 +236,15 @@ inappropriate error. system exit status (passed to \C{}'s \code{exit()} function); if it is \code{None}, the exit status is zero; if it has another type (such as a string), the object's value is printed and the exit status is one. + +When class exceptions are used, the instance has an attribute +\code{code} which is set to the proposed exit status or error message +(defaulting to \code{None}). A call to \code{sys.exit} is translated into an exception so that clean-up handlers (\code{finally} clauses of \code{try} statements) can be executed, and so that a debugger can execute a script without - running the risk of losing control. The \code{posix._exit()} function + running the risk of losing control. The \code{os._exit()} function can be used if it is absolutely positively necessary to exit immediately (e.g., after a \code{fork()} in the child process). \end{excdesc} |