diff -r ffa851df0825 -r 2fb8b9db1c86 symbian-qemu-0.9.1-12/python-2.6.1/Doc/library/exceptions.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/symbian-qemu-0.9.1-12/python-2.6.1/Doc/library/exceptions.rst	Fri Jul 31 15:01:17 2009 +0100
@@ -0,0 +1,478 @@
+.. _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.
+
+.. 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.  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.
+
+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 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.  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`.
+
+
+.. exception:: StandardError
+
+   The base class for all built-in exceptions except :exc:`StopIteration`,
+   :exc:`GeneratorExit`, :exc:`KeyboardInterrupt` and :exc:`SystemExit`.
+   :exc:`StandardError` itself is derived from :exc:`Exception`.
+
+
+.. exception:: ArithmeticError
+
+   The base class for those built-in exceptions that are raised for various
+   arithmetic errors: :exc:`OverflowError`, :exc:`ZeroDivisionError`,
+   :exc:`FloatingPointError`.
+
+
+.. exception:: LookupError
+
+   The base class for the exceptions that are raised when a key or index used on a
+   mapping or sequence is invalid: :exc:`IndexError`, :exc:`KeyError`.  This can be
+   raised directly by :func:`sys.setdefaultencoding`.
+
+
+.. exception:: EnvironmentError
+
+   The base class for exceptions that can occur outside the Python system:
+   :exc:`IOError`, :exc:`OSError`.  When exceptions of this type are created with a
+   2-tuple, the first item is available on the instance's :attr:`errno` attribute
+   (it is assumed to be an error number), and the second item is available on the
+   :attr:`strerror` attribute (it is usually the associated error message).  The
+   tuple itself is also available on the :attr:`args` attribute.
+
+   .. versionadded:: 1.5.2
+
+   When an :exc:`EnvironmentError` exception is instantiated with a 3-tuple, the
+   first two items are available as above, while the third item is available on the
+   :attr:`filename` attribute.  However, for backwards compatibility, the
+   :attr:`args` attribute contains only a 2-tuple of the first two constructor
+   arguments.
+
+   The :attr:`filename` attribute is ``None`` when this exception is created with
+   other than 3 arguments.  The :attr:`errno` and :attr:`strerror` attributes are
+   also ``None`` when the instance was created with other than 2 or 3 arguments.
+   In this last case, :attr:`args` contains the verbatim constructor arguments as a
+   tuple.
+
+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 (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:`file.read` and :meth:`file.readline` methods return an empty string
+   when they hit EOF.)
+
+
+.. 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 :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".
+
+   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.
+
+
+.. 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.)
+
+   .. XXX xref to sequences
+
+
+.. exception:: KeyError
+
+   Raised when a mapping (dictionary) key is not found in the set of existing keys.
+
+   .. 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.
+
+   .. 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
+   case a run-away program was the cause.
+
+
+.. exception:: 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.
+
+
+.. 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
+
+   .. index:: module: errno
+
+   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) 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 :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).
+
+   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.
+   Be sure to report the version of the Python interpreter (``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.
+
+
+.. 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.
+
+   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`).
+
+   The exception inherits from :exc:`BaseException` instead of :exc:`StandardError`
+   or :exc:`Exception` so that it is not accidentally caught by code that catches
+   :exc:`Exception`.  This allows the exception to properly propagate up and cause
+   the interpreter to exit.
+
+   .. versionchanged:: 2.5
+      Changed to inherit from :exc:`BaseException`.
+
+
+.. exception:: 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.
+
+
+.. exception:: 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
+   :exc:`NameError`.
+
+   .. versionadded:: 2.0
+
+
+.. exception:: UnicodeError
+
+   Raised when a Unicode-related encoding or decoding error occurs.  It is a
+   subclass of :exc:`ValueError`.
+
+   .. versionadded:: 2.0
+
+
+.. exception:: UnicodeEncodeError
+
+   Raised when a Unicode-related error occurs during encoding.  It is a subclass of
+   :exc:`UnicodeError`.
+
+   .. versionadded:: 2.3
+
+
+.. exception:: UnicodeDecodeError
+
+   Raised when a Unicode-related error occurs during decoding.  It is a subclass of
+   :exc:`UnicodeError`.
+
+   .. versionadded:: 2.3
+
+
+.. exception:: UnicodeTranslateError
+
+   Raised when a Unicode-related error occurs during translating.  It is a subclass
+   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:: 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
+      Previous versions put the :cfunc:`GetLastError` codes into :attr:`errno`.
+
+
+.. exception:: 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.
+
+The following exceptions are used as warning categories; see the :mod:`warnings`
+module for more information.
+
+
+.. exception:: Warning
+
+   Base class for warning categories.
+
+
+.. exception:: UserWarning
+
+   Base class for warnings generated by user code.
+
+
+.. exception:: DeprecationWarning
+
+   Base class for warnings about deprecated features.
+
+
+.. exception:: PendingDeprecationWarning
+
+   Base class for warnings about features which will be deprecated in the future.
+
+
+.. exception:: SyntaxWarning
+
+   Base class for warnings about dubious syntax
+
+
+.. exception:: RuntimeWarning
+
+   Base class for warnings about dubious runtime behavior.
+
+
+.. exception:: FutureWarning
+
+   Base class for warnings about constructs that will change semantically in the
+   future.
+
+
+.. exception:: ImportWarning
+
+   Base class for warnings about probable mistakes in module imports.
+
+   .. versionadded:: 2.5
+
+
+.. exception:: UnicodeWarning
+
+   Base class for warnings related to Unicode.
+
+   .. versionadded:: 2.5
+
+The class hierarchy for built-in exceptions is:
+
+
+.. literalinclude:: ../../Lib/test/exception_hierarchy.txt