--- rest25/library/exceptions.rst	2008-12-19 16:58:08.000000000 +0900
+++ rest262/library/exceptions.rst	2009-04-07 00:06:53.000000000 +0900
@@ -1,92 +1,69 @@
+.. _bltin-exceptions:
 
 Built-in Exceptions
 ===================
 
 .. module:: exceptions
    :synopsis: Standard exception classes.
 
 
 Exceptions should be class objects.   The exceptions are defined in the module
 :mod:`exceptions`.  This module never needs to be imported explicitly: the
 exceptions are provided in the built-in namespace as well as the
 :mod:`exceptions` module.
 
-.. note::
-
-   In past versions of Python string exceptions were supported.  In Python 1.5 and
-   newer versions, all standard exceptions have been converted to class objects and
-   users are encouraged to do the same. String exceptions will raise a
-   ``DeprecationWarning`` in Python 2.5 and newer. In future versions, support for
-   string exceptions will be removed.
-
-   Two distinct string objects with the same value are considered different
-   exceptions.  This is done to force programmers to use exception names rather
-   than their string value when specifying exception handlers. The string value of
-   all built-in exceptions is their name, but this is not a requirement for user-
-   defined exceptions or exceptions defined by library modules.
-
 .. index::
    statement: try
    statement: except
 
 For class exceptions, in a :keyword:`try` statement with an :keyword:`except`
 clause that mentions a particular class, that clause also handles any exception
 classes derived from that class (but not exception classes from which *it* is
 derived).  Two exception classes that are not related via subclassing are never
 equivalent, even if they have the same name.
 
 .. index:: statement: raise
 
 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` statement.  For string exceptions, the associated value itself
-will be stored in the variable named as the second argument of the
-:keyword:`except` clause (if any).  For class exceptions, that variable receives
-the exception instance.  If the exception class is derived from the standard
+:keyword:`raise` statement.  If the exception class is derived from the standard
 root class :exc:`BaseException`, the associated value is present as the
-exception instance's :attr:`args` attribute.  If there is a single argument (as
-is preferred), it is bound to the :attr:`message` attribute.
+exception instance's :attr:`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
 :exc:`Exception` class and not :exc:`BaseException`.  More information on
