Move the 3k reST doc tree in place.

1 files changed, 515 insertions, 0 deletions

diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst
new file mode 100644
index 0000000..68ac090
--- /dev/null
+++ b/Doc/c-api/exceptions.rst
@@ -0,0 +1,515 @@
+.. highlightlang:: c
+
+
+.. _exceptionhandling:
+
+******************
+Exception Handling
+******************
+
+The functions described in this chapter will let you handle and raise Python
+exceptions.  It is important to understand some of the basics of Python
+exception handling.  It works somewhat like the Unix :cdata:`errno` variable:
+there is a global indicator (per thread) of the last error that occurred.  Most
+functions don't clear this on success, but will set it to indicate the cause of
+the error on failure.  Most functions also return an error indicator, usually
+*NULL* if they are supposed to return a pointer, or ``-1`` if they return an
+integer (exception: the :cfunc:`PyArg_\*` functions return ``1`` for success and
+``0`` for failure).
+
+When a function must fail because some function it called failed, it generally
+doesn't set the error indicator; the function it called already set it.  It is
+responsible for either handling the error and clearing the exception or
+returning after cleaning up any resources it holds (such as object references or
+memory allocations); it should *not* continue normally if it is not prepared to
+handle the error.  If returning due to an error, it is important to indicate to
+the caller that an error has been set.  If the error is not handled or carefully
+propagated, additional calls into the Python/C API may not behave as intended
+and may fail in mysterious ways.
+
+The error indicator consists of three Python objects corresponding to the result
+of ``sys.exc_info()``.  API functions exist to interact with the error indicator
+in various ways.  There is a separate error indicator for each thread.
+
+.. % XXX Order of these should be more thoughtful.
+.. % Either alphabetical or some kind of structure.
+
+
+.. cfunction:: void PyErr_Print()
+
+   Print a standard traceback to ``sys.stderr`` and clear the error indicator.
+   Call this function only when the error indicator is set.  (Otherwise it will
+   cause a fatal error!)
+
+
+.. cfunction:: PyObject* PyErr_Occurred()
+
+   Test whether the error indicator is set.  If set, return the exception *type*
+   (the first argument to the last call to one of the :cfunc:`PyErr_Set\*`
+   functions or to :cfunc:`PyErr_Restore`).  If not set, return *NULL*.  You do not
+   own a reference to the return value, so you do not need to :cfunc:`Py_DECREF`
+   it.
+
+   .. note::
+
+      Do not compare the return value to a specific exception; use
+      :cfunc:`PyErr_ExceptionMatches` instead, shown below.  (The comparison could
+      easily fail since the exception may be an instance instead of a class, in the
+      case of a class exception, or it may the a subclass of the expected exception.)
+
+
+.. cfunction:: int PyErr_ExceptionMatches(PyObject *exc)
+
+   Equivalent to ``PyErr_GivenExceptionMatches(PyErr_Occurred(), exc)``.  This
+   should only be called when an exception is actually set; a memory access
+   violation will occur if no exception has been raised.
+
+
+.. cfunction:: int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)
+
+   Return true if the *given* exception matches the exception in *exc*.  If *exc*
+   is a class object, this also returns true when *given* is an instance of a
+   subclass.  If *exc* is a tuple, all exceptions in the tuple (and recursively in
+   subtuples) are searched for a match.  If *given* is *NULL*, a memory access
+   violation will occur.
+
+
+.. cfunction:: void PyErr_NormalizeException(PyObject**exc, PyObject**val, PyObject**tb)
+
+   Under certain circumstances, the values returned by :cfunc:`PyErr_Fetch` below
+   can be "unnormalized", meaning that ``*exc`` is a class object but ``*val`` is
+   not an instance of the  same class.  This function can be used to instantiate
+   the class in that case.  If the values are already normalized, nothing happens.
+   The delayed normalization is implemented to improve performance.
+
+
+.. cfunction:: void PyErr_Clear()
+
+   Clear the error indicator.  If the error indicator is not set, there is no
+   effect.
+
+
+.. cfunction:: void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
+
+   Retrieve the error indicator into three variables whose addresses are passed.
+   If the error indicator is not set, set all three variables to *NULL*.  If it is
+   set, it will be cleared and you own a reference to each object retrieved.  The
+   value and traceback object may be *NULL* even when the type object is not.
+
+   .. note::
+
+      This function is normally only used by code that needs to handle exceptions or
+      by code that needs to save and restore the error indicator temporarily.
+
+
+.. cfunction:: void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback)
+
+   Set  the error indicator from the three objects.  If the error indicator is
+   already set, it is cleared first.  If the objects are *NULL*, the error
+   indicator is cleared.  Do not pass a *NULL* type and non-*NULL* value or
+   traceback.  The exception type should be a class.  Do not pass an invalid
+   exception type or value. (Violating these rules will cause subtle problems
+   later.)  This call takes away a reference to each object: you must own a
+   reference to each object before the call and after the call you no longer own
+   these references.  (If you don't understand this, don't use this function.  I
+   warned you.)
+
+   .. note::
+
+      This function is normally only used by code that needs to save and restore the
+      error indicator temporarily; use :cfunc:`PyErr_Fetch` to save the current
+      exception state.
+
+
+.. cfunction:: void PyErr_SetString(PyObject *type, const char *message)
+
+   This is the most common way to set the error indicator.  The first argument
+   specifies the exception type; it is normally one of the standard exceptions,
+   e.g. :cdata:`PyExc_RuntimeError`.  You need not increment its reference count.
+   The second argument is an error message; it is converted to a string object.
+
+
+.. cfunction:: void PyErr_SetObject(PyObject *type, PyObject *value)
+
+   This function is similar to :cfunc:`PyErr_SetString` but lets you specify an
+   arbitrary Python object for the "value" of the exception.
+
+
+.. cfunction:: PyObject* PyErr_Format(PyObject *exception, const char *format, ...)
+
+   This function sets the error indicator and returns *NULL*. *exception* should be
+   a Python exception (class, not an instance).  *format* should be a string,
+   containing format codes, similar to :cfunc:`printf`. The ``width.precision``
+   before a format code is parsed, but the width part is ignored.
+
+   .. % This should be exactly the same as the table in PyString_FromFormat.
+   .. % One should just refer to the other.
+   .. % The descriptions for %zd and %zu are wrong, but the truth is complicated
+   .. % because not all compilers support the %z width modifier -- we fake it
+   .. % when necessary via interpolating PY_FORMAT_SIZE_T.
+   .. % %u, %lu, %zu should have "new in Python 2.5" blurbs.
+
+   +-------------------+---------------+--------------------------------+
+   | Format Characters | Type          | Comment                        |
+   +===================+===============+================================+
+   | :attr:`%%`        | *n/a*         | The literal % character.       |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%c`        | int           | A single character,            |
+   |                   |               | represented as an C int.       |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%d`        | int           | Exactly equivalent to          |
+   |                   |               | ``printf("%d")``.              |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%u`        | unsigned int  | Exactly equivalent to          |
+   |                   |               | ``printf("%u")``.              |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%ld`       | long          | Exactly equivalent to          |
+   |                   |               | ``printf("%ld")``.             |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%lu`       | unsigned long | Exactly equivalent to          |
+   |                   |               | ``printf("%lu")``.             |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%zd`       | Py_ssize_t    | Exactly equivalent to          |
+   |                   |               | ``printf("%zd")``.             |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%zu`       | size_t        | Exactly equivalent to          |
+   |                   |               | ``printf("%zu")``.             |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%i`        | int           | Exactly equivalent to          |
+   |                   |               | ``printf("%i")``.              |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%x`        | int           | Exactly equivalent to          |
+   |                   |               | ``printf("%x")``.              |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%s`        | char\*        | A null-terminated C character  |
+   |                   |               | array.                         |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%p`        | void\*        | The hex representation of a C  |
+   |                   |               | pointer. Mostly equivalent to  |
+   |                   |               | ``printf("%p")`` except that   |
+   |                   |               | it is guaranteed to start with |
+   |                   |               | the literal ``0x`` regardless  |
+   |                   |               | of what the platform's         |
+   |                   |               | ``printf`` yields.             |
+   +-------------------+---------------+--------------------------------+
+
+   An unrecognized format character causes all the rest of the format string to be
+   copied as-is to the result string, and any extra arguments discarded.
+
+
+.. cfunction:: void PyErr_SetNone(PyObject *type)
+
+   This is a shorthand for ``PyErr_SetObject(type, Py_None)``.
+
+
+.. cfunction:: int PyErr_BadArgument()
+
+   This is a shorthand for ``PyErr_SetString(PyExc_TypeError, message)``, where
+   *message* indicates that a built-in operation was invoked with an illegal
+   argument.  It is mostly for internal use.
+
+
+.. cfunction:: PyObject* PyErr_NoMemory()
+
+   This is a shorthand for ``PyErr_SetNone(PyExc_MemoryError)``; it returns *NULL*
+   so an object allocation function can write ``return PyErr_NoMemory();`` when it
+   runs out of memory.
+
+
+.. cfunction:: PyObject* PyErr_SetFromErrno(PyObject *type)
+
+   .. index:: single: strerror()
+
+   This is a convenience function to raise an exception when a C library function
+   has returned an error and set the C variable :cdata:`errno`.  It constructs a
+   tuple object whose first item is the integer :cdata:`errno` value and whose
+   second item is the corresponding error message (gotten from :cfunc:`strerror`),
+   and then calls ``PyErr_SetObject(type, object)``.  On Unix, when the
+   :cdata:`errno` value is :const:`EINTR`, indicating an interrupted system call,
+   this calls :cfunc:`PyErr_CheckSignals`, and if that set the error indicator,
+   leaves it set to that.  The function always returns *NULL*, so a wrapper
+   function around a system call can write ``return PyErr_SetFromErrno(type);``
+   when the system call returns an error.
+
+
+.. cfunction:: PyObject* PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename)
+
+   Similar to :cfunc:`PyErr_SetFromErrno`, with the additional behavior that if
+   *filename* is not *NULL*, it is passed to the constructor of *type* as a third
+   parameter.  In the case of exceptions such as :exc:`IOError` and :exc:`OSError`,
+   this is used to define the :attr:`filename` attribute of the exception instance.
+
+
+.. cfunction:: PyObject* PyErr_SetFromWindowsErr(int ierr)
+
+   This is a convenience function to raise :exc:`WindowsError`. If called with
+   *ierr* of :cdata:`0`, the error code returned by a call to :cfunc:`GetLastError`
+   is used instead.  It calls the Win32 function :cfunc:`FormatMessage` to retrieve
+   the Windows description of error code given by *ierr* or :cfunc:`GetLastError`,
+   then it constructs a tuple object whose first item is the *ierr* value and whose
+   second item is the corresponding error message (gotten from
+   :cfunc:`FormatMessage`), and then calls ``PyErr_SetObject(PyExc_WindowsError,
+   object)``. This function always returns *NULL*. Availability: Windows.
+
+
+.. cfunction:: PyObject* PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)
+
+   Similar to :cfunc:`PyErr_SetFromWindowsErr`, with an additional parameter
+   specifying the exception type to be raised. Availability: Windows.
+
+   .. versionadded:: 2.3
+
+
+.. cfunction:: PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)
+
+   Similar to :cfunc:`PyErr_SetFromWindowsErr`, with the additional behavior that
+   if *filename* is not *NULL*, it is passed to the constructor of
+   :exc:`WindowsError` as a third parameter. Availability: Windows.
+
+
+.. cfunction:: PyObject* PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, char *filename)
+
+   Similar to :cfunc:`PyErr_SetFromWindowsErrWithFilename`, with an additional
+   parameter specifying the exception type to be raised. Availability: Windows.
+
+   .. versionadded:: 2.3
+
+
+.. cfunction:: void PyErr_BadInternalCall()
+
+   This is a shorthand for ``PyErr_SetString(PyExc_TypeError, message)``, where
+   *message* indicates that an internal operation (e.g. a Python/C API function)
+   was invoked with an illegal argument.  It is mostly for internal use.
+
+
+.. cfunction:: int PyErr_WarnEx(PyObject *category, char *message, int stacklevel)
+
+   Issue a warning message.  The *category* argument is a warning category (see
+   below) or *NULL*; the *message* argument is a message string.  *stacklevel* is a
+   positive number giving a number of stack frames; the warning will be issued from
+   the  currently executing line of code in that stack frame.  A *stacklevel* of 1
+   is the function calling :cfunc:`PyErr_WarnEx`, 2 is  the function above that,
+   and so forth.
+
+   This function normally prints a warning message to *sys.stderr*; however, it is
+   also possible that the user has specified that warnings are to be turned into
+   errors, and in that case this will raise an exception.  It is also possible that
+   the function raises an exception because of a problem with the warning machinery
+   (the implementation imports the :mod:`warnings` module to do the heavy lifting).
+   The return value is ``0`` if no exception is raised, or ``-1`` if an exception
+   is raised.  (It is not possible to determine whether a warning message is
+   actually printed, nor what the reason is for the exception; this is
+   intentional.)  If an exception is raised, the caller should do its normal
+   exception handling (for example, :cfunc:`Py_DECREF` owned references and return
+   an error value).
+
+   Warning categories must be subclasses of :cdata:`Warning`; the default warning
+   category is :cdata:`RuntimeWarning`.  The standard Python warning categories are
+   available as global variables whose names are ``PyExc_`` followed by the Python
+   exception name. These have the type :ctype:`PyObject\*`; they are all class
+   objects. Their names are :cdata:`PyExc_Warning`, :cdata:`PyExc_UserWarning`,
+   :cdata:`PyExc_UnicodeWarning`, :cdata:`PyExc_DeprecationWarning`,
+   :cdata:`PyExc_SyntaxWarning`, :cdata:`PyExc_RuntimeWarning`, and
+   :cdata:`PyExc_FutureWarning`.  :cdata:`PyExc_Warning` is a subclass of
+   :cdata:`PyExc_Exception`; the other warning categories are subclasses of
+   :cdata:`PyExc_Warning`.
+
+   For information about warning control, see the documentation for the
+   :mod:`warnings` module and the :option:`-W` option in the command line
+   documentation.  There is no C API for warning control.
+
+
+.. cfunction:: int PyErr_WarnExplicit(PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry)
+
+   Issue a warning message with explicit control over all warning attributes.  This
+   is a straightforward wrapper around the Python function
+   :func:`warnings.warn_explicit`, see there for more information.  The *module*
+   and *registry* arguments may be set to *NULL* to get the default effect
+   described there.
+
+
+.. cfunction:: int PyErr_CheckSignals()
+
+   .. index::
+      module: signal
+      single: SIGINT
+      single: KeyboardInterrupt (built-in exception)
+
+   This function interacts with Python's signal handling.  It checks whether a
+   signal has been sent to the processes and if so, invokes the corresponding
+   signal handler.  If the :mod:`signal` module is supported, this can invoke a
+   signal handler written in Python.  In all cases, the default effect for
+   :const:`SIGINT` is to raise the  :exc:`KeyboardInterrupt` exception.  If an
+   exception is raised the error indicator is set and the function returns ``-1``;
+   otherwise the function returns ``0``.  The error indicator may or may not be
+   cleared if it was previously set.
+
+
+.. cfunction:: void PyErr_SetInterrupt()
+
+   .. index::
+      single: SIGINT
+      single: KeyboardInterrupt (built-in exception)
+
+   This function simulates the effect of a :const:`SIGINT` signal arriving --- the
+   next time :cfunc:`PyErr_CheckSignals` is called,  :exc:`KeyboardInterrupt` will
+   be raised.  It may be called without holding the interpreter lock.
+
+   .. % XXX This was described as obsolete, but is used in
+   .. % thread.interrupt_main() (used from IDLE), so it's still needed.
+
+
+.. cfunction:: PyObject* PyErr_NewException(char *name, PyObject *base, PyObject *dict)
+
+   This utility function creates and returns a new exception object. The *name*
+   argument must be the name of the new exception, a C string of the form
+   ``module.class``.  The *base* and *dict* arguments are normally *NULL*.  This
+   creates a class object derived from :exc:`Exception` (accessible in C as
+   :cdata:`PyExc_Exception`).
+
+   The :attr:`__module__` attribute of the new class is set to the first part (up
+   to the last dot) of the *name* argument, and the class name is set to the last
+   part (after the last dot).  The *base* argument can be used to specify alternate
+   base classes; it can either be only one class or a tuple of classes. The *dict*
+   argument can be used to specify a dictionary of class variables and methods.
+
+
+.. cfunction:: void PyErr_WriteUnraisable(PyObject *obj)
+
+   This utility function prints a warning message to ``sys.stderr`` when an
+   exception has been set but it is impossible for the interpreter to actually
+   raise the exception.  It is used, for example, when an exception occurs in an
+   :meth:`__del__` method.
+
+   The function is called with a single argument *obj* that identifies the context
+   in which the unraisable exception occurred. The repr of *obj* will be printed in
+   the warning message.
+
+
+.. _standardexceptions:
+
+Standard Exceptions
+===================
+
+All standard Python exceptions are available as global variables whose names are
+``PyExc_`` followed by the Python exception name.  These have the type
+:ctype:`PyObject\*`; they are all class objects.  For completeness, here are all
+the variables:
+
++------------------------------------+----------------------------+----------+
+| C Name                             | Python Name                | Notes    |
++====================================+============================+==========+
+| :cdata:`PyExc_BaseException`       | :exc:`BaseException`       | (1), (4) |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_Exception`           | :exc:`Exception`           | \(1)     |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_ArithmeticError`     | :exc:`ArithmeticError`     | \(1)     |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_LookupError`         | :exc:`LookupError`         | \(1)     |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_AssertionError`      | :exc:`AssertionError`      |          |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_AttributeError`      | :exc:`AttributeError`      |          |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_EOFError`            | :exc:`EOFError`            |          |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_EnvironmentError`    | :exc:`EnvironmentError`    | \(1)     |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_FloatingPointError`  | :exc:`FloatingPointError`  |          |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_IOError`             | :exc:`IOError`             |          |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_ImportError`         | :exc:`ImportError`         |          |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_IndexError`          | :exc:`IndexError`          |          |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_KeyError`            | :exc:`KeyError`            |          |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_KeyboardInterrupt`   | :exc:`KeyboardInterrupt`   |          |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_MemoryError`         | :exc:`MemoryError`         |          |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_NameError`           | :exc:`NameError`           |          |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_NotImplementedError` | :exc:`NotImplementedError` |          |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_OSError`             | :exc:`OSError`             |          |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_OverflowError`       | :exc:`OverflowError`       |          |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_ReferenceError`      | :exc:`ReferenceError`      | \(2)     |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_RuntimeError`        | :exc:`RuntimeError`        |          |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_SyntaxError`         | :exc:`SyntaxError`         |          |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_SystemError`         | :exc:`SystemError`         |          |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_SystemExit`          | :exc:`SystemExit`          |          |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_TypeError`           | :exc:`TypeError`           |          |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_ValueError`          | :exc:`ValueError`          |          |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_WindowsError`        | :exc:`WindowsError`        | \(3)     |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_ZeroDivisionError`   | :exc:`ZeroDivisionError`   |          |
++------------------------------------+----------------------------+----------+
+
+.. index::
+   single: PyExc_BaseException
+   single: PyExc_Exception
+   single: PyExc_ArithmeticError
+   single: PyExc_LookupError
+   single: PyExc_AssertionError
+   single: PyExc_AttributeError
+   single: PyExc_EOFError
+   single: PyExc_EnvironmentError
+   single: PyExc_FloatingPointError
+   single: PyExc_IOError
+   single: PyExc_ImportError
+   single: PyExc_IndexError
+   single: PyExc_KeyError
+   single: PyExc_KeyboardInterrupt
+   single: PyExc_MemoryError
+   single: PyExc_NameError
+   single: PyExc_NotImplementedError
+   single: PyExc_OSError
+   single: PyExc_OverflowError
+   single: PyExc_ReferenceError
+   single: PyExc_RuntimeError
+   single: PyExc_SyntaxError
+   single: PyExc_SystemError
+   single: PyExc_SystemExit
+   single: PyExc_TypeError
+   single: PyExc_ValueError
+   single: PyExc_WindowsError
+   single: PyExc_ZeroDivisionError
+
+Notes:
+
+(1)
+   This is a base class for other standard exceptions.
+
+(2)
+   This is the same as :exc:`weakref.ReferenceError`.
+
+(3)
+   Only defined on Windows; protect code that uses this by testing that the
+   preprocessor macro ``MS_WINDOWS`` is defined.
+
+(4)
+   .. versionadded:: 2.5
+
+
+Deprecation of String Exceptions
+================================
+
+.. index:: single: BaseException (built-in exception)
+
+All exceptions built into Python or provided in the standard library are derived
+from :exc:`BaseException`.
+
+String exceptions are still supported in the interpreter to allow existing code
+to run unmodified, but this will also change in a future release.
+