Ignore:
Timestamp:
Mar 19, 2014, 11:31:01 PM (11 years ago)
Author:
dmik
Message:

python: Merge vendor 2.7.6 to trunk.

Location:
python/trunk
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • python/trunk

  • python/trunk/Doc/c-api/exceptions.rst

    r2 r391  
    1010The functions described in this chapter will let you handle and raise Python
    1111exceptions.  It is important to understand some of the basics of Python
    12 exception handling.  It works somewhat like the Unix :cdata:`errno` variable:
     12exception handling.  It works somewhat like the Unix :c:data:`errno` variable:
    1313there is a global indicator (per thread) of the last error that occurred.  Most
    1414functions don't clear this on success, but will set it to indicate the cause of
    1515the error on failure.  Most functions also return an error indicator, usually
    1616*NULL* if they are supposed to return a pointer, or ``-1`` if they return an
    17 integer (exception: the :cfunc:`PyArg_\*` functions return ``1`` for success and
     17integer (exception: the :c:func:`PyArg_\*` functions return ``1`` for success and
    1818``0`` for failure).
    1919
    … …  
    4242
    4343
    44 .. cfunction:: void PyErr_PrintEx(int set_sys_last_vars)
     44.. c:function:: void PyErr_PrintEx(int set_sys_last_vars)
    4545
    4646   Print a standard traceback to ``sys.stderr`` and clear the error indicator.
    … …  
    5353
    5454
    55 .. cfunction:: void PyErr_Print()
     55.. c:function:: void PyErr_Print()
    5656
    5757   Alias for ``PyErr_PrintEx(1)``.
    5858
    5959
    60 .. cfunction:: PyObject* PyErr_Occurred()
     60.. c:function:: PyObject* PyErr_Occurred()
    6161
    6262   Test whether the error indicator is set.  If set, return the exception *type*
    63    (the first argument to the last call to one of the :cfunc:`PyErr_Set\*`
    64    functions or to :cfunc:`PyErr_Restore`).  If not set, return *NULL*.  You do not
    65    own a reference to the return value, so you do not need to :cfunc:`Py_DECREF`
     63   (the first argument to the last call to one of the :c:func:`PyErr_Set\*`
     64   functions or to :c:func:`PyErr_Restore`).  If not set, return *NULL*.  You do not
     65   own a reference to the return value, so you do not need to :c:func:`Py_DECREF`
    6666   it.
    6767
    … …  
    6969
    7070      Do not compare the return value to a specific exception; use
    71       :cfunc:`PyErr_ExceptionMatches` instead, shown below.  (The comparison could
     71      :c:func:`PyErr_ExceptionMatches` instead, shown below.  (The comparison could
    7272      easily fail since the exception may be an instance instead of a class, in the
    7373      case of a class exception, or it may the a subclass of the expected exception.)
    7474
    7575
    76 .. cfunction:: int PyErr_ExceptionMatches(PyObject *exc)
     76.. c:function:: int PyErr_ExceptionMatches(PyObject *exc)
    7777
    7878   Equivalent to ``PyErr_GivenExceptionMatches(PyErr_Occurred(), exc)``.  This
    … …  
    8181
    8282
    83 .. cfunction:: int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)
     83.. c:function:: int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)
    8484
    8585   Return true if the *given* exception matches the exception in *exc*.  If
    … …  
    8989
    9090
    91 .. cfunction:: void PyErr_NormalizeException(PyObject**exc, PyObject**val, PyObject**tb)
    92 
    93    Under certain circumstances, the values returned by :cfunc:`PyErr_Fetch` below
     91.. c:function:: void PyErr_NormalizeException(PyObject**exc, PyObject**val, PyObject**tb)
     92
     93   Under certain circumstances, the values returned by :c:func:`PyErr_Fetch` below
    9494   can be "unnormalized", meaning that ``*exc`` is a class object but ``*val`` is
    9595   not an instance of the  same class.  This function can be used to instantiate
    … …  
    9898
    9999
    100 .. cfunction:: void PyErr_Clear()
     100.. c:function:: void PyErr_Clear()
    101101
    102102   Clear the error indicator.  If the error indicator is not set, there is no
    … …  
    104104
    105105
    106 .. cfunction:: void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
     106.. c:function:: void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
    107107
    108108   Retrieve the error indicator into three variables whose addresses are passed.
    … …  
    117117
    118118
    119 .. cfunction:: void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback)
     119.. c:function:: void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback)
    120120
    121121   Set  the error indicator from the three objects.  If the error indicator is
    … …  
    132132
    133133      This function is normally only used by code that needs to save and restore the
    134       error indicator temporarily; use :cfunc:`PyErr_Fetch` to save the current
     134      error indicator temporarily; use :c:func:`PyErr_Fetch` to save the current
    135135      exception state.
    136136
    137137
    138 .. cfunction:: void PyErr_SetString(PyObject *type, const char *message)
     138.. c:function:: void PyErr_SetString(PyObject *type, const char *message)
    139139
    140140   This is the most common way to set the error indicator.  The first argument
    141141   specifies the exception type; it is normally one of the standard exceptions,
    142    e.g. :cdata:`PyExc_RuntimeError`.  You need not increment its reference count.
     142   e.g. :c:data:`PyExc_RuntimeError`.  You need not increment its reference count.
    143143   The second argument is an error message; it is converted to a string object.
    144144
    145145
    146 .. cfunction:: void PyErr_SetObject(PyObject *type, PyObject *value)
    147 
    148    This function is similar to :cfunc:`PyErr_SetString` but lets you specify an
     146.. c:function:: void PyErr_SetObject(PyObject *type, PyObject *value)
     147
     148   This function is similar to :c:func:`PyErr_SetString` but lets you specify an
    149149   arbitrary Python object for the "value" of the exception.
    150150
    151151
    152 .. cfunction:: PyObject* PyErr_Format(PyObject *exception, const char *format, ...)
    153 
    154    This function sets the error indicator and returns *NULL*. *exception* should be
    155    a Python exception (class, not an instance).  *format* should be a string,
    156    containing format codes, similar to :cfunc:`printf`. The ``width.precision``
    157    before a format code is parsed, but the width part is ignored.
    158 
    159    .. % This should be exactly the same as the table in PyString_FromFormat.
    160    .. % One should just refer to the other.
    161    .. % The descriptions for %zd and %zu are wrong, but the truth is complicated
    162    .. % because not all compilers support the %z width modifier -- we fake it
    163    .. % when necessary via interpolating PY_FORMAT_SIZE_T.
    164    .. % %u, %lu, %zu should have "new in Python 2.5" blurbs.
    165 
    166    +-------------------+---------------+--------------------------------+
    167    | Format Characters | Type          | Comment                        |
    168    +===================+===============+================================+
    169    | :attr:`%%`        | *n/a*         | The literal % character.       |
    170    +-------------------+---------------+--------------------------------+
    171    | :attr:`%c`        | int           | A single character,            |
    172    |                   |               | represented as an C int.       |
    173    +-------------------+---------------+--------------------------------+
    174    | :attr:`%d`        | int           | Exactly equivalent to          |
    175    |                   |               | ``printf("%d")``.              |
    176    +-------------------+---------------+--------------------------------+
    177    | :attr:`%u`        | unsigned int  | Exactly equivalent to          |
    178    |                   |               | ``printf("%u")``.              |
    179    +-------------------+---------------+--------------------------------+
    180    | :attr:`%ld`       | long          | Exactly equivalent to          |
    181    |                   |               | ``printf("%ld")``.             |
    182    +-------------------+---------------+--------------------------------+
    183    | :attr:`%lu`       | unsigned long | Exactly equivalent to          |
    184    |                   |               | ``printf("%lu")``.             |
    185    +-------------------+---------------+--------------------------------+
    186    | :attr:`%zd`       | Py_ssize_t    | Exactly equivalent to          |
    187    |                   |               | ``printf("%zd")``.             |
    188    +-------------------+---------------+--------------------------------+
    189    | :attr:`%zu`       | size_t        | Exactly equivalent to          |
    190    |                   |               | ``printf("%zu")``.             |
    191    +-------------------+---------------+--------------------------------+
    192    | :attr:`%i`        | int           | Exactly equivalent to          |
    193    |                   |               | ``printf("%i")``.              |
    194    +-------------------+---------------+--------------------------------+
    195    | :attr:`%x`        | int           | Exactly equivalent to          |
    196    |                   |               | ``printf("%x")``.              |
    197    +-------------------+---------------+--------------------------------+
    198    | :attr:`%s`        | char\*        | A null-terminated C character  |
    199    |                   |               | array.                         |
    200    +-------------------+---------------+--------------------------------+
    201    | :attr:`%p`        | void\*        | The hex representation of a C  |
    202    |                   |               | pointer. Mostly equivalent to  |
    203    |                   |               | ``printf("%p")`` except that   |
    204    |                   |               | it is guaranteed to start with |
    205    |                   |               | the literal ``0x`` regardless  |
    206    |                   |               | of what the platform's         |
    207    |                   |               | ``printf`` yields.             |
    208    +-------------------+---------------+--------------------------------+
    209 
    210    An unrecognized format character causes all the rest of the format string to be
    211    copied as-is to the result string, and any extra arguments discarded.
    212 
    213 
    214 .. cfunction:: void PyErr_SetNone(PyObject *type)
     152.. c:function:: PyObject* PyErr_Format(PyObject *exception, const char *format, ...)
     153
     154   This function sets the error indicator and returns *NULL*.  *exception*
     155   should be a Python exception class.  The *format* and subsequent
     156   parameters help format the error message; they have the same meaning and
     157   values as in :c:func:`PyString_FromFormat`.
     158
     159
     160.. c:function:: void PyErr_SetNone(PyObject *type)
    215161
    216162   This is a shorthand for ``PyErr_SetObject(type, Py_None)``.
    217163
    218164
    219 .. cfunction:: int PyErr_BadArgument()
     165.. c:function:: int PyErr_BadArgument()
    220166
    221167   This is a shorthand for ``PyErr_SetString(PyExc_TypeError, message)``, where
    … …  
    224170
    225171
    226 .. cfunction:: PyObject* PyErr_NoMemory()
     172.. c:function:: PyObject* PyErr_NoMemory()
    227173
    228174   This is a shorthand for ``PyErr_SetNone(PyExc_MemoryError)``; it returns *NULL*
    … …  
    231177
    232178
    233 .. cfunction:: PyObject* PyErr_SetFromErrno(PyObject *type)
     179.. c:function:: PyObject* PyErr_SetFromErrno(PyObject *type)
    234180
    235181   .. index:: single: strerror()
    236182
    237183   This is a convenience function to raise an exception when a C library function
    238    has returned an error and set the C variable :cdata:`errno`.  It constructs a
    239    tuple object whose first item is the integer :cdata:`errno` value and whose
    240    second item is the corresponding error message (gotten from :cfunc:`strerror`),
     184   has returned an error and set the C variable :c:data:`errno`.  It constructs a
     185   tuple object whose first item is the integer :c:data:`errno` value and whose
     186   second item is the corresponding error message (gotten from :c:func:`strerror`),
    241187   and then calls ``PyErr_SetObject(type, object)``.  On Unix, when the
    242    :cdata:`errno` value is :const:`EINTR`, indicating an interrupted system call,
    243    this calls :cfunc:`PyErr_CheckSignals`, and if that set the error indicator,
     188   :c:data:`errno` value is :const:`EINTR`, indicating an interrupted system call,
     189   this calls :c:func:`PyErr_CheckSignals`, and if that set the error indicator,
    244190   leaves it set to that.  The function always returns *NULL*, so a wrapper
    245191   function around a system call can write ``return PyErr_SetFromErrno(type);``
    … …  
    247193
    248194
    249 .. cfunction:: PyObject* PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename)
    250 
    251    Similar to :cfunc:`PyErr_SetFromErrno`, with the additional behavior that if
    252    *filename* is not *NULL*, it is passed to the constructor of *type* as a third
    253    parameter.  In the case of exceptions such as :exc:`IOError` and :exc:`OSError`,
    254    this is used to define the :attr:`filename` attribute of the exception instance.
    255 
    256 
    257 .. cfunction:: PyObject* PyErr_SetFromWindowsErr(int ierr)
     195.. c:function:: PyObject* PyErr_SetFromErrnoWithFilenameObject(PyObject *type, PyObject *filenameObject)
     196
     197   Similar to :c:func:`PyErr_SetFromErrno`, with the additional behavior that if
     198   *filenameObject* is not *NULL*, it is passed to the constructor of *type* as
     199   a third parameter.  In the case of exceptions such as :exc:`IOError` and
     200   :exc:`OSError`, this is used to define the :attr:`filename` attribute of the
     201   exception instance.
     202
     203
     204.. c:function:: PyObject* PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename)
     205
     206   Similar to :c:func:`PyErr_SetFromErrnoWithFilenameObject`, but the filename
     207   is given as a C string.
     208
     209
     210.. c:function:: PyObject* PyErr_SetFromWindowsErr(int ierr)
    258211
    259212   This is a convenience function to raise :exc:`WindowsError`. If called with
    260    *ierr* of :cdata:`0`, the error code returned by a call to :cfunc:`GetLastError`
    261    is used instead.  It calls the Win32 function :cfunc:`FormatMessage` to retrieve
    262    the Windows description of error code given by *ierr* or :cfunc:`GetLastError`,
     213   *ierr* of :c:data:`0`, the error code returned by a call to :c:func:`GetLastError`
     214   is used instead.  It calls the Win32 function :c:func:`FormatMessage` to retrieve
     215   the Windows description of error code given by *ierr* or :c:func:`GetLastError`,
    263216   then it constructs a tuple object whose first item is the *ierr* value and whose
    264217   second item is the corresponding error message (gotten from
    265    :cfunc:`FormatMessage`), and then calls ``PyErr_SetObject(PyExc_WindowsError,
     218   :c:func:`FormatMessage`), and then calls ``PyErr_SetObject(PyExc_WindowsError,
    266219   object)``. This function always returns *NULL*. Availability: Windows.
    267220
    268221
    269 .. cfunction:: PyObject* PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)
    270 
    271    Similar to :cfunc:`PyErr_SetFromWindowsErr`, with an additional parameter
     222.. c:function:: PyObject* PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)
     223
     224   Similar to :c:func:`PyErr_SetFromWindowsErr`, with an additional parameter
    272225   specifying the exception type to be raised. Availability: Windows.
    273226
    … …  
    275228
    276229
    277 .. cfunction:: PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)
    278 
    279    Similar to :cfunc:`PyErr_SetFromWindowsErr`, with the additional behavior that
    280    if *filename* is not *NULL*, it is passed to the constructor of
     230.. c:function:: PyObject* PyErr_SetFromWindowsErrWithFilenameObject(int ierr, PyObject *filenameObject)
     231
     232   Similar to :c:func:`PyErr_SetFromWindowsErr`, with the additional behavior that
     233   if *filenameObject* is not *NULL*, it is passed to the constructor of
    281234   :exc:`WindowsError` as a third parameter. Availability: Windows.
    282235
    283236
    284 .. cfunction:: PyObject* PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, char *filename)
    285 
    286    Similar to :cfunc:`PyErr_SetFromWindowsErrWithFilename`, with an additional
     237.. c:function:: PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)
     238
     239   Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, but the
     240   filename is given as a C string. Availability: Windows.
     241
     242
     243.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject *type, int ierr, PyObject *filename)
     244
     245   Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, with an
     246   additional parameter specifying the exception type to be raised.
     247   Availability: Windows.
     248
     249   .. versionadded:: 2.3
     250
     251
     252.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, const char *filename)
     253
     254   Similar to :c:func:`PyErr_SetFromWindowsErrWithFilename`, with an additional
    287255   parameter specifying the exception type to be raised. Availability: Windows.
    288256
    … …  
    290258
    291259
    292 .. cfunction:: void PyErr_BadInternalCall()
     260.. c:function:: void PyErr_BadInternalCall()
    293261
    294262   This is a shorthand for ``PyErr_SetString(PyExc_SystemError, message)``,
    … …  
    298266
    299267
    300 .. cfunction:: int PyErr_WarnEx(PyObject *category, char *message, int stacklevel)
     268.. c:function:: int PyErr_WarnEx(PyObject *category, char *message, int stacklevel)
    301269
    302270   Issue a warning message.  The *category* argument is a warning category (see
    … …  
    304272   positive number giving a number of stack frames; the warning will be issued from
    305273   the  currently executing line of code in that stack frame.  A *stacklevel* of 1
    306    is the function calling :cfunc:`PyErr_WarnEx`, 2 is  the function above that,
     274   is the function calling :c:func:`PyErr_WarnEx`, 2 is  the function above that,
    307275   and so forth.
    308276
    … …  
    316284   actually printed, nor what the reason is for the exception; this is
    317285   intentional.)  If an exception is raised, the caller should do its normal
    318    exception handling (for example, :cfunc:`Py_DECREF` owned references and return
     286   exception handling (for example, :c:func:`Py_DECREF` owned references and return
    319287   an error value).
    320288
    321    Warning categories must be subclasses of :cdata:`Warning`; the default warning
    322    category is :cdata:`RuntimeWarning`.  The standard Python warning categories are
     289   Warning categories must be subclasses of :c:data:`Warning`; the default warning
     290   category is :c:data:`RuntimeWarning`.  The standard Python warning categories are
    323291   available as global variables whose names are ``PyExc_`` followed by the Python
    324    exception name. These have the type :ctype:`PyObject\*`; they are all class
    325    objects. Their names are :cdata:`PyExc_Warning`, :cdata:`PyExc_UserWarning`,
    326    :cdata:`PyExc_UnicodeWarning`, :cdata:`PyExc_DeprecationWarning`,
    327    :cdata:`PyExc_SyntaxWarning`, :cdata:`PyExc_RuntimeWarning`, and
    328    :cdata:`PyExc_FutureWarning`.  :cdata:`PyExc_Warning` is a subclass of
    329    :cdata:`PyExc_Exception`; the other warning categories are subclasses of
    330    :cdata:`PyExc_Warning`.
     292   exception name. These have the type :c:type:`PyObject\*`; they are all class
     293   objects. Their names are :c:data:`PyExc_Warning`, :c:data:`PyExc_UserWarning`,
     294   :c:data:`PyExc_UnicodeWarning`, :c:data:`PyExc_DeprecationWarning`,
     295   :c:data:`PyExc_SyntaxWarning`, :c:data:`PyExc_RuntimeWarning`, and
     296   :c:data:`PyExc_FutureWarning`.  :c:data:`PyExc_Warning` is a subclass of
     297   :c:data:`PyExc_Exception`; the other warning categories are subclasses of
     298   :c:data:`PyExc_Warning`.
    331299
    332300   For information about warning control, see the documentation for the
    … …  
    335303
    336304
    337 .. cfunction:: int PyErr_Warn(PyObject *category, char *message)
     305.. c:function:: int PyErr_Warn(PyObject *category, char *message)
    338306
    339307   Issue a warning message.  The *category* argument is a warning category (see
    340308   below) or *NULL*; the *message* argument is a message string.  The warning will
    341    appear to be issued from the function calling :cfunc:`PyErr_Warn`, equivalent to
    342    calling :cfunc:`PyErr_WarnEx` with a *stacklevel* of 1.
    343 
    344    Deprecated; use :cfunc:`PyErr_WarnEx` instead.
    345 
    346 
    347 .. cfunction:: int PyErr_WarnExplicit(PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry)
     309   appear to be issued from the function calling :c:func:`PyErr_Warn`, equivalent to
     310   calling :c:func:`PyErr_WarnEx` with a *stacklevel* of 1.
     311
     312   Deprecated; use :c:func:`PyErr_WarnEx` instead.
     313
     314
     315.. c:function:: int PyErr_WarnExplicit(PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry)
    348316
    349317   Issue a warning message with explicit control over all warning attributes.  This
    … …  
    354322
    355323
    356 .. cfunction:: int PyErr_WarnPy3k(char *message, int stacklevel)
     324.. c:function:: int PyErr_WarnPy3k(char *message, int stacklevel)
    357325
    358326   Issue a :exc:`DeprecationWarning` with the given *message* and *stacklevel*
    359    if the :cdata:`Py_Py3kWarningFlag` flag is enabled.
     327   if the :c:data:`Py_Py3kWarningFlag` flag is enabled.
    360328
    361329   .. versionadded:: 2.6
    362330
    363331
    364 .. cfunction:: int PyErr_CheckSignals()
     332.. c:function:: int PyErr_CheckSignals()
    365333
    366334   .. index::
    … …  
    379347
    380348
    381 .. cfunction:: void PyErr_SetInterrupt()
     349.. c:function:: void PyErr_SetInterrupt()
    382350
    383351   .. index::
    … …  
    386354
    387355   This function simulates the effect of a :const:`SIGINT` signal arriving --- the
    388    next time :cfunc:`PyErr_CheckSignals` is called,  :exc:`KeyboardInterrupt` will
     356   next time :c:func:`PyErr_CheckSignals` is called,  :exc:`KeyboardInterrupt` will
    389357   be raised.  It may be called without holding the interpreter lock.
    390358
    … …  
    393361
    394362
    395 .. cfunction:: int PySignal_SetWakeupFd(int fd)
     363.. c:function:: int PySignal_SetWakeupFd(int fd)
    396364
    397365   This utility function specifies a file descriptor to which a ``'\0'`` byte will
    … …  
    402370   only be called from the main thread.
    403371
    404 
    405 .. cfunction:: PyObject* PyErr_NewException(char *name, PyObject *base, PyObject *dict)
    406 
    407    This utility function creates and returns a new exception object. The *name*
     372   .. versionadded:: 2.6
     373
     374
     375.. c:function:: PyObject* PyErr_NewException(char *name, PyObject *base, PyObject *dict)
     376
     377   This utility function creates and returns a new exception class. The *name*
    408378   argument must be the name of the new exception, a C string of the form
    409    ``module.class``.  The *base* and *dict* arguments are normally *NULL*.  This
    410    creates a class object derived from :exc:`Exception` (accessible in C as
    411    :cdata:`PyExc_Exception`).
     379   ``module.classname``.  The *base* and *dict* arguments are normally *NULL*.
     380   This creates a class object derived from :exc:`Exception` (accessible in C as
     381   :c:data:`PyExc_Exception`).
    412382
    413383   The :attr:`__module__` attribute of the new class is set to the first part (up
    … …  
    418388
    419389
    420 .. cfunction:: void PyErr_WriteUnraisable(PyObject *obj)
     390.. c:function:: PyObject* PyErr_NewExceptionWithDoc(char *name, char *doc, PyObject *base, PyObject *dict)
     391
     392   Same as :c:func:`PyErr_NewException`, except that the new exception class can
     393   easily be given a docstring: If *doc* is non-*NULL*, it will be used as the
     394   docstring for the exception class.
     395
     396   .. versionadded:: 2.7
     397
     398
     399.. c:function:: void PyErr_WriteUnraisable(PyObject *obj)
    421400
    422401   This utility function prints a warning message to ``sys.stderr`` when an
    … …  
    430409
    431410
     411.. _unicodeexceptions:
     412
     413Unicode Exception Objects
     414=========================
     415
     416The following functions are used to create and modify Unicode exceptions from C.
     417
     418.. c:function:: PyObject* PyUnicodeDecodeError_Create(const char *encoding, const char *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
     419
     420   Create a :class:`UnicodeDecodeError` object with the attributes *encoding*,
     421   *object*, *length*, *start*, *end* and *reason*.
     422
     423.. c:function:: PyObject* PyUnicodeEncodeError_Create(const char *encoding, const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
     424
     425   Create a :class:`UnicodeEncodeError` object with the attributes *encoding*,
     426   *object*, *length*, *start*, *end* and *reason*.
     427
     428.. c:function:: PyObject* PyUnicodeTranslateError_Create(const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
     429
     430   Create a :class:`UnicodeTranslateError` object with the attributes *object*,
     431   *length*, *start*, *end* and *reason*.
     432
     433.. c:function:: PyObject* PyUnicodeDecodeError_GetEncoding(PyObject *exc)
     434               PyObject* PyUnicodeEncodeError_GetEncoding(PyObject *exc)
     435
     436   Return the *encoding* attribute of the given exception object.
     437
     438.. c:function:: PyObject* PyUnicodeDecodeError_GetObject(PyObject *exc)
     439               PyObject* PyUnicodeEncodeError_GetObject(PyObject *exc)
     440               PyObject* PyUnicodeTranslateError_GetObject(PyObject *exc)
     441
     442   Return the *object* attribute of the given exception object.
     443
     444.. c:function:: int PyUnicodeDecodeError_GetStart(PyObject *exc, Py_ssize_t *start)
     445               int PyUnicodeEncodeError_GetStart(PyObject *exc, Py_ssize_t *start)
     446               int PyUnicodeTranslateError_GetStart(PyObject *exc, Py_ssize_t *start)
     447
     448   Get the *start* attribute of the given exception object and place it into
     449   *\*start*.  *start* must not be *NULL*.  Return ``0`` on success, ``-1`` on
     450   failure.
     451
     452.. c:function:: int PyUnicodeDecodeError_SetStart(PyObject *exc, Py_ssize_t start)
     453               int PyUnicodeEncodeError_SetStart(PyObject *exc, Py_ssize_t start)
     454               int PyUnicodeTranslateError_SetStart(PyObject *exc, Py_ssize_t start)
     455
     456   Set the *start* attribute of the given exception object to *start*.  Return
     457   ``0`` on success, ``-1`` on failure.
     458
     459.. c:function:: int PyUnicodeDecodeError_GetEnd(PyObject *exc, Py_ssize_t *end)
     460               int PyUnicodeEncodeError_GetEnd(PyObject *exc, Py_ssize_t *end)
     461               int PyUnicodeTranslateError_GetEnd(PyObject *exc, Py_ssize_t *end)
     462
     463   Get the *end* attribute of the given exception object and place it into
     464   *\*end*.  *end* must not be *NULL*.  Return ``0`` on success, ``-1`` on
     465   failure.
     466
     467.. c:function:: int PyUnicodeDecodeError_SetEnd(PyObject *exc, Py_ssize_t end)
     468               int PyUnicodeEncodeError_SetEnd(PyObject *exc, Py_ssize_t end)
     469               int PyUnicodeTranslateError_SetEnd(PyObject *exc, Py_ssize_t end)
     470
     471   Set the *end* attribute of the given exception object to *end*.  Return ``0``
     472   on success, ``-1`` on failure.
     473
     474.. c:function:: PyObject* PyUnicodeDecodeError_GetReason(PyObject *exc)
     475               PyObject* PyUnicodeEncodeError_GetReason(PyObject *exc)
     476               PyObject* PyUnicodeTranslateError_GetReason(PyObject *exc)
     477
     478   Return the *reason* attribute of the given exception object.
     479
     480.. c:function:: int PyUnicodeDecodeError_SetReason(PyObject *exc, const char *reason)
     481               int PyUnicodeEncodeError_SetReason(PyObject *exc, const char *reason)
     482               int PyUnicodeTranslateError_SetReason(PyObject *exc, const char *reason)
     483
     484   Set the *reason* attribute of the given exception object to *reason*.  Return
     485   ``0`` on success, ``-1`` on failure.
     486
     487
     488Recursion Control
     489=================
     490
     491These two functions provide a way to perform safe recursive calls at the C
     492level, both in the core and in extension modules.  They are needed if the
     493recursive code does not necessarily invoke Python code (which tracks its
     494recursion depth automatically).
     495
     496.. c:function:: int Py_EnterRecursiveCall(char *where)
     497
     498   Marks a point where a recursive C-level call is about to be performed.
     499
     500   If :const:`USE_STACKCHECK` is defined, this function checks if the OS
     501   stack overflowed using :c:func:`PyOS_CheckStack`.  In this is the case, it
     502   sets a :exc:`MemoryError` and returns a nonzero value.
     503
     504   The function then checks if the recursion limit is reached.  If this is the
     505   case, a :exc:`RuntimeError` is set and a nonzero value is returned.
     506   Otherwise, zero is returned.
     507
     508   *where* should be a string such as ``" in instance check"`` to be
     509   concatenated to the :exc:`RuntimeError` message caused by the recursion depth
     510   limit.
     511
     512.. c:function:: void Py_LeaveRecursiveCall()
     513
     514   Ends a :c:func:`Py_EnterRecursiveCall`.  Must be called once for each
     515   *successful* invocation of :c:func:`Py_EnterRecursiveCall`.
     516
     517
    432518.. _standardexceptions:
    433519
    … …  
    437523All standard Python exceptions are available as global variables whose names are
    438524``PyExc_`` followed by the Python exception name.  These have the type
    439 :ctype:`PyObject\*`; they are all class objects.  For completeness, here are all
     525:c:type:`PyObject\*`; they are all class objects.  For completeness, here are all
    440526the variables:
    441527
    442 +------------------------------------+----------------------------+----------+
    443 | C Name                             | Python Name                | Notes    |
    444 +====================================+============================+==========+
    445 | :cdata:`PyExc_BaseException`       | :exc:`BaseException`       | (1), (4) |
    446 +------------------------------------+----------------------------+----------+
    447 | :cdata:`PyExc_Exception`           | :exc:`Exception`           | \(1)     |
    448 +------------------------------------+----------------------------+----------+
    449 | :cdata:`PyExc_StandardError`       | :exc:`StandardError`       | \(1)     |
    450 +------------------------------------+----------------------------+----------+
    451 | :cdata:`PyExc_ArithmeticError`     | :exc:`ArithmeticError`     | \(1)     |
    452 +------------------------------------+----------------------------+----------+
    453 | :cdata:`PyExc_LookupError`         | :exc:`LookupError`         | \(1)     |
    454 +------------------------------------+----------------------------+----------+
    455 | :cdata:`PyExc_AssertionError`      | :exc:`AssertionError`      |          |
    456 +------------------------------------+----------------------------+----------+
    457 | :cdata:`PyExc_AttributeError`      | :exc:`AttributeError`      |          |
    458 +------------------------------------+----------------------------+----------+
    459 | :cdata:`PyExc_EOFError`            | :exc:`EOFError`            |          |
    460 +------------------------------------+----------------------------+----------+
    461 | :cdata:`PyExc_EnvironmentError`    | :exc:`EnvironmentError`    | \(1)     |
    462 +------------------------------------+----------------------------+----------+
    463 | :cdata:`PyExc_FloatingPointError`  | :exc:`FloatingPointError`  |          |
    464 +------------------------------------+----------------------------+----------+
    465 | :cdata:`PyExc_IOError`             | :exc:`IOError`             |          |
    466 +------------------------------------+----------------------------+----------+
    467 | :cdata:`PyExc_ImportError`         | :exc:`ImportError`         |          |
    468 +------------------------------------+----------------------------+----------+
    469 | :cdata:`PyExc_IndexError`          | :exc:`IndexError`          |          |
    470 +------------------------------------+----------------------------+----------+
    471 | :cdata:`PyExc_KeyError`            | :exc:`KeyError`            |          |
    472 +------------------------------------+----------------------------+----------+
    473 | :cdata:`PyExc_KeyboardInterrupt`   | :exc:`KeyboardInterrupt`   |          |
    474 +------------------------------------+----------------------------+----------+
    475 | :cdata:`PyExc_MemoryError`         | :exc:`MemoryError`         |          |
    476 +------------------------------------+----------------------------+----------+
    477 | :cdata:`PyExc_NameError`           | :exc:`NameError`           |          |
    478 +------------------------------------+----------------------------+----------+
    479 | :cdata:`PyExc_NotImplementedError` | :exc:`NotImplementedError` |          |
    480 +------------------------------------+----------------------------+----------+
    481 | :cdata:`PyExc_OSError`             | :exc:`OSError`             |          |
    482 +------------------------------------+----------------------------+----------+
    483 | :cdata:`PyExc_OverflowError`       | :exc:`OverflowError`       |          |
    484 +------------------------------------+----------------------------+----------+
    485 | :cdata:`PyExc_ReferenceError`      | :exc:`ReferenceError`      | \(2)     |
    486 +------------------------------------+----------------------------+----------+
    487 | :cdata:`PyExc_RuntimeError`        | :exc:`RuntimeError`        |          |
    488 +------------------------------------+----------------------------+----------+
    489 | :cdata:`PyExc_SyntaxError`         | :exc:`SyntaxError`         |          |
    490 +------------------------------------+----------------------------+----------+
    491 | :cdata:`PyExc_SystemError`         | :exc:`SystemError`         |          |
    492 +------------------------------------+----------------------------+----------+
    493 | :cdata:`PyExc_SystemExit`          | :exc:`SystemExit`          |          |
    494 +------------------------------------+----------------------------+----------+
    495 | :cdata:`PyExc_TypeError`           | :exc:`TypeError`           |          |
    496 +------------------------------------+----------------------------+----------+
    497 | :cdata:`PyExc_ValueError`          | :exc:`ValueError`          |          |
    498 +------------------------------------+----------------------------+----------+
    499 | :cdata:`PyExc_WindowsError`        | :exc:`WindowsError`        | \(3)     |
    500 +------------------------------------+----------------------------+----------+
    501 | :cdata:`PyExc_ZeroDivisionError`   | :exc:`ZeroDivisionError`   |          |
    502 +------------------------------------+----------------------------+----------+
     528+-------------------------------------+----------------------------+----------+
     529| C Name                              | Python Name                | Notes    |
     530+=====================================+============================+==========+
     531| :c:data:`PyExc_BaseException`       | :exc:`BaseException`       | (1), (4) |
     532+-------------------------------------+----------------------------+----------+
     533| :c:data:`PyExc_Exception`           | :exc:`Exception`           | \(1)     |
     534+-------------------------------------+----------------------------+----------+
     535| :c:data:`PyExc_StandardError`       | :exc:`StandardError`       | \(1)     |
     536+-------------------------------------+----------------------------+----------+
     537| :c:data:`PyExc_ArithmeticError`     | :exc:`ArithmeticError`     | \(1)     |
     538+-------------------------------------+----------------------------+----------+
     539| :c:data:`PyExc_LookupError`         | :exc:`LookupError`         | \(1)     |
     540+-------------------------------------+----------------------------+----------+
     541| :c:data:`PyExc_AssertionError`      | :exc:`AssertionError`      |          |
     542+-------------------------------------+----------------------------+----------+
     543| :c:data:`PyExc_AttributeError`      | :exc:`AttributeError`      |          |
     544+-------------------------------------+----------------------------+----------+
     545| :c:data:`PyExc_EOFError`            | :exc:`EOFError`            |          |
     546+-------------------------------------+----------------------------+----------+
     547| :c:data:`PyExc_EnvironmentError`    | :exc:`EnvironmentError`    | \(1)     |
     548+-------------------------------------+----------------------------+----------+
     549| :c:data:`PyExc_FloatingPointError`  | :exc:`FloatingPointError`  |          |
     550+-------------------------------------+----------------------------+----------+
     551| :c:data:`PyExc_IOError`             | :exc:`IOError`             |          |
     552+-------------------------------------+----------------------------+----------+
     553| :c:data:`PyExc_ImportError`         | :exc:`ImportError`         |          |
     554+-------------------------------------+----------------------------+----------+
     555| :c:data:`PyExc_IndexError`          | :exc:`IndexError`          |          |
     556+-------------------------------------+----------------------------+----------+
     557| :c:data:`PyExc_KeyError`            | :exc:`KeyError`            |          |
     558+-------------------------------------+----------------------------+----------+
     559| :c:data:`PyExc_KeyboardInterrupt`   | :exc:`KeyboardInterrupt`   |          |
     560+-------------------------------------+----------------------------+----------+
     561| :c:data:`PyExc_MemoryError`         | :exc:`MemoryError`         |          |
     562+-------------------------------------+----------------------------+----------+
     563| :c:data:`PyExc_NameError`           | :exc:`NameError`           |          |
     564+-------------------------------------+----------------------------+----------+
     565| :c:data:`PyExc_NotImplementedError` | :exc:`NotImplementedError` |          |
     566+-------------------------------------+----------------------------+----------+
     567| :c:data:`PyExc_OSError`             | :exc:`OSError`             |          |
     568+-------------------------------------+----------------------------+----------+
     569| :c:data:`PyExc_OverflowError`       | :exc:`OverflowError`       |          |
     570+-------------------------------------+----------------------------+----------+
     571| :c:data:`PyExc_ReferenceError`      | :exc:`ReferenceError`      | \(2)     |
     572+-------------------------------------+----------------------------+----------+
     573| :c:data:`PyExc_RuntimeError`        | :exc:`RuntimeError`        |          |
     574+-------------------------------------+----------------------------+----------+
     575| :c:data:`PyExc_SyntaxError`         | :exc:`SyntaxError`         |          |
     576+-------------------------------------+----------------------------+----------+
     577| :c:data:`PyExc_SystemError`         | :exc:`SystemError`         |          |
     578+-------------------------------------+----------------------------+----------+
     579| :c:data:`PyExc_SystemExit`          | :exc:`SystemExit`          |          |
     580+-------------------------------------+----------------------------+----------+
     581| :c:data:`PyExc_TypeError`           | :exc:`TypeError`           |          |
     582+-------------------------------------+----------------------------+----------+
     583| :c:data:`PyExc_ValueError`          | :exc:`ValueError`          |          |
     584+-------------------------------------+----------------------------+----------+
     585| :c:data:`PyExc_WindowsError`        | :exc:`WindowsError`        | \(3)     |
     586+-------------------------------------+----------------------------+----------+
     587| :c:data:`PyExc_ZeroDivisionError`   | :exc:`ZeroDivisionError`   |          |
     588+-------------------------------------+----------------------------+----------+
    503589
    504590.. index::
    … …  
    549635
    550636
    551 Deprecation of String Exceptions
    552 ================================
    553 
    554 .. index:: single: BaseException (built-in exception)
    555 
    556 All exceptions built into Python or provided in the standard library are derived
    557 from :exc:`BaseException`.
    558 
    559 String exceptions are still supported in the interpreter to allow existing code
    560 to run unmodified, but this will also change in a future release.
    561 
     637String Exceptions
     638=================
     639
     640.. versionchanged:: 2.6
     641   All exceptions to be raised or caught must be derived from :exc:`BaseException`.
     642   Trying to raise a string exception now raises :exc:`TypeError`.
     643
Note: See TracChangeset for help on using the changeset viewer.