-defining exceptions is available in the Python Tutorial (XXX reference:
-../tut/tut.html) under the heading "User-defined Exceptions."
+defining exceptions is available in the Python Tutorial under
+:ref:`tut-userexceptions`.
 
 The following exceptions are only used as base classes for other exceptions.
 
 
 .. exception:: BaseException
 
    The base class for all built-in exceptions.  It is not meant to be directly
    inherited by user-defined classes (for that use :exc:`Exception`).  If
    :func:`str` or :func:`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.  If only a single argument is passed in, it
-   is stored in the :attr:`message` attribute.  If more than one argument is passed
-   in, :attr:`message` is set to the empty string.  These semantics are meant to
-   reflect the fact that :attr:`message` is to store a text message explaining why
-   the exception had been raised.  If more data needs to be attached to the
-   exception, attach it through arbitrary attributes on the instance.  All
-   arguments are also stored in :attr:`args` as a tuple, but it will eventually be
-   deprecated and thus its use is discouraged.
+   representation of the argument(s) to the instance are returned or the empty
+   string when there were no arguments.  All arguments are  stored in :attr:`args`
+   as a tuple.
 
    .. versionadded:: 2.5
 
 
 .. exception:: 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:: 2.5
       Changed to inherit from :exc:`BaseException`.
 
@@ -138,106 +115,100 @@
 The following exceptions are the exceptions that are actually raised.
 
 
 .. exception:: AssertionError
 
    .. index:: statement: assert
 
    Raised when an :keyword:`assert` statement fails.
 
 
 .. exception:: AttributeError
 
-   Raised when an attribute reference or assignment fails.  (When an object does
-   not support attribute references or attribute assignments at all,
-   :exc:`TypeError` is raised.)
-
-   .. % xref to attribute reference?
+   Raised when an attribute reference (see :ref:`attribute-references`) or
+   assignment fails.  (When an object does not support attribute references or
+   attribute assignments at all, :exc:`TypeError` is raised.)
 
 
 .. exception:: EOFError
 
    Raised when one of the built-in functions (:func:`input` or :func:`raw_input`)
    hits an end-of-file condition (EOF) without reading any data. (N.B.: the
-   :meth:`read` and :meth:`readline` methods of file objects return an empty string
+   :meth:`file.read` and :meth:`file.readline` methods return an empty string
    when they hit EOF.)
 
-   .. % XXXJH xrefs here
-   .. % XXXJH xrefs here
-
 
 .. exception:: FloatingPointError
 
    Raised when a floating point operation fails.  This exception is always defined,
    but can only be raised when Python is configured with the
    :option:`--with-fpectl` option, or the :const:`WANT_SIGFPE_HANDLER` symbol is
    defined in the :file:`pyconfig.h` file.
 
 
 .. exception:: GeneratorExit
 
-   Raise when a generator's :meth:`close` method is called. It directly inherits
-   from :exc:`Exception` instead of :exc:`StandardError` since it is technically
-   not an error.
+   Raise when a :term:`generator`\'s :meth:`close` method is called.  It
+   directly inherits from :exc:`BaseException` instead of :exc:`StandardError` since
+   it is technically not an error.
 
    .. versionadded:: 2.5
 
+   .. versionchanged:: 2.6
+      Changed to inherit from :exc:`BaseException`.
 
 .. exception:: IOError
 
    Raised when an I/O operation (such as a :keyword:`print` statement, the built-in
    :func:`open` function or a method of a file object) fails for an I/O-related
    reason, e.g., "file not found" or "disk full".
 
-   .. % XXXJH xrefs here
-
    This class is derived from :exc:`EnvironmentError`.  See the discussion above
    for more information on exception instance attributes.
 
+   .. versionchanged:: 2.6
+      Changed :exc:`socket.error` to use this as a base class.
+
 
 .. exception:: ImportError
 
    Raised when an :keyword:`import` statement fails to find the module definition
    or when a ``from ... import`` fails to find a name that is to be imported.
 
-   .. % XXXJH xref to import statement?
-
 
 .. exception:: IndexError
 
    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,
    :exc:`TypeError` is raised.)
 
-   .. % XXXJH xref to sequences
+   .. XXX xref to sequences
 
 
 .. exception:: KeyError
 
    Raised when a mapping (dictionary) key is not found in the set of existing keys.
 
-   .. % XXXJH xref to mapping objects?
+   .. XXX xref to mapping objects?
 
 
 .. exception:: 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.
    Interrupts typed when a built-in function :func:`input` or :func:`raw_input` is
    waiting for input also raise this exception. The exception inherits from
    :exc:`BaseException` so as to not be accidentally caught by code that catches
    :exc:`Exception` and thus prevent the interpreter from exiting.
 
-   .. % XXX(hylton) xrefs here
-
    .. versionchanged:: 2.5
       Changed to inherit from :exc:`BaseException`.
 
 
 .. exception:: 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 :cfunc:`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
@@ -253,83 +224,87 @@
 
 .. exception:: NotImplementedError
 
    This exception is derived from :exc:`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
 
 
 .. exception:: OSError
 
-   This class is derived from :exc:`EnvironmentError` and is used primarily as the
-   :mod:`os` module's ``os.error`` exception. See :exc:`EnvironmentError` above for
-   a description of the possible associated values.
+   .. index:: module: errno
 
-   .. % xref for os module
+   This exception is derived from :exc:`EnvironmentError`.  It is raised when a
+   function returns a system-related error (not for illegal argument types or
+   other incidental errors).  The :attr:`errno` attribute is a numeric error
+   code from :cdata:`errno`, and the :attr:`strerror` attribute is the
+   corresponding string, as would be printed by the C function :cfunc:`perror`.
+   See the module :mod:`errno`, which contains names for the error codes defined
+   by the underlying operating system.
+
+   For exceptions that involve a file system path (such as :func:`chdir` or
+   :func:`unlink`), the exception instance will contain a third attribute,
+   :attr:`filename`, which is the file name passed to the function.
 
    .. versionadded:: 1.5.2
 
 
 .. exception:: OverflowError
 
    Raised when the result of an arithmetic operation is too large to be
    represented.  This cannot occur for long integers (which would rather raise
-   :exc:`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.
-
-   .. % XXXJH reference to long's and/or int's?
+   :exc:`MemoryError` than give up) and for most operations with plain integers,
+   which return a long integer instead.  Because of the lack of standardization
+   of floating point exception handling in C, most floating point operations
+   also aren't checked.
 
 
 .. exception:: ReferenceError
 
    This exception is raised when a weak reference proxy, created by the
    :func:`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 :mod:`weakref` module.
 
    .. versionadded:: 2.2
       Previously known as the :exc:`weakref.ReferenceError` exception.
 
 
 .. exception:: 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.)
 
 
 .. exception:: StopIteration
 
-   Raised by an iterator's :meth:`next` method to signal that there are no further
-   values. This is derived from :exc:`Exception` rather than :exc:`StandardError`,
-   since this is not considered an error in its normal application.
+   Raised by an :term:`iterator`\'s :meth:`next` method to signal that there are
+   no further values.  This is derived from :exc:`Exception` rather than
+   :exc:`StandardError`, since this is not considered an error in its normal
+   application.
 
    .. versionadded:: 2.2
 
 
 .. exception:: SyntaxError
 
    Raised when the parser encounters a syntax error.  This may occur in an
    :keyword:`import` statement, in an :keyword:`exec` statement, in a call to the
    built-in function :func:`eval` or :func:`input`, or when reading the initial
    script or standard input (also interactively).
 
-   .. % XXXJH xref to these functions?
-
    Instances of this class have attributes :attr:`filename`, :attr:`lineno`,
    :attr:`offset` and :attr:`text` for easier access to the details.  :func:`str`
    of the exception instance returns only the message.
 
 
 .. exception:: 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.
@@ -339,26 +314,24 @@
    program that triggered the error.
 
 
 .. exception:: SystemExit
 
    This exception is raised by the :func:`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 :cfunc:`exit` function); if it is ``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.
 
-   .. % XXX(hylton) xref to module sys?
-
    Instances have an attribute :attr:`code` which is set to the proposed exit
    status or error message (defaulting to ``None``). Also, this exception derives
    directly from :exc:`BaseException` and not :exc:`StandardError`, since it is not
    technically an error.
 
    A call to :func:`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 :func:`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 :func:`fork`).
 
@@ -416,24 +389,29 @@
    of :exc:`UnicodeError`.
 
    .. versionadded:: 2.3
 
 
 .. exception:: 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 :exc:`IndexError`.
 
 
+.. exception:: VMSError
+
+   Only available on VMS.  Raised when a VMS-specific error occurs.
+
+
 .. exception:: WindowsError
 
    Raised when a Windows-specific error occurs or when the error number does not
    correspond to an :cdata:`errno` value.  The :attr:`winerror` and
    :attr:`strerror` values are created from the return values of the
    :cfunc:`GetLastError` and :cfunc:`FormatMessage` functions from the Windows
    Platform API. The :attr:`errno` value maps the :attr:`winerror` value to
    corresponding ``errno.h`` values. This is a subclass of :exc:`OSError`.
 
    .. versionadded:: 2.0
 
    .. versionchanged:: 2.5
@@ -493,13 +471,13 @@
    .. versionadded:: 2.5
 
 
 .. exception:: UnicodeWarning
 
    Base class for warnings related to Unicode.
 
    .. versionadded:: 2.5
 
 The class hierarchy for built-in exceptions is:
 
 
-.. XXX includefile ../../Lib/test/exception_hierarchy.txt
+.. literalinclude:: ../../Lib/test/exception_hierarchy.txt
