diff options
Diffstat (limited to 'Doc/lib/libexcs.tex')
| -rw-r--r-- | Doc/lib/libexcs.tex | 427 |
1 files changed, 0 insertions, 427 deletions
diff --git a/Doc/lib/libexcs.tex b/Doc/lib/libexcs.tex deleted file mode 100644 index 74531d3..0000000 --- a/Doc/lib/libexcs.tex +++ /dev/null @@ -1,427 +0,0 @@ -\section{Built-in Exceptions} - -\declaremodule{standard}{exceptions} -\modulesynopsis{Standard exception classes.} - - -Exceptions should be class objects. -The exceptions are defined in the module \module{exceptions}. This -module never needs to be imported explicitly: the exceptions are -provided in the built-in namespace as well as the \module{exceptions} -module. - -For class exceptions, in a \keyword{try}\stindex{try} statement with -an \keyword{except}\stindex{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. - -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 -\keyword{raise}\stindex{raise} statement. If the exception class is -derived from the standard root class \exception{BaseException}, the -associated value is present as the exception instance's \member{args} -attribute. - -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 -situation in which the interpreter raises the same exception; but -beware that there is nothing to prevent user code from raising an -inappropriate error. - -The built-in exception classes can be sub-classed to define new -exceptions; programmers are encouraged to at least derive new -exceptions from the \exception{Exception} class and not -\exception{BaseException}. More -information on defining exceptions is available in the -\citetitle[../tut/tut.html]{Python Tutorial} under the heading -``User-defined Exceptions.'' - -\setindexsubitem{(built-in exception base class)} - -The following exceptions are only used as base classes for other -exceptions. - -\begin{excdesc}{BaseException} -The base class for all built-in exceptions. It is not meant to be directly -inherited by user-defined classes (for that use \exception{Exception}). If -\function{str()} or \function{unicode()} is called on an instance of this -class, the representation of the argument(s) to the instance are returned or -the emptry string when there were no arguments. All arguments are -stored in \member{args} as a tuple. -\versionadded{2.5} -\end{excdesc} - -\begin{excdesc}{Exception} -All built-in, non-system-exiting exceptions are derived -from this class. All user-defined exceptions should also be derived -from this class. -\versionchanged[Changed to inherit from \exception{BaseException}]{2.5} -\end{excdesc} - -\begin{excdesc}{ArithmeticError} -The base class for those built-in exceptions that are raised for -various arithmetic errors: \exception{OverflowError}, -\exception{ZeroDivisionError}, \exception{FloatingPointError}. -\end{excdesc} - -\begin{excdesc}{LookupError} -The base class for the exceptions that are raised when a key or -index used on a mapping or sequence is invalid: \exception{IndexError}, -\exception{KeyError}. This can be raised directly by -\function{sys.setdefaultencoding()}. -\end{excdesc} - -\begin{excdesc}{EnvironmentError} -The base class for exceptions that -can occur outside the Python system: \exception{IOError}, -\exception{OSError}. When exceptions of this type are created with a -2-tuple, the first item is available on the instance's \member{errno} -attribute (it is assumed to be an error number), and the second item -is available on the \member{strerror} attribute (it is usually the -associated error message). The tuple itself is also available on the -\member{args} attribute. -\versionadded{1.5.2} - -When an \exception{EnvironmentError} exception is instantiated with a -3-tuple, the first two items are available as above, while the third -item is available on the \member{filename} attribute. However, for -backwards compatibility, the \member{args} attribute contains only a -2-tuple of the first two constructor arguments. - -The \member{filename} attribute is \code{None} when this exception is -created with other than 3 arguments. The \member{errno} and -\member{strerror} attributes are also \code{None} when the instance was -created with other than 2 or 3 arguments. In this last case, -\member{args} contains the verbatim constructor arguments as a tuple. -\end{excdesc} - - -\setindexsubitem{(built-in exception)} - -The following exceptions are the exceptions that are actually raised. - -\begin{excdesc}{AssertionError} -\stindex{assert} -Raised when an \keyword{assert} statement fails. -\end{excdesc} - -\begin{excdesc}{AttributeError} -% xref to attribute reference? - Raised when an attribute reference or assignment fails. (When an - object does not support attribute references or attribute assignments - at all, \exception{TypeError} is raised.) -\end{excdesc} - -\begin{excdesc}{EOFError} -% XXXJH xrefs here - Raised when attempting to read beyond the end of a file. -% XXXJH xrefs here - (N.B.: the \method{read()} and \method{readline()} methods of file - objects return an empty string when they hit \EOF.) -\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 \longprogramopt{with-fpectl} option, or the - \constant{WANT_SIGFPE_HANDLER} symbol is defined in the - \file{pyconfig.h} file. -\end{excdesc} - -\begin{excdesc}{GeneratorExit} - Raise when a generator's \method{close()} method is called. - \versionadded{2.5} - \versionchanged[Changed to inherit from Exception instead of - StandardError]{3.0} -\end{excdesc} - -\begin{excdesc}{IOError} -% XXXJH xrefs here - Raised when an I/O operation (such as a \keyword{print} statement, - the built-in \function{open()} function or a method of a file - object) fails for an I/O-related reason, e.g., ``file not found'' or - ``disk full''. - - This class is derived from \exception{EnvironmentError}. See the - discussion above for more information on exception instance - attributes. -\end{excdesc} - -\begin{excdesc}{ImportError} -% XXXJH xref to import statement? - Raised when an \keyword{import} statement fails to find the module - definition or when a \code{from \textrm{\ldots} import} fails to find a - name that is to be imported. -\end{excdesc} - -\begin{excdesc}{IndexError} -% XXXJH xref to sequences - Raised when a sequence subscript is out of range. (Slice indices are - silently truncated to fall in the allowed range; if an index is not a - plain integer, \exception{TypeError} is raised.) -\end{excdesc} - -\begin{excdesc}{KeyError} -% XXXJH xref to mapping objects? - Raised when a mapping (dictionary) key is not found in the set of - existing keys. -\end{excdesc} - -\begin{excdesc}{KeyboardInterrupt} - Raised when the user hits the interrupt key (normally - \kbd{Control-C} or \kbd{Delete}). During execution, a check for - interrupts is made regularly. -% XXX(hylton) xrefs here - The exception inherits from \exception{BaseException} so as to not be - accidentally caught by code that catches \exception{Exception} and thus - prevent the interpreter from exiting. - \versionchanged[Changed to inherit from \exception{BaseException}]{2.5} -\end{excdesc} - -\begin{excdesc}{MemoryError} - Raised when an operation runs out of memory but the situation may - still be rescued (by deleting some objects). The associated value is - a string indicating what kind of (internal) operation ran out of memory. - Note that because of the underlying memory management architecture - (C's \cfunction{malloc()} function), the interpreter may not - always be able to completely recover from this situation; it - nevertheless raises an exception so that a stack traceback can be - printed, in case a run-away program was the cause. -\end{excdesc} - -\begin{excdesc}{NameError} - Raised when a local or global name is not found. This applies only - to unqualified names. The associated value is an error message that - includes the name that could not be found. -\end{excdesc} - -\begin{excdesc}{NotImplementedError} - This exception is derived from \exception{RuntimeError}. In user - defined base classes, abstract methods should raise this exception - when they require derived classes to override the method. - \versionadded{1.5.2} -\end{excdesc} - -\begin{excdesc}{OSError} - %xref for os module - This class is derived from \exception{EnvironmentError} and is used - primarily as the \refmodule{os} module's \code{os.error} exception. - See \exception{EnvironmentError} above for a description of the - possible associated values. - \versionadded{1.5.2} -\end{excdesc} - -\begin{excdesc}{OverflowError} -% XXXJH reference to long's and/or int's? - Raised when the result of an arithmetic operation is too large to be - represented. This cannot occur for long integers (which would rather - raise \exception{MemoryError} than give up). Because of the lack of - standardization of floating point exception handling in C, most - floating point operations also aren't checked. For plain integers, - all operations that can overflow are checked except left shift, where - typical applications prefer to drop bits than raise an exception. -\end{excdesc} - -\begin{excdesc}{ReferenceError} - This exception is raised when a weak reference proxy, created by the - \function{\refmodule{weakref}.proxy()} function, is used to access - an attribute of the referent after it has been garbage collected. - For more information on weak references, see the \refmodule{weakref} - module. - \versionadded[Previously known as the - \exception{\refmodule{weakref}.ReferenceError} - exception]{2.2} -\end{excdesc} - -\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 mostly a relic from a - previous version of the interpreter; it is not used very much any - more.) -\end{excdesc} - -\begin{excdesc}{StopIteration} - Raised by builtin \function{next()} and an iterator's \method{__next__()} - method to signal that there are no further values. - \versionadded{2.2} - \versionchanged[Changed to inherit from Exception instead of - StandardError]{3.0} -\end{excdesc} - - -\begin{excdesc}{SyntaxError} -% XXXJH xref to these functions? - Raised when the parser encounters a syntax error. This may occur in - an \keyword{import} statement, in a call to the built-in functions - \function{exec()}, \function{eval()} or - \function{input()}, or when reading the initial script or standard - input (also interactively). - - Instances of this class have attributes \member{filename}, - \member{lineno}, \member{offset} and \member{text} for easier access - to the details. \function{str()} of the exception instance returns - only the message. -\end{excdesc} - -\begin{excdesc}{SystemError} - Raised when the interpreter finds an internal error, but the - situation does not look so serious to cause it to abandon all hope. - The associated value is a string indicating what went wrong (in - low-level terms). - - You should report this to the author or maintainer of your Python - interpreter. Be sure to report the version of the Python - interpreter (\code{sys.version}; it is also printed at the start of an - interactive Python session), the exact error message (the exception's - associated value) and if possible the source of the program that - triggered the error. -\end{excdesc} - -\begin{excdesc}{SystemExit} -% XXX(hylton) xref to module sys? - This exception is raised by the \function{sys.exit()} function. When it - is not handled, the Python interpreter exits; no stack traceback is - printed. If the associated value is a plain integer, it specifies the - system exit status (passed to C's \cfunction{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. - - Instances have an attribute \member{code} which is set to the - proposed exit status or error message (defaulting to \code{None}). - Also, this exception derives directly from \exception{BaseException} and - not \exception{Exception}, since it is not technically an error. - - A call to \function{sys.exit()} is translated into an exception so that - clean-up handlers (\keyword{finally} clauses of \keyword{try} statements) - can be executed, and so that a debugger can execute a script without - running the risk of losing control. The \function{os._exit()} function - can be used if it is absolutely positively necessary to exit - immediately (for example, in the child process after a call to - \function{fork()}). - - The exception inherits from \exception{BaseException} instead of - \exception{Exception} so that it is not - accidentally caught by code that catches \exception{Exception}. This allows - the exception to properly propagate up and cause the interpreter to exit. - \versionchanged[Changed to inherit from \exception{BaseException}]{2.5} -\end{excdesc} - -\begin{excdesc}{TypeError} - Raised when an operation or function is applied to an object - of inappropriate type. The associated value is a string giving - details about the type mismatch. -\end{excdesc} - -\begin{excdesc}{UnboundLocalError} - Raised when a reference is made to a local variable in a function or - method, but no value has been bound to that variable. This is a - subclass of \exception{NameError}. -\versionadded{2.0} -\end{excdesc} - -\begin{excdesc}{UnicodeError} - Raised when a Unicode-related encoding or decoding error occurs. It - is a subclass of \exception{ValueError}. -\versionadded{2.0} -\end{excdesc} - -\begin{excdesc}{UnicodeEncodeError} - Raised when a Unicode-related error occurs during encoding. It - is a subclass of \exception{UnicodeError}. -\versionadded{2.3} -\end{excdesc} - -\begin{excdesc}{UnicodeDecodeError} - Raised when a Unicode-related error occurs during decoding. It - is a subclass of \exception{UnicodeError}. -\versionadded{2.3} -\end{excdesc} - -\begin{excdesc}{UnicodeTranslateError} - Raised when a Unicode-related error occurs during translating. It - is a subclass of \exception{UnicodeError}. -\versionadded{2.3} -\end{excdesc} - -\begin{excdesc}{ValueError} - Raised when a built-in operation or function receives an argument - that has the right type but an inappropriate value, and the - situation is not described by a more precise exception such as - \exception{IndexError}. -\end{excdesc} - -\begin{excdesc}{WindowsError} - Raised when a Windows-specific error occurs or when the error number - does not correspond to an \cdata{errno} value. The - \member{winerror} and \member{strerror} values are created from the - return values of the \cfunction{GetLastError()} and - \cfunction{FormatMessage()} functions from the Windows Platform API. - The \member{errno} value maps the \member{winerror} value to - corresponding \code{errno.h} values. - This is a subclass of \exception{OSError}. -\versionadded{2.0} -\versionchanged[Previous versions put the \cfunction{GetLastError()} -codes into \member{errno}]{2.5} -\end{excdesc} - -\begin{excdesc}{ZeroDivisionError} - Raised when the second argument of a division or modulo operation is - zero. The associated value is a string indicating the type of the - operands and the operation. -\end{excdesc} - - -\setindexsubitem{(built-in warning)} - -The following exceptions are used as warning categories; see the -\refmodule{warnings} module for more information. - -\begin{excdesc}{Warning} -Base class for warning categories. -\end{excdesc} - -\begin{excdesc}{UserWarning} -Base class for warnings generated by user code. -\end{excdesc} - -\begin{excdesc}{DeprecationWarning} -Base class for warnings about deprecated features. -\end{excdesc} - -\begin{excdesc}{PendingDeprecationWarning} -Base class for warnings about features which will be deprecated in the future. -\end{excdesc} - -\begin{excdesc}{SyntaxWarning} -Base class for warnings about dubious syntax -\end{excdesc} - -\begin{excdesc}{RuntimeWarning} -Base class for warnings about dubious runtime behavior. -\end{excdesc} - -\begin{excdesc}{FutureWarning} -Base class for warnings about constructs that will change semantically -in the future. -\end{excdesc} - -\begin{excdesc}{ImportWarning} -Base class for warnings about probable mistakes in module imports. -\versionadded{2.5} -\end{excdesc} - -\begin{excdesc}{UnicodeWarning} -Base class for warnings related to Unicode. -\versionadded{2.5} -\end{excdesc} - -The class hierarchy for built-in exceptions is: - -\verbatiminput{../../Lib/test/exception_hierarchy.txt} |