2007-08-15 11:28:22 -03:00
|
|
|
.. 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
|
2014-09-30 16:56:10 -03:00
|
|
|
exception handling. It works somewhat like the POSIX :c:data:`errno` variable:
|
2007-08-15 11:28:22 -03:00
|
|
|
there is a global indicator (per thread) of the last error that occurred. Most
|
2014-09-30 16:56:10 -03:00
|
|
|
C API functions don't clear this on success, but will set it to indicate the
|
|
|
|
cause of the error on failure. Most C API 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 :c:func:`PyArg_\*` functions
|
|
|
|
return ``1`` for success and ``0`` for failure).
|
|
|
|
|
|
|
|
Concretely, the error indicator consists of three object pointers: the
|
|
|
|
exception's type, the exception's value, and the traceback object. Any
|
|
|
|
of those pointers can be NULL if non-set (although some combinations are
|
|
|
|
forbidden, for example you can't have a non-NULL traceback if the exception
|
|
|
|
type is NULL).
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
2014-09-30 16:56:10 -03:00
|
|
|
.. note::
|
|
|
|
The error indicator is **not** the result of :func:`sys.exc_info()`.
|
|
|
|
The former corresponds to an exception that is not yet caught (and is
|
|
|
|
therefore still propagating), while the latter returns an exception after
|
|
|
|
it is caught (and has therefore stopped propagating).
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2014-09-30 16:56:10 -03:00
|
|
|
|
|
|
|
Printing and clearing
|
|
|
|
=====================
|
|
|
|
|
|
|
|
|
|
|
|
.. c:function:: void PyErr_Clear()
|
|
|
|
|
|
|
|
Clear the error indicator. If the error indicator is not set, there is no
|
|
|
|
effect.
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
.. c:function:: void PyErr_PrintEx(int set_sys_last_vars)
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
Print a standard traceback to ``sys.stderr`` and clear the error indicator.
|
2019-02-27 19:45:28 -04:00
|
|
|
**Unless** the error is a ``SystemExit``. In that case the no traceback
|
|
|
|
is printed and Python process will exit with the error code specified by
|
|
|
|
the ``SystemExit`` instance.
|
|
|
|
|
|
|
|
Call this function **only** when the error indicator is set. Otherwise it
|
|
|
|
will cause a fatal error!
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2009-02-05 06:56:37 -04:00
|
|
|
If *set_sys_last_vars* is nonzero, the variables :data:`sys.last_type`,
|
|
|
|
:data:`sys.last_value` and :data:`sys.last_traceback` will be set to the
|
|
|
|
type, value and traceback of the printed exception, respectively.
|
|
|
|
|
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
.. c:function:: void PyErr_Print()
|
2009-02-05 06:56:37 -04:00
|
|
|
|
|
|
|
Alias for ``PyErr_PrintEx(1)``.
|
|
|
|
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2014-09-30 16:56:10 -03:00
|
|
|
.. c:function:: void PyErr_WriteUnraisable(PyObject *obj)
|
2012-04-19 09:33:43 -03:00
|
|
|
|
2014-09-30 16:56:10 -03:00
|
|
|
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.
|
2012-04-19 09:33:43 -03:00
|
|
|
|
2014-09-30 16:56:10 -03:00
|
|
|
The function is called with a single argument *obj* that identifies the context
|
2016-02-27 23:16:11 -04:00
|
|
|
in which the unraisable exception occurred. If possible,
|
|
|
|
the repr of *obj* will be printed in the warning message.
|
2012-04-19 09:33:43 -03:00
|
|
|
|
|
|
|
|
2014-09-30 16:56:10 -03:00
|
|
|
Raising exceptions
|
|
|
|
==================
|
2012-04-19 09:33:43 -03:00
|
|
|
|
2014-09-30 16:56:10 -03:00
|
|
|
These functions help you set the current thread's error indicator.
|
|
|
|
For convenience, some of these functions will always return a
|
|
|
|
NULL pointer for use in a ``return`` statement.
|
2012-04-19 09:33:43 -03:00
|
|
|
|
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
.. c:function:: void PyErr_SetString(PyObject *type, const char *message)
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
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,
|
2010-10-06 07:11:56 -03:00
|
|
|
e.g. :c:data:`PyExc_RuntimeError`. You need not increment its reference count.
|
2010-10-09 07:12:11 -03:00
|
|
|
The second argument is an error message; it is decoded from ``'utf-8``'.
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
.. c:function:: void PyErr_SetObject(PyObject *type, PyObject *value)
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
This function is similar to :c:func:`PyErr_SetString` but lets you specify an
|
2007-08-15 11:28:22 -03:00
|
|
|
arbitrary Python object for the "value" of the exception.
|
|
|
|
|
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
.. c:function:: PyObject* PyErr_Format(PyObject *exception, const char *format, ...)
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2010-11-27 16:40:43 -04:00
|
|
|
This function sets the error indicator and returns *NULL*. *exception*
|
|
|
|
should be a Python exception class. The *format* and subsequent
|
|
|
|
parameters help format the error message; they have the same meaning and
|
2010-12-28 07:02:46 -04:00
|
|
|
values as in :c:func:`PyUnicode_FromFormat`. *format* is an ASCII-encoded
|
2010-12-26 21:49:26 -04:00
|
|
|
string.
|
2009-11-16 13:00:11 -04:00
|
|
|
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2014-09-30 16:16:27 -03:00
|
|
|
.. c:function:: PyObject* PyErr_FormatV(PyObject *exception, const char *format, va_list vargs)
|
|
|
|
|
2014-10-30 18:25:41 -03:00
|
|
|
Same as :c:func:`PyErr_Format`, but taking a :c:type:`va_list` argument rather
|
2014-09-30 16:16:27 -03:00
|
|
|
than a variable number of arguments.
|
|
|
|
|
|
|
|
.. versionadded:: 3.5
|
|
|
|
|
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
.. c:function:: void PyErr_SetNone(PyObject *type)
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
This is a shorthand for ``PyErr_SetObject(type, Py_None)``.
|
|
|
|
|
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
.. c:function:: int PyErr_BadArgument()
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
.. c:function:: PyObject* PyErr_NoMemory()
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
.. c:function:: PyObject* PyErr_SetFromErrno(PyObject *type)
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
.. index:: single: strerror()
|
|
|
|
|
|
|
|
This is a convenience function to raise an exception when a C library function
|
2010-10-06 07:11:56 -03:00
|
|
|
has returned an error and set the C variable :c:data:`errno`. It constructs a
|
|
|
|
tuple object whose first item is the integer :c:data:`errno` value and whose
|
|
|
|
second item is the corresponding error message (gotten from :c:func:`strerror`),
|
2007-08-15 11:28:22 -03:00
|
|
|
and then calls ``PyErr_SetObject(type, object)``. On Unix, when the
|
2010-10-06 07:11:56 -03:00
|
|
|
:c:data:`errno` value is :const:`EINTR`, indicating an interrupted system call,
|
|
|
|
this calls :c:func:`PyErr_CheckSignals`, and if that set the error indicator,
|
2007-08-15 11:28:22 -03:00
|
|
|
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.
|
|
|
|
|
|
|
|
|
2013-04-14 06:12:16 -03:00
|
|
|
.. c:function:: PyObject* PyErr_SetFromErrnoWithFilenameObject(PyObject *type, PyObject *filenameObject)
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
Similar to :c:func:`PyErr_SetFromErrno`, with the additional behavior that if
|
2013-04-14 06:12:16 -03:00
|
|
|
*filenameObject* is not *NULL*, it is passed to the constructor of *type* as
|
2014-03-31 19:13:30 -03:00
|
|
|
a third parameter. In the case of :exc:`OSError` exception,
|
|
|
|
this is used to define the :attr:`filename` attribute of the
|
2013-04-14 06:12:16 -03:00
|
|
|
exception instance.
|
|
|
|
|
|
|
|
|
2014-02-10 02:05:19 -04:00
|
|
|
.. c:function:: PyObject* PyErr_SetFromErrnoWithFilenameObjects(PyObject *type, PyObject *filenameObject, PyObject *filenameObject2)
|
|
|
|
|
|
|
|
Similar to :c:func:`PyErr_SetFromErrnoWithFilenameObject`, but takes a second
|
|
|
|
filename object, for raising errors when a function that takes two filenames
|
|
|
|
fails.
|
|
|
|
|
2014-03-24 05:06:18 -03:00
|
|
|
.. versionadded:: 3.4
|
2014-02-10 02:05:19 -04:00
|
|
|
|
|
|
|
|
2013-04-14 06:12:16 -03:00
|
|
|
.. c:function:: PyObject* PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename)
|
|
|
|
|
|
|
|
Similar to :c:func:`PyErr_SetFromErrnoWithFilenameObject`, but the filename
|
|
|
|
is given as a C string. *filename* is decoded from the filesystem encoding
|
2013-08-26 17:28:21 -03:00
|
|
|
(:func:`os.fsdecode`).
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
.. c:function:: PyObject* PyErr_SetFromWindowsErr(int ierr)
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
This is a convenience function to raise :exc:`WindowsError`. If called with
|
2010-10-06 07:11:56 -03:00
|
|
|
*ierr* of :c:data:`0`, the error code returned by a call to :c:func:`GetLastError`
|
|
|
|
is used instead. It calls the Win32 function :c:func:`FormatMessage` to retrieve
|
|
|
|
the Windows description of error code given by *ierr* or :c:func:`GetLastError`,
|
2007-08-15 11:28:22 -03:00
|
|
|
then it constructs a tuple object whose first item is the *ierr* value and whose
|
|
|
|
second item is the corresponding error message (gotten from
|
2010-10-06 07:11:56 -03:00
|
|
|
:c:func:`FormatMessage`), and then calls ``PyErr_SetObject(PyExc_WindowsError,
|
2018-10-15 17:52:26 -03:00
|
|
|
object)``. This function always returns *NULL*.
|
|
|
|
|
|
|
|
.. availability:: Windows.
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
.. c:function:: PyObject* PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
Similar to :c:func:`PyErr_SetFromWindowsErr`, with an additional parameter
|
2018-10-15 17:52:26 -03:00
|
|
|
specifying the exception type to be raised.
|
|
|
|
|
|
|
|
.. availability:: Windows.
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
.. c:function:: PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2013-04-14 06:12:16 -03:00
|
|
|
Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, but the
|
|
|
|
filename is given as a C string. *filename* is decoded from the filesystem
|
2018-10-15 17:52:26 -03:00
|
|
|
encoding (:func:`os.fsdecode`).
|
|
|
|
|
|
|
|
.. availability:: Windows.
|
2013-04-14 06:12:16 -03:00
|
|
|
|
|
|
|
|
|
|
|
.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject *type, int ierr, PyObject *filename)
|
|
|
|
|
|
|
|
Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, with an
|
|
|
|
additional parameter specifying the exception type to be raised.
|
2018-10-15 17:52:26 -03:00
|
|
|
|
|
|
|
.. availability:: Windows.
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
|
2014-02-10 02:05:19 -04:00
|
|
|
.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilenameObjects(PyObject *type, int ierr, PyObject *filename, PyObject *filename2)
|
|
|
|
|
|
|
|
Similar to :c:func:`PyErr_SetExcFromWindowsErrWithFilenameObject`,
|
|
|
|
but accepts a second filename object.
|
2018-10-15 17:52:26 -03:00
|
|
|
|
|
|
|
.. availability:: Windows.
|
2014-02-10 02:05:19 -04:00
|
|
|
|
2014-03-24 05:06:18 -03:00
|
|
|
.. versionadded:: 3.4
|
2014-02-10 02:05:19 -04:00
|
|
|
|
|
|
|
|
2013-04-14 06:12:16 -03:00
|
|
|
.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, const char *filename)
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
Similar to :c:func:`PyErr_SetFromWindowsErrWithFilename`, with an additional
|
2018-10-15 17:52:26 -03:00
|
|
|
parameter specifying the exception type to be raised.
|
|
|
|
|
|
|
|
.. availability:: Windows.
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2012-04-24 14:16:24 -03:00
|
|
|
|
2012-04-17 18:57:09 -03:00
|
|
|
.. c:function:: PyObject* PyErr_SetImportError(PyObject *msg, PyObject *name, PyObject *path)
|
2012-04-16 17:14:36 -03:00
|
|
|
|
|
|
|
This is a convenience function to raise :exc:`ImportError`. *msg* will be
|
2012-04-17 18:57:09 -03:00
|
|
|
set as the exception's message string. *name* and *path*, both of which can
|
|
|
|
be ``NULL``, will be set as the :exc:`ImportError`'s respective ``name``
|
|
|
|
and ``path`` attributes.
|
2012-04-16 17:14:36 -03:00
|
|
|
|
2012-04-16 20:14:09 -03:00
|
|
|
.. versionadded:: 3.3
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2012-04-24 14:16:24 -03:00
|
|
|
|
2013-08-26 17:28:21 -03:00
|
|
|
.. c:function:: void PyErr_SyntaxLocationObject(PyObject *filename, int lineno, int col_offset)
|
2010-09-20 19:42:10 -03:00
|
|
|
|
|
|
|
Set file, line, and offset information for the current exception. If the
|
|
|
|
current exception is not a :exc:`SyntaxError`, then it sets additional
|
|
|
|
attributes, which make the exception printing subsystem think the exception
|
2013-08-26 17:28:21 -03:00
|
|
|
is a :exc:`SyntaxError`.
|
2010-09-20 19:42:10 -03:00
|
|
|
|
2014-03-24 05:06:18 -03:00
|
|
|
.. versionadded:: 3.4
|
2013-08-26 17:28:21 -03:00
|
|
|
|
|
|
|
|
2015-06-21 11:11:21 -03:00
|
|
|
.. c:function:: void PyErr_SyntaxLocationEx(const char *filename, int lineno, int col_offset)
|
2013-08-26 17:28:21 -03:00
|
|
|
|
|
|
|
Like :c:func:`PyErr_SyntaxLocationObject`, but *filename* is a byte string
|
|
|
|
decoded from the filesystem encoding (:func:`os.fsdecode`).
|
|
|
|
|
2014-03-24 05:06:18 -03:00
|
|
|
.. versionadded:: 3.2
|
2010-09-21 18:29:26 -03:00
|
|
|
|
2010-09-20 19:42:10 -03:00
|
|
|
|
2015-06-21 11:11:21 -03:00
|
|
|
.. c:function:: void PyErr_SyntaxLocation(const char *filename, int lineno)
|
2010-09-20 19:42:10 -03:00
|
|
|
|
2013-08-26 17:28:21 -03:00
|
|
|
Like :c:func:`PyErr_SyntaxLocationEx`, but the col_offset parameter is
|
2010-09-20 19:42:10 -03:00
|
|
|
omitted.
|
|
|
|
|
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
.. c:function:: void PyErr_BadInternalCall()
|
2007-08-15 11:28:22 -03:00
|
|
|
|
Merged revisions 69129-69131,69139-69140,69143,69154-69159,69169,69288-69289,69293,69297-69301,69348 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r69129 | benjamin.peterson | 2009-01-30 19:42:55 -0600 (Fri, 30 Jan 2009) | 1 line
check the errno in bad fd cases
........
r69130 | andrew.kuchling | 2009-01-30 20:50:09 -0600 (Fri, 30 Jan 2009) | 1 line
Add a section
........
r69131 | andrew.kuchling | 2009-01-30 21:26:02 -0600 (Fri, 30 Jan 2009) | 1 line
Text edits and markup fixes
........
r69139 | mark.dickinson | 2009-01-31 10:44:04 -0600 (Sat, 31 Jan 2009) | 2 lines
Add an extra test for long <-> float hash equivalence.
........
r69140 | benjamin.peterson | 2009-01-31 10:52:03 -0600 (Sat, 31 Jan 2009) | 1 line
PyErr_BadInternalCall() raises a SystemError, not TypeError #5112
........
r69143 | benjamin.peterson | 2009-01-31 15:00:10 -0600 (Sat, 31 Jan 2009) | 1 line
I believe the intention here was to avoid a global lookup
........
r69154 | benjamin.peterson | 2009-01-31 16:33:02 -0600 (Sat, 31 Jan 2009) | 1 line
fix indentation in comment
........
r69155 | david.goodger | 2009-01-31 16:53:46 -0600 (Sat, 31 Jan 2009) | 1 line
markup fix
........
r69156 | gregory.p.smith | 2009-01-31 16:57:30 -0600 (Sat, 31 Jan 2009) | 4 lines
- Issue #5104: The socket module now raises OverflowError when 16-bit port and
protocol numbers are supplied outside the allowed 0-65536 range on bind()
and getservbyport().
........
r69157 | benjamin.peterson | 2009-01-31 17:43:25 -0600 (Sat, 31 Jan 2009) | 1 line
add explanatory comment
........
r69158 | benjamin.peterson | 2009-01-31 17:54:38 -0600 (Sat, 31 Jan 2009) | 1 line
more flags which only work for function blocks
........
r69159 | gregory.p.smith | 2009-01-31 18:16:01 -0600 (Sat, 31 Jan 2009) | 2 lines
Update doc wording as suggested in issue4903.
........
r69169 | guilherme.polo | 2009-01-31 20:56:16 -0600 (Sat, 31 Jan 2009) | 3 lines
Restore Tkinter.Tk._loadtk so this test doesn't fail for problems
related to ttk.
........
r69288 | georg.brandl | 2009-02-05 04:30:57 -0600 (Thu, 05 Feb 2009) | 1 line
#5153: fix typo in example.
........
r69289 | georg.brandl | 2009-02-05 04:37:07 -0600 (Thu, 05 Feb 2009) | 1 line
#5144: document that PySys_SetArgv prepends the script directory (or the empty string) to sys.path.
........
r69293 | georg.brandl | 2009-02-05 04:59:28 -0600 (Thu, 05 Feb 2009) | 1 line
#5059: fix example.
........
r69297 | georg.brandl | 2009-02-05 05:32:18 -0600 (Thu, 05 Feb 2009) | 1 line
#5015: document PythonHome API functions.
........
r69298 | georg.brandl | 2009-02-05 05:33:21 -0600 (Thu, 05 Feb 2009) | 1 line
#4827: fix callback example.
........
r69299 | georg.brandl | 2009-02-05 05:35:28 -0600 (Thu, 05 Feb 2009) | 1 line
#4820: use correct module for ctypes.util.
........
r69300 | georg.brandl | 2009-02-05 05:38:23 -0600 (Thu, 05 Feb 2009) | 1 line
#4563: disable alpha and roman lists, fixes wrong formatting of contributor list.
........
r69301 | georg.brandl | 2009-02-05 05:40:35 -0600 (Thu, 05 Feb 2009) | 1 line
#5031: fix Thread.daemon property docs.
........
r69348 | benjamin.peterson | 2009-02-05 19:47:31 -0600 (Thu, 05 Feb 2009) | 1 line
fix download link
........
2009-02-05 22:40:07 -04:00
|
|
|
This is a shorthand for ``PyErr_SetString(PyExc_SystemError, 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.
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
|
2014-09-30 16:56:10 -03:00
|
|
|
Issuing warnings
|
|
|
|
================
|
|
|
|
|
|
|
|
Use these functions to issue warnings from C code. They mirror similar
|
|
|
|
functions exported by the Python :mod:`warnings` module. They normally
|
|
|
|
print 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 they will raise an exception. It is also possible that
|
|
|
|
the functions raise an exception because of a problem with the warning machinery.
|
|
|
|
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, :c:func:`Py_DECREF` owned references and return
|
|
|
|
an error value).
|
|
|
|
|
2014-10-06 07:58:00 -03:00
|
|
|
.. c:function:: int PyErr_WarnEx(PyObject *category, const char *message, Py_ssize_t stack_level)
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
Issue a warning message. The *category* argument is a warning category (see
|
2016-04-14 23:14:19 -03:00
|
|
|
below) or *NULL*; the *message* argument is a UTF-8 encoded string. *stack_level* is a
|
2007-08-15 11:28:22 -03:00
|
|
|
positive number giving a number of stack frames; the warning will be issued from
|
2010-08-13 11:03:48 -03:00
|
|
|
the currently executing line of code in that stack frame. A *stack_level* of 1
|
2010-10-06 07:11:56 -03:00
|
|
|
is the function calling :c:func:`PyErr_WarnEx`, 2 is the function above that,
|
2007-08-15 11:28:22 -03:00
|
|
|
and so forth.
|
|
|
|
|
2017-04-14 23:06:02 -03:00
|
|
|
Warning categories must be subclasses of :c:data:`PyExc_Warning`;
|
|
|
|
:c:data:`PyExc_Warning` is a subclass of :c:data:`PyExc_Exception`;
|
|
|
|
the default warning category is :c:data:`PyExc_RuntimeWarning`. The standard
|
|
|
|
Python warning categories are available as global variables whose names are
|
2017-05-19 17:37:57 -03:00
|
|
|
enumerated at :ref:`standardwarningcategories`.
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
2016-09-07 20:56:15 -03:00
|
|
|
.. c:function:: PyObject* PyErr_SetImportErrorSubclass(PyObject *msg, PyObject *name, PyObject *path)
|
|
|
|
|
|
|
|
Much like :c:func:`PyErr_SetImportError` but this function allows for
|
|
|
|
specifying a subclass of :exc:`ImportError` to raise.
|
|
|
|
|
2016-11-10 14:25:26 -04:00
|
|
|
.. versionadded:: 3.6
|
2016-09-07 20:56:15 -03:00
|
|
|
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2013-08-26 17:28:21 -03:00
|
|
|
.. c:function:: int PyErr_WarnExplicitObject(PyObject *category, PyObject *message, PyObject *filename, int lineno, PyObject *module, PyObject *registry)
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
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
|
2013-08-26 17:28:21 -03:00
|
|
|
described there.
|
|
|
|
|
|
|
|
.. versionadded:: 3.4
|
|
|
|
|
|
|
|
|
|
|
|
.. c:function:: int PyErr_WarnExplicit(PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry)
|
|
|
|
|
|
|
|
Similar to :c:func:`PyErr_WarnExplicitObject` except that *message* and
|
|
|
|
*module* are UTF-8 encoded strings, and *filename* is decoded from the
|
|
|
|
filesystem encoding (:func:`os.fsdecode`).
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
.. c:function:: int PyErr_WarnFormat(PyObject *category, Py_ssize_t stack_level, const char *format, ...)
|
2010-08-13 11:03:48 -03:00
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
Function similar to :c:func:`PyErr_WarnEx`, but use
|
2010-12-26 21:49:26 -04:00
|
|
|
:c:func:`PyUnicode_FromFormat` to format the warning message. *format* is
|
|
|
|
an ASCII-encoded string.
|
2010-08-13 11:03:48 -03:00
|
|
|
|
|
|
|
.. versionadded:: 3.2
|
|
|
|
|
2012-04-24 14:16:24 -03:00
|
|
|
|
2016-03-18 21:03:51 -03:00
|
|
|
.. c:function:: int PyErr_ResourceWarning(PyObject *source, Py_ssize_t stack_level, const char *format, ...)
|
|
|
|
|
|
|
|
Function similar to :c:func:`PyErr_WarnFormat`, but *category* is
|
|
|
|
:exc:`ResourceWarning` and pass *source* to :func:`warnings.WarningMessage`.
|
|
|
|
|
|
|
|
.. versionadded:: 3.6
|
|
|
|
|
|
|
|
|
2014-09-30 16:56:10 -03:00
|
|
|
Querying the error indicator
|
|
|
|
============================
|
|
|
|
|
|
|
|
.. c:function:: 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 :c:func:`PyErr_Set\*`
|
|
|
|
functions or to :c:func:`PyErr_Restore`). If not set, return *NULL*. You do not
|
|
|
|
own a reference to the return value, so you do not need to :c:func:`Py_DECREF`
|
|
|
|
it.
|
|
|
|
|
|
|
|
.. note::
|
|
|
|
|
|
|
|
Do not compare the return value to a specific exception; use
|
|
|
|
:c:func:`PyErr_ExceptionMatches` instead, shown below. (The comparison could
|
|
|
|
easily fail since the exception may be an instance instead of a class, in the
|
2015-01-13 10:20:31 -04:00
|
|
|
case of a class exception, or it may be a subclass of the expected exception.)
|
2014-09-30 16:56:10 -03:00
|
|
|
|
|
|
|
|
|
|
|
.. c:function:: 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.
|
|
|
|
|
|
|
|
|
|
|
|
.. c:function:: int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)
|
|
|
|
|
|
|
|
Return true if the *given* exception matches the exception type 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 exception types in the tuple (and
|
|
|
|
recursively in subtuples) are searched for a match.
|
|
|
|
|
|
|
|
|
|
|
|
.. c:function:: 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 catch exceptions or
|
|
|
|
by code that needs to save and restore the error indicator temporarily, e.g.::
|
|
|
|
|
|
|
|
{
|
2016-12-25 10:22:23 -04:00
|
|
|
PyObject *type, *value, *traceback;
|
2014-09-30 16:56:10 -03:00
|
|
|
PyErr_Fetch(&type, &value, &traceback);
|
|
|
|
|
|
|
|
/* ... code that might produce other errors ... */
|
|
|
|
|
|
|
|
PyErr_Restore(type, value, traceback);
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
.. c:function:: 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 :c:func:`PyErr_Fetch` to save the current
|
|
|
|
error indicator.
|
|
|
|
|
|
|
|
|
|
|
|
.. c:function:: void PyErr_NormalizeException(PyObject**exc, PyObject**val, PyObject**tb)
|
|
|
|
|
|
|
|
Under certain circumstances, the values returned by :c:func:`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.
|
|
|
|
|
|
|
|
.. note::
|
|
|
|
|
|
|
|
This function *does not* implicitly set the ``__traceback__``
|
|
|
|
attribute on the exception value. If setting the traceback
|
|
|
|
appropriately is desired, the following additional snippet is needed::
|
|
|
|
|
|
|
|
if (tb != NULL) {
|
|
|
|
PyException_SetTraceback(val, tb);
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
.. c:function:: void PyErr_GetExcInfo(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
|
|
|
|
|
|
|
|
Retrieve the exception info, as known from ``sys.exc_info()``. This refers
|
|
|
|
to an exception that was *already caught*, not to an exception that was
|
|
|
|
freshly raised. Returns new references for the three objects, any of which
|
|
|
|
may be *NULL*. Does not modify the exception info state.
|
|
|
|
|
|
|
|
.. note::
|
|
|
|
|
|
|
|
This function is not normally used by code that wants to handle exceptions.
|
|
|
|
Rather, it can be used when code needs to save and restore the exception
|
|
|
|
state temporarily. Use :c:func:`PyErr_SetExcInfo` to restore or clear the
|
|
|
|
exception state.
|
|
|
|
|
|
|
|
.. versionadded:: 3.3
|
|
|
|
|
|
|
|
|
|
|
|
.. c:function:: void PyErr_SetExcInfo(PyObject *type, PyObject *value, PyObject *traceback)
|
|
|
|
|
|
|
|
Set the exception info, as known from ``sys.exc_info()``. This refers
|
|
|
|
to an exception that was *already caught*, not to an exception that was
|
|
|
|
freshly raised. This function steals the references of the arguments.
|
|
|
|
To clear the exception state, pass *NULL* for all three arguments.
|
|
|
|
For general rules about the three arguments, see :c:func:`PyErr_Restore`.
|
|
|
|
|
|
|
|
.. note::
|
|
|
|
|
|
|
|
This function is not normally used by code that wants to handle exceptions.
|
|
|
|
Rather, it can be used when code needs to save and restore the exception
|
|
|
|
state temporarily. Use :c:func:`PyErr_GetExcInfo` to read the exception
|
|
|
|
state.
|
|
|
|
|
|
|
|
.. versionadded:: 3.3
|
|
|
|
|
|
|
|
|
|
|
|
Signal Handling
|
|
|
|
===============
|
|
|
|
|
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
.. c:function:: int PyErr_CheckSignals()
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
.. 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.
|
|
|
|
|
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
.. c:function:: void PyErr_SetInterrupt()
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
.. index::
|
|
|
|
single: SIGINT
|
|
|
|
single: KeyboardInterrupt (built-in exception)
|
|
|
|
|
|
|
|
This function simulates the effect of a :const:`SIGINT` signal arriving --- the
|
2010-10-06 07:11:56 -03:00
|
|
|
next time :c:func:`PyErr_CheckSignals` is called, :exc:`KeyboardInterrupt` will
|
2007-08-15 11:28:22 -03:00
|
|
|
be raised. It may be called without holding the interpreter lock.
|
|
|
|
|
|
|
|
.. % XXX This was described as obsolete, but is used in
|
2008-05-25 10:05:15 -03:00
|
|
|
.. % _thread.interrupt_main() (used from IDLE), so it's still needed.
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
.. c:function:: int PySignal_SetWakeupFd(int fd)
|
Merged revisions 59565-59594 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r59568 | facundo.batista | 2007-12-19 13:53:01 +0100 (Wed, 19 Dec 2007) | 3 lines
Some minor cleanups. Thanks Mark Dickinson.
........
r59573 | raymond.hettinger | 2007-12-19 19:13:31 +0100 (Wed, 19 Dec 2007) | 1 line
Fix issue 1661: Flags argument silently ignored in re functions with compiled regexes.
........
r59574 | guido.van.rossum | 2007-12-19 20:41:06 +0100 (Wed, 19 Dec 2007) | 7 lines
Patch #1583 by Adam Olsen.
This adds signal.set_wakeup_fd(fd) which sets a file descriptor to
which a zero byte will be written whenever a C exception handler runs.
I added a simple C API as well, PySignal_SetWakeupFd(fd).
........
r59575 | raymond.hettinger | 2007-12-19 23:14:34 +0100 (Wed, 19 Dec 2007) | 1 line
Bigger range for non-extended opargs.
........
r59576 | guido.van.rossum | 2007-12-19 23:51:13 +0100 (Wed, 19 Dec 2007) | 5 lines
Patch #1549 by Thomas Herve.
This changes the rules for when __hash__ is inherited slightly,
by allowing it to be inherited when one or more of __lt__, __le__,
__gt__, __ge__ are overridden, as long as __eq__ and __ne__ aren't.
........
r59577 | raymond.hettinger | 2007-12-20 02:25:05 +0100 (Thu, 20 Dec 2007) | 1 line
Add comments
........
r59578 | brett.cannon | 2007-12-20 11:09:52 +0100 (Thu, 20 Dec 2007) | 3 lines
Add tests for the warnings module; specifically formatwarning and showwarning.
Still need tests for warn_explicit and simplefilter.
........
r59582 | guido.van.rossum | 2007-12-20 18:28:10 +0100 (Thu, 20 Dec 2007) | 2 lines
Patch #1672 by Joseph Armbruster. Use tempdir() to get a temporary directory.
........
r59584 | georg.brandl | 2007-12-20 22:03:02 +0100 (Thu, 20 Dec 2007) | 2 lines
Fix refleak introduced in r59576.
........
r59586 | guido.van.rossum | 2007-12-21 00:48:28 +0100 (Fri, 21 Dec 2007) | 4 lines
Improve performance of built-in any()/all() by avoiding PyIter_Next() --
using a trick found in ifilter().
Feel free to backport to 2.5.
........
r59591 | andrew.kuchling | 2007-12-22 18:27:02 +0100 (Sat, 22 Dec 2007) | 1 line
Add item
........
2007-12-24 04:52:31 -04:00
|
|
|
|
2014-07-29 18:31:34 -03:00
|
|
|
This utility function specifies a file descriptor to which the signal number
|
|
|
|
is written as a single byte whenever a signal is received. *fd* must be
|
|
|
|
non-blocking. It returns the previous such file descriptor.
|
|
|
|
|
|
|
|
The value ``-1`` disables the feature; this is the initial state.
|
Merged revisions 59565-59594 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r59568 | facundo.batista | 2007-12-19 13:53:01 +0100 (Wed, 19 Dec 2007) | 3 lines
Some minor cleanups. Thanks Mark Dickinson.
........
r59573 | raymond.hettinger | 2007-12-19 19:13:31 +0100 (Wed, 19 Dec 2007) | 1 line
Fix issue 1661: Flags argument silently ignored in re functions with compiled regexes.
........
r59574 | guido.van.rossum | 2007-12-19 20:41:06 +0100 (Wed, 19 Dec 2007) | 7 lines
Patch #1583 by Adam Olsen.
This adds signal.set_wakeup_fd(fd) which sets a file descriptor to
which a zero byte will be written whenever a C exception handler runs.
I added a simple C API as well, PySignal_SetWakeupFd(fd).
........
r59575 | raymond.hettinger | 2007-12-19 23:14:34 +0100 (Wed, 19 Dec 2007) | 1 line
Bigger range for non-extended opargs.
........
r59576 | guido.van.rossum | 2007-12-19 23:51:13 +0100 (Wed, 19 Dec 2007) | 5 lines
Patch #1549 by Thomas Herve.
This changes the rules for when __hash__ is inherited slightly,
by allowing it to be inherited when one or more of __lt__, __le__,
__gt__, __ge__ are overridden, as long as __eq__ and __ne__ aren't.
........
r59577 | raymond.hettinger | 2007-12-20 02:25:05 +0100 (Thu, 20 Dec 2007) | 1 line
Add comments
........
r59578 | brett.cannon | 2007-12-20 11:09:52 +0100 (Thu, 20 Dec 2007) | 3 lines
Add tests for the warnings module; specifically formatwarning and showwarning.
Still need tests for warn_explicit and simplefilter.
........
r59582 | guido.van.rossum | 2007-12-20 18:28:10 +0100 (Thu, 20 Dec 2007) | 2 lines
Patch #1672 by Joseph Armbruster. Use tempdir() to get a temporary directory.
........
r59584 | georg.brandl | 2007-12-20 22:03:02 +0100 (Thu, 20 Dec 2007) | 2 lines
Fix refleak introduced in r59576.
........
r59586 | guido.van.rossum | 2007-12-21 00:48:28 +0100 (Fri, 21 Dec 2007) | 4 lines
Improve performance of built-in any()/all() by avoiding PyIter_Next() --
using a trick found in ifilter().
Feel free to backport to 2.5.
........
r59591 | andrew.kuchling | 2007-12-22 18:27:02 +0100 (Sat, 22 Dec 2007) | 1 line
Add item
........
2007-12-24 04:52:31 -04:00
|
|
|
This is equivalent to :func:`signal.set_wakeup_fd` in Python, but without any
|
|
|
|
error checking. *fd* should be a valid file descriptor. The function should
|
|
|
|
only be called from the main thread.
|
|
|
|
|
2014-07-29 18:31:34 -03:00
|
|
|
.. versionchanged:: 3.5
|
|
|
|
On Windows, the function now also supports socket handles.
|
|
|
|
|
Merged revisions 59565-59594 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r59568 | facundo.batista | 2007-12-19 13:53:01 +0100 (Wed, 19 Dec 2007) | 3 lines
Some minor cleanups. Thanks Mark Dickinson.
........
r59573 | raymond.hettinger | 2007-12-19 19:13:31 +0100 (Wed, 19 Dec 2007) | 1 line
Fix issue 1661: Flags argument silently ignored in re functions with compiled regexes.
........
r59574 | guido.van.rossum | 2007-12-19 20:41:06 +0100 (Wed, 19 Dec 2007) | 7 lines
Patch #1583 by Adam Olsen.
This adds signal.set_wakeup_fd(fd) which sets a file descriptor to
which a zero byte will be written whenever a C exception handler runs.
I added a simple C API as well, PySignal_SetWakeupFd(fd).
........
r59575 | raymond.hettinger | 2007-12-19 23:14:34 +0100 (Wed, 19 Dec 2007) | 1 line
Bigger range for non-extended opargs.
........
r59576 | guido.van.rossum | 2007-12-19 23:51:13 +0100 (Wed, 19 Dec 2007) | 5 lines
Patch #1549 by Thomas Herve.
This changes the rules for when __hash__ is inherited slightly,
by allowing it to be inherited when one or more of __lt__, __le__,
__gt__, __ge__ are overridden, as long as __eq__ and __ne__ aren't.
........
r59577 | raymond.hettinger | 2007-12-20 02:25:05 +0100 (Thu, 20 Dec 2007) | 1 line
Add comments
........
r59578 | brett.cannon | 2007-12-20 11:09:52 +0100 (Thu, 20 Dec 2007) | 3 lines
Add tests for the warnings module; specifically formatwarning and showwarning.
Still need tests for warn_explicit and simplefilter.
........
r59582 | guido.van.rossum | 2007-12-20 18:28:10 +0100 (Thu, 20 Dec 2007) | 2 lines
Patch #1672 by Joseph Armbruster. Use tempdir() to get a temporary directory.
........
r59584 | georg.brandl | 2007-12-20 22:03:02 +0100 (Thu, 20 Dec 2007) | 2 lines
Fix refleak introduced in r59576.
........
r59586 | guido.van.rossum | 2007-12-21 00:48:28 +0100 (Fri, 21 Dec 2007) | 4 lines
Improve performance of built-in any()/all() by avoiding PyIter_Next() --
using a trick found in ifilter().
Feel free to backport to 2.5.
........
r59591 | andrew.kuchling | 2007-12-22 18:27:02 +0100 (Sat, 22 Dec 2007) | 1 line
Add item
........
2007-12-24 04:52:31 -04:00
|
|
|
|
2014-09-30 16:56:10 -03:00
|
|
|
Exception Classes
|
|
|
|
=================
|
|
|
|
|
2015-06-21 11:11:21 -03:00
|
|
|
.. c:function:: PyObject* PyErr_NewException(const char *name, PyObject *base, PyObject *dict)
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2011-07-13 10:59:24 -03:00
|
|
|
This utility function creates and returns a new exception class. The *name*
|
2007-08-15 11:28:22 -03:00
|
|
|
argument must be the name of the new exception, a C string of the form
|
2011-07-13 10:59:24 -03:00
|
|
|
``module.classname``. The *base* and *dict* arguments are normally *NULL*.
|
|
|
|
This creates a class object derived from :exc:`Exception` (accessible in C as
|
2010-10-06 07:11:56 -03:00
|
|
|
:c:data:`PyExc_Exception`).
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
2015-06-21 11:11:21 -03:00
|
|
|
.. c:function:: PyObject* PyErr_NewExceptionWithDoc(const char *name, const char *doc, PyObject *base, PyObject *dict)
|
2009-12-28 04:41:01 -04:00
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
Same as :c:func:`PyErr_NewException`, except that the new exception class can
|
2009-12-28 04:41:01 -04:00
|
|
|
easily be given a docstring: If *doc* is non-*NULL*, it will be used as the
|
|
|
|
docstring for the exception class.
|
|
|
|
|
|
|
|
.. versionadded:: 3.2
|
|
|
|
|
|
|
|
|
2009-03-31 01:16:10 -03:00
|
|
|
Exception Objects
|
|
|
|
=================
|
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
.. c:function:: PyObject* PyException_GetTraceback(PyObject *ex)
|
2009-03-31 01:16:10 -03:00
|
|
|
|
|
|
|
Return the traceback associated with the exception as a new reference, as
|
|
|
|
accessible from Python through :attr:`__traceback__`. If there is no
|
|
|
|
traceback associated, this returns *NULL*.
|
|
|
|
|
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
.. c:function:: int PyException_SetTraceback(PyObject *ex, PyObject *tb)
|
2009-03-31 01:16:10 -03:00
|
|
|
|
|
|
|
Set the traceback associated with the exception to *tb*. Use ``Py_None`` to
|
|
|
|
clear it.
|
|
|
|
|
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
.. c:function:: PyObject* PyException_GetContext(PyObject *ex)
|
2009-03-31 01:16:10 -03:00
|
|
|
|
|
|
|
Return the context (another exception instance during whose handling *ex* was
|
|
|
|
raised) associated with the exception as a new reference, as accessible from
|
|
|
|
Python through :attr:`__context__`. If there is no context associated, this
|
|
|
|
returns *NULL*.
|
|
|
|
|
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
.. c:function:: void PyException_SetContext(PyObject *ex, PyObject *ctx)
|
2009-03-31 01:16:10 -03:00
|
|
|
|
|
|
|
Set the context associated with the exception to *ctx*. Use *NULL* to clear
|
|
|
|
it. There is no type check to make sure that *ctx* is an exception instance.
|
|
|
|
This steals a reference to *ctx*.
|
|
|
|
|
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
.. c:function:: PyObject* PyException_GetCause(PyObject *ex)
|
2009-03-31 01:16:10 -03:00
|
|
|
|
2012-02-26 03:49:52 -04:00
|
|
|
Return the cause (either an exception instance, or :const:`None`,
|
|
|
|
set by ``raise ... from ...``) associated with the exception as a new
|
|
|
|
reference, as accessible from Python through :attr:`__cause__`.
|
|
|
|
|
2009-03-31 01:16:10 -03:00
|
|
|
|
2014-03-16 01:13:56 -03:00
|
|
|
.. c:function:: void PyException_SetCause(PyObject *ex, PyObject *cause)
|
2009-03-31 01:16:10 -03:00
|
|
|
|
2014-03-16 01:13:56 -03:00
|
|
|
Set the cause associated with the exception to *cause*. Use *NULL* to clear
|
|
|
|
it. There is no type check to make sure that *cause* is either an exception
|
|
|
|
instance or :const:`None`. This steals a reference to *cause*.
|
2012-02-26 03:49:52 -04:00
|
|
|
|
2012-05-15 02:09:31 -03:00
|
|
|
:attr:`__suppress_context__` is implicitly set to ``True`` by this function.
|
2009-03-31 01:16:10 -03:00
|
|
|
|
|
|
|
|
2010-11-23 03:54:19 -04:00
|
|
|
.. _unicodeexceptions:
|
|
|
|
|
|
|
|
Unicode Exception Objects
|
|
|
|
=========================
|
|
|
|
|
|
|
|
The following functions are used to create and modify Unicode exceptions from C.
|
|
|
|
|
|
|
|
.. 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)
|
|
|
|
|
|
|
|
Create a :class:`UnicodeDecodeError` object with the attributes *encoding*,
|
2010-12-26 21:49:26 -04:00
|
|
|
*object*, *length*, *start*, *end* and *reason*. *encoding* and *reason* are
|
|
|
|
UTF-8 encoded strings.
|
2010-11-23 03:54:19 -04:00
|
|
|
|
|
|
|
.. 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)
|
|
|
|
|
|
|
|
Create a :class:`UnicodeEncodeError` object with the attributes *encoding*,
|
2010-12-26 21:49:26 -04:00
|
|
|
*object*, *length*, *start*, *end* and *reason*. *encoding* and *reason* are
|
|
|
|
UTF-8 encoded strings.
|
2010-11-23 03:54:19 -04:00
|
|
|
|
|
|
|
.. c:function:: PyObject* PyUnicodeTranslateError_Create(const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
|
|
|
|
|
|
|
|
Create a :class:`UnicodeTranslateError` object with the attributes *object*,
|
2016-04-14 23:14:19 -03:00
|
|
|
*length*, *start*, *end* and *reason*. *reason* is a UTF-8 encoded string.
|
2010-11-23 03:54:19 -04:00
|
|
|
|
|
|
|
.. c:function:: PyObject* PyUnicodeDecodeError_GetEncoding(PyObject *exc)
|
|
|
|
PyObject* PyUnicodeEncodeError_GetEncoding(PyObject *exc)
|
|
|
|
|
|
|
|
Return the *encoding* attribute of the given exception object.
|
|
|
|
|
|
|
|
.. c:function:: PyObject* PyUnicodeDecodeError_GetObject(PyObject *exc)
|
|
|
|
PyObject* PyUnicodeEncodeError_GetObject(PyObject *exc)
|
|
|
|
PyObject* PyUnicodeTranslateError_GetObject(PyObject *exc)
|
|
|
|
|
|
|
|
Return the *object* attribute of the given exception object.
|
|
|
|
|
|
|
|
.. c:function:: int PyUnicodeDecodeError_GetStart(PyObject *exc, Py_ssize_t *start)
|
|
|
|
int PyUnicodeEncodeError_GetStart(PyObject *exc, Py_ssize_t *start)
|
|
|
|
int PyUnicodeTranslateError_GetStart(PyObject *exc, Py_ssize_t *start)
|
|
|
|
|
|
|
|
Get the *start* attribute of the given exception object and place it into
|
|
|
|
*\*start*. *start* must not be *NULL*. Return ``0`` on success, ``-1`` on
|
|
|
|
failure.
|
|
|
|
|
|
|
|
.. c:function:: int PyUnicodeDecodeError_SetStart(PyObject *exc, Py_ssize_t start)
|
|
|
|
int PyUnicodeEncodeError_SetStart(PyObject *exc, Py_ssize_t start)
|
|
|
|
int PyUnicodeTranslateError_SetStart(PyObject *exc, Py_ssize_t start)
|
|
|
|
|
|
|
|
Set the *start* attribute of the given exception object to *start*. Return
|
|
|
|
``0`` on success, ``-1`` on failure.
|
|
|
|
|
|
|
|
.. c:function:: int PyUnicodeDecodeError_GetEnd(PyObject *exc, Py_ssize_t *end)
|
|
|
|
int PyUnicodeEncodeError_GetEnd(PyObject *exc, Py_ssize_t *end)
|
|
|
|
int PyUnicodeTranslateError_GetEnd(PyObject *exc, Py_ssize_t *end)
|
|
|
|
|
|
|
|
Get the *end* attribute of the given exception object and place it into
|
|
|
|
*\*end*. *end* must not be *NULL*. Return ``0`` on success, ``-1`` on
|
|
|
|
failure.
|
|
|
|
|
|
|
|
.. c:function:: int PyUnicodeDecodeError_SetEnd(PyObject *exc, Py_ssize_t end)
|
|
|
|
int PyUnicodeEncodeError_SetEnd(PyObject *exc, Py_ssize_t end)
|
|
|
|
int PyUnicodeTranslateError_SetEnd(PyObject *exc, Py_ssize_t end)
|
|
|
|
|
|
|
|
Set the *end* attribute of the given exception object to *end*. Return ``0``
|
|
|
|
on success, ``-1`` on failure.
|
|
|
|
|
|
|
|
.. c:function:: PyObject* PyUnicodeDecodeError_GetReason(PyObject *exc)
|
|
|
|
PyObject* PyUnicodeEncodeError_GetReason(PyObject *exc)
|
|
|
|
PyObject* PyUnicodeTranslateError_GetReason(PyObject *exc)
|
|
|
|
|
|
|
|
Return the *reason* attribute of the given exception object.
|
|
|
|
|
|
|
|
.. c:function:: int PyUnicodeDecodeError_SetReason(PyObject *exc, const char *reason)
|
|
|
|
int PyUnicodeEncodeError_SetReason(PyObject *exc, const char *reason)
|
|
|
|
int PyUnicodeTranslateError_SetReason(PyObject *exc, const char *reason)
|
|
|
|
|
|
|
|
Set the *reason* attribute of the given exception object to *reason*. Return
|
|
|
|
``0`` on success, ``-1`` on failure.
|
|
|
|
|
|
|
|
|
Merged revisions 78760,78771-78773,78802,78922,78952 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r78760 | georg.brandl | 2010-03-07 16:23:59 +0100 (So, 07 Mär 2010) | 1 line
#5341: more built-in vs builtin fixes.
........
r78771 | georg.brandl | 2010-03-07 21:58:31 +0100 (So, 07 Mär 2010) | 1 line
#8085: The function is called PyObject_NewVar, not PyObject_VarNew.
........
r78772 | georg.brandl | 2010-03-07 22:12:28 +0100 (So, 07 Mär 2010) | 1 line
#8039: document conditional expressions better, giving them their own section.
........
r78773 | georg.brandl | 2010-03-07 22:32:06 +0100 (So, 07 Mär 2010) | 1 line
#8044: document Py_{Enter,Leave}RecursiveCall functions.
........
r78802 | georg.brandl | 2010-03-08 17:28:40 +0100 (Mo, 08 Mär 2010) | 1 line
Fix typo.
........
r78922 | georg.brandl | 2010-03-13 14:41:58 +0100 (Sa, 13 Mär 2010) | 1 line
Update for new download location.
........
r78952 | georg.brandl | 2010-03-14 10:55:08 +0100 (So, 14 Mär 2010) | 1 line
#8137: add iso-8859-16 to the standard encodings table.
........
2010-03-14 07:56:14 -03:00
|
|
|
Recursion Control
|
|
|
|
=================
|
|
|
|
|
|
|
|
These two functions provide a way to perform safe recursive calls at the C
|
|
|
|
level, both in the core and in extension modules. They are needed if the
|
|
|
|
recursive code does not necessarily invoke Python code (which tracks its
|
|
|
|
recursion depth automatically).
|
|
|
|
|
2015-06-21 10:26:28 -03:00
|
|
|
.. c:function:: int Py_EnterRecursiveCall(const char *where)
|
Merged revisions 78760,78771-78773,78802,78922,78952 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r78760 | georg.brandl | 2010-03-07 16:23:59 +0100 (So, 07 Mär 2010) | 1 line
#5341: more built-in vs builtin fixes.
........
r78771 | georg.brandl | 2010-03-07 21:58:31 +0100 (So, 07 Mär 2010) | 1 line
#8085: The function is called PyObject_NewVar, not PyObject_VarNew.
........
r78772 | georg.brandl | 2010-03-07 22:12:28 +0100 (So, 07 Mär 2010) | 1 line
#8039: document conditional expressions better, giving them their own section.
........
r78773 | georg.brandl | 2010-03-07 22:32:06 +0100 (So, 07 Mär 2010) | 1 line
#8044: document Py_{Enter,Leave}RecursiveCall functions.
........
r78802 | georg.brandl | 2010-03-08 17:28:40 +0100 (Mo, 08 Mär 2010) | 1 line
Fix typo.
........
r78922 | georg.brandl | 2010-03-13 14:41:58 +0100 (Sa, 13 Mär 2010) | 1 line
Update for new download location.
........
r78952 | georg.brandl | 2010-03-14 10:55:08 +0100 (So, 14 Mär 2010) | 1 line
#8137: add iso-8859-16 to the standard encodings table.
........
2010-03-14 07:56:14 -03:00
|
|
|
|
|
|
|
Marks a point where a recursive C-level call is about to be performed.
|
|
|
|
|
2011-10-19 05:06:26 -03:00
|
|
|
If :const:`USE_STACKCHECK` is defined, this function checks if the OS
|
2010-10-06 07:11:56 -03:00
|
|
|
stack overflowed using :c:func:`PyOS_CheckStack`. In this is the case, it
|
Merged revisions 78760,78771-78773,78802,78922,78952 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r78760 | georg.brandl | 2010-03-07 16:23:59 +0100 (So, 07 Mär 2010) | 1 line
#5341: more built-in vs builtin fixes.
........
r78771 | georg.brandl | 2010-03-07 21:58:31 +0100 (So, 07 Mär 2010) | 1 line
#8085: The function is called PyObject_NewVar, not PyObject_VarNew.
........
r78772 | georg.brandl | 2010-03-07 22:12:28 +0100 (So, 07 Mär 2010) | 1 line
#8039: document conditional expressions better, giving them their own section.
........
r78773 | georg.brandl | 2010-03-07 22:32:06 +0100 (So, 07 Mär 2010) | 1 line
#8044: document Py_{Enter,Leave}RecursiveCall functions.
........
r78802 | georg.brandl | 2010-03-08 17:28:40 +0100 (Mo, 08 Mär 2010) | 1 line
Fix typo.
........
r78922 | georg.brandl | 2010-03-13 14:41:58 +0100 (Sa, 13 Mär 2010) | 1 line
Update for new download location.
........
r78952 | georg.brandl | 2010-03-14 10:55:08 +0100 (So, 14 Mär 2010) | 1 line
#8137: add iso-8859-16 to the standard encodings table.
........
2010-03-14 07:56:14 -03:00
|
|
|
sets a :exc:`MemoryError` and returns a nonzero value.
|
|
|
|
|
|
|
|
The function then checks if the recursion limit is reached. If this is the
|
2015-07-03 02:04:23 -03:00
|
|
|
case, a :exc:`RecursionError` is set and a nonzero value is returned.
|
Merged revisions 78760,78771-78773,78802,78922,78952 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r78760 | georg.brandl | 2010-03-07 16:23:59 +0100 (So, 07 Mär 2010) | 1 line
#5341: more built-in vs builtin fixes.
........
r78771 | georg.brandl | 2010-03-07 21:58:31 +0100 (So, 07 Mär 2010) | 1 line
#8085: The function is called PyObject_NewVar, not PyObject_VarNew.
........
r78772 | georg.brandl | 2010-03-07 22:12:28 +0100 (So, 07 Mär 2010) | 1 line
#8039: document conditional expressions better, giving them their own section.
........
r78773 | georg.brandl | 2010-03-07 22:32:06 +0100 (So, 07 Mär 2010) | 1 line
#8044: document Py_{Enter,Leave}RecursiveCall functions.
........
r78802 | georg.brandl | 2010-03-08 17:28:40 +0100 (Mo, 08 Mär 2010) | 1 line
Fix typo.
........
r78922 | georg.brandl | 2010-03-13 14:41:58 +0100 (Sa, 13 Mär 2010) | 1 line
Update for new download location.
........
r78952 | georg.brandl | 2010-03-14 10:55:08 +0100 (So, 14 Mär 2010) | 1 line
#8137: add iso-8859-16 to the standard encodings table.
........
2010-03-14 07:56:14 -03:00
|
|
|
Otherwise, zero is returned.
|
|
|
|
|
|
|
|
*where* should be a string such as ``" in instance check"`` to be
|
2015-07-03 02:04:23 -03:00
|
|
|
concatenated to the :exc:`RecursionError` message caused by the recursion
|
|
|
|
depth limit.
|
Merged revisions 78760,78771-78773,78802,78922,78952 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r78760 | georg.brandl | 2010-03-07 16:23:59 +0100 (So, 07 Mär 2010) | 1 line
#5341: more built-in vs builtin fixes.
........
r78771 | georg.brandl | 2010-03-07 21:58:31 +0100 (So, 07 Mär 2010) | 1 line
#8085: The function is called PyObject_NewVar, not PyObject_VarNew.
........
r78772 | georg.brandl | 2010-03-07 22:12:28 +0100 (So, 07 Mär 2010) | 1 line
#8039: document conditional expressions better, giving them their own section.
........
r78773 | georg.brandl | 2010-03-07 22:32:06 +0100 (So, 07 Mär 2010) | 1 line
#8044: document Py_{Enter,Leave}RecursiveCall functions.
........
r78802 | georg.brandl | 2010-03-08 17:28:40 +0100 (Mo, 08 Mär 2010) | 1 line
Fix typo.
........
r78922 | georg.brandl | 2010-03-13 14:41:58 +0100 (Sa, 13 Mär 2010) | 1 line
Update for new download location.
........
r78952 | georg.brandl | 2010-03-14 10:55:08 +0100 (So, 14 Mär 2010) | 1 line
#8137: add iso-8859-16 to the standard encodings table.
........
2010-03-14 07:56:14 -03:00
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
.. c:function:: void Py_LeaveRecursiveCall()
|
Merged revisions 78760,78771-78773,78802,78922,78952 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r78760 | georg.brandl | 2010-03-07 16:23:59 +0100 (So, 07 Mär 2010) | 1 line
#5341: more built-in vs builtin fixes.
........
r78771 | georg.brandl | 2010-03-07 21:58:31 +0100 (So, 07 Mär 2010) | 1 line
#8085: The function is called PyObject_NewVar, not PyObject_VarNew.
........
r78772 | georg.brandl | 2010-03-07 22:12:28 +0100 (So, 07 Mär 2010) | 1 line
#8039: document conditional expressions better, giving them their own section.
........
r78773 | georg.brandl | 2010-03-07 22:32:06 +0100 (So, 07 Mär 2010) | 1 line
#8044: document Py_{Enter,Leave}RecursiveCall functions.
........
r78802 | georg.brandl | 2010-03-08 17:28:40 +0100 (Mo, 08 Mär 2010) | 1 line
Fix typo.
........
r78922 | georg.brandl | 2010-03-13 14:41:58 +0100 (Sa, 13 Mär 2010) | 1 line
Update for new download location.
........
r78952 | georg.brandl | 2010-03-14 10:55:08 +0100 (So, 14 Mär 2010) | 1 line
#8137: add iso-8859-16 to the standard encodings table.
........
2010-03-14 07:56:14 -03:00
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
Ends a :c:func:`Py_EnterRecursiveCall`. Must be called once for each
|
|
|
|
*successful* invocation of :c:func:`Py_EnterRecursiveCall`.
|
Merged revisions 78760,78771-78773,78802,78922,78952 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r78760 | georg.brandl | 2010-03-07 16:23:59 +0100 (So, 07 Mär 2010) | 1 line
#5341: more built-in vs builtin fixes.
........
r78771 | georg.brandl | 2010-03-07 21:58:31 +0100 (So, 07 Mär 2010) | 1 line
#8085: The function is called PyObject_NewVar, not PyObject_VarNew.
........
r78772 | georg.brandl | 2010-03-07 22:12:28 +0100 (So, 07 Mär 2010) | 1 line
#8039: document conditional expressions better, giving them their own section.
........
r78773 | georg.brandl | 2010-03-07 22:32:06 +0100 (So, 07 Mär 2010) | 1 line
#8044: document Py_{Enter,Leave}RecursiveCall functions.
........
r78802 | georg.brandl | 2010-03-08 17:28:40 +0100 (Mo, 08 Mär 2010) | 1 line
Fix typo.
........
r78922 | georg.brandl | 2010-03-13 14:41:58 +0100 (Sa, 13 Mär 2010) | 1 line
Update for new download location.
........
r78952 | georg.brandl | 2010-03-14 10:55:08 +0100 (So, 14 Mär 2010) | 1 line
#8137: add iso-8859-16 to the standard encodings table.
........
2010-03-14 07:56:14 -03:00
|
|
|
|
2013-08-01 16:12:45 -03:00
|
|
|
Properly implementing :c:member:`~PyTypeObject.tp_repr` for container types requires
|
2010-12-17 12:31:32 -04:00
|
|
|
special recursion handling. In addition to protecting the stack,
|
2013-08-01 16:12:45 -03:00
|
|
|
:c:member:`~PyTypeObject.tp_repr` also needs to track objects to prevent cycles. The
|
2010-12-17 12:31:32 -04:00
|
|
|
following two functions facilitate this functionality. Effectively,
|
|
|
|
these are the C equivalent to :func:`reprlib.recursive_repr`.
|
|
|
|
|
2010-12-17 18:28:07 -04:00
|
|
|
.. c:function:: int Py_ReprEnter(PyObject *object)
|
2010-12-17 12:31:32 -04:00
|
|
|
|
2013-08-01 16:12:45 -03:00
|
|
|
Called at the beginning of the :c:member:`~PyTypeObject.tp_repr` implementation to
|
2010-12-17 12:31:32 -04:00
|
|
|
detect cycles.
|
|
|
|
|
|
|
|
If the object has already been processed, the function returns a
|
2013-08-01 16:12:45 -03:00
|
|
|
positive integer. In that case the :c:member:`~PyTypeObject.tp_repr` implementation
|
2010-12-17 12:31:32 -04:00
|
|
|
should return a string object indicating a cycle. As examples,
|
|
|
|
:class:`dict` objects return ``{...}`` and :class:`list` objects
|
|
|
|
return ``[...]``.
|
|
|
|
|
|
|
|
The function will return a negative integer if the recursion limit
|
2013-08-01 16:12:45 -03:00
|
|
|
is reached. In that case the :c:member:`~PyTypeObject.tp_repr` implementation should
|
2010-12-17 12:31:32 -04:00
|
|
|
typically return ``NULL``.
|
|
|
|
|
2013-08-01 16:12:45 -03:00
|
|
|
Otherwise, the function returns zero and the :c:member:`~PyTypeObject.tp_repr`
|
2010-12-17 12:31:32 -04:00
|
|
|
implementation can continue normally.
|
|
|
|
|
|
|
|
.. c:function:: void Py_ReprLeave(PyObject *object)
|
|
|
|
|
2010-12-17 18:28:07 -04:00
|
|
|
Ends a :c:func:`Py_ReprEnter`. Must be called once for each
|
|
|
|
invocation of :c:func:`Py_ReprEnter` that returns zero.
|
2010-12-17 12:31:32 -04:00
|
|
|
|
Merged revisions 78760,78771-78773,78802,78922,78952 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r78760 | georg.brandl | 2010-03-07 16:23:59 +0100 (So, 07 Mär 2010) | 1 line
#5341: more built-in vs builtin fixes.
........
r78771 | georg.brandl | 2010-03-07 21:58:31 +0100 (So, 07 Mär 2010) | 1 line
#8085: The function is called PyObject_NewVar, not PyObject_VarNew.
........
r78772 | georg.brandl | 2010-03-07 22:12:28 +0100 (So, 07 Mär 2010) | 1 line
#8039: document conditional expressions better, giving them their own section.
........
r78773 | georg.brandl | 2010-03-07 22:32:06 +0100 (So, 07 Mär 2010) | 1 line
#8044: document Py_{Enter,Leave}RecursiveCall functions.
........
r78802 | georg.brandl | 2010-03-08 17:28:40 +0100 (Mo, 08 Mär 2010) | 1 line
Fix typo.
........
r78922 | georg.brandl | 2010-03-13 14:41:58 +0100 (Sa, 13 Mär 2010) | 1 line
Update for new download location.
........
r78952 | georg.brandl | 2010-03-14 10:55:08 +0100 (So, 14 Mär 2010) | 1 line
#8137: add iso-8859-16 to the standard encodings table.
........
2010-03-14 07:56:14 -03:00
|
|
|
|
2007-08-15 11:28:22 -03:00
|
|
|
.. _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
|
2010-10-06 07:11:56 -03:00
|
|
|
:c:type:`PyObject\*`; they are all class objects. For completeness, here are all
|
2007-08-15 11:28:22 -03:00
|
|
|
the variables:
|
|
|
|
|
2017-04-02 07:45:40 -03:00
|
|
|
.. index::
|
|
|
|
single: PyExc_BaseException
|
|
|
|
single: PyExc_Exception
|
|
|
|
single: PyExc_ArithmeticError
|
|
|
|
single: PyExc_AssertionError
|
|
|
|
single: PyExc_AttributeError
|
|
|
|
single: PyExc_BlockingIOError
|
|
|
|
single: PyExc_BrokenPipeError
|
|
|
|
single: PyExc_BufferError
|
|
|
|
single: PyExc_ChildProcessError
|
|
|
|
single: PyExc_ConnectionAbortedError
|
|
|
|
single: PyExc_ConnectionError
|
|
|
|
single: PyExc_ConnectionRefusedError
|
|
|
|
single: PyExc_ConnectionResetError
|
|
|
|
single: PyExc_EOFError
|
|
|
|
single: PyExc_FileExistsError
|
|
|
|
single: PyExc_FileNotFoundError
|
|
|
|
single: PyExc_FloatingPointError
|
|
|
|
single: PyExc_GeneratorExit
|
|
|
|
single: PyExc_ImportError
|
|
|
|
single: PyExc_IndentationError
|
|
|
|
single: PyExc_IndexError
|
|
|
|
single: PyExc_InterruptedError
|
|
|
|
single: PyExc_IsADirectoryError
|
|
|
|
single: PyExc_KeyError
|
|
|
|
single: PyExc_KeyboardInterrupt
|
|
|
|
single: PyExc_LookupError
|
|
|
|
single: PyExc_MemoryError
|
|
|
|
single: PyExc_ModuleNotFoundError
|
|
|
|
single: PyExc_NameError
|
|
|
|
single: PyExc_NotADirectoryError
|
|
|
|
single: PyExc_NotImplementedError
|
|
|
|
single: PyExc_OSError
|
|
|
|
single: PyExc_OverflowError
|
|
|
|
single: PyExc_PermissionError
|
|
|
|
single: PyExc_ProcessLookupError
|
|
|
|
single: PyExc_RecursionError
|
|
|
|
single: PyExc_ReferenceError
|
|
|
|
single: PyExc_RuntimeError
|
|
|
|
single: PyExc_StopAsyncIteration
|
|
|
|
single: PyExc_StopIteration
|
|
|
|
single: PyExc_SyntaxError
|
|
|
|
single: PyExc_SystemError
|
|
|
|
single: PyExc_SystemExit
|
|
|
|
single: PyExc_TabError
|
|
|
|
single: PyExc_TimeoutError
|
|
|
|
single: PyExc_TypeError
|
|
|
|
single: PyExc_UnboundLocalError
|
|
|
|
single: PyExc_UnicodeDecodeError
|
|
|
|
single: PyExc_UnicodeEncodeError
|
|
|
|
single: PyExc_UnicodeError
|
|
|
|
single: PyExc_UnicodeTranslateError
|
|
|
|
single: PyExc_ValueError
|
|
|
|
single: PyExc_ZeroDivisionError
|
|
|
|
|
2011-10-12 13:28:01 -03:00
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
|
|
|
| C Name | Python Name | Notes |
|
|
|
|
+=========================================+=================================+==========+
|
|
|
|
| :c:data:`PyExc_BaseException` | :exc:`BaseException` | \(1) |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_Exception` | :exc:`Exception` | \(1) |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_ArithmeticError` | :exc:`ArithmeticError` | \(1) |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_AssertionError` | :exc:`AssertionError` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_AttributeError` | :exc:`AttributeError` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_BlockingIOError` | :exc:`BlockingIOError` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_BrokenPipeError` | :exc:`BrokenPipeError` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
2017-04-02 07:45:40 -03:00
|
|
|
| :c:data:`PyExc_BufferError` | :exc:`BufferError` | |
|
2011-10-12 13:28:01 -03:00
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
2017-04-02 07:45:40 -03:00
|
|
|
| :c:data:`PyExc_ChildProcessError` | :exc:`ChildProcessError` | |
|
2011-10-12 13:28:01 -03:00
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_ConnectionAbortedError` | :exc:`ConnectionAbortedError` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
2017-04-02 07:45:40 -03:00
|
|
|
| :c:data:`PyExc_ConnectionError` | :exc:`ConnectionError` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
2011-10-12 13:28:01 -03:00
|
|
|
| :c:data:`PyExc_ConnectionRefusedError` | :exc:`ConnectionRefusedError` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_ConnectionResetError` | :exc:`ConnectionResetError` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
2017-04-02 07:45:40 -03:00
|
|
|
| :c:data:`PyExc_EOFError` | :exc:`EOFError` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
2011-10-12 13:28:01 -03:00
|
|
|
| :c:data:`PyExc_FileExistsError` | :exc:`FileExistsError` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_FileNotFoundError` | :exc:`FileNotFoundError` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_FloatingPointError` | :exc:`FloatingPointError` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
2017-04-02 07:45:40 -03:00
|
|
|
| :c:data:`PyExc_GeneratorExit` | :exc:`GeneratorExit` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
2011-10-12 13:28:01 -03:00
|
|
|
| :c:data:`PyExc_ImportError` | :exc:`ImportError` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
2017-04-02 07:45:40 -03:00
|
|
|
| :c:data:`PyExc_IndentationError` | :exc:`IndentationError` | |
|
2016-09-07 19:42:32 -03:00
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
2011-10-12 13:28:01 -03:00
|
|
|
| :c:data:`PyExc_IndexError` | :exc:`IndexError` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_InterruptedError` | :exc:`InterruptedError` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_IsADirectoryError` | :exc:`IsADirectoryError` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_KeyError` | :exc:`KeyError` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_KeyboardInterrupt` | :exc:`KeyboardInterrupt` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
2017-04-02 07:45:40 -03:00
|
|
|
| :c:data:`PyExc_LookupError` | :exc:`LookupError` | \(1) |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
2011-10-12 13:28:01 -03:00
|
|
|
| :c:data:`PyExc_MemoryError` | :exc:`MemoryError` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
2017-04-02 07:45:40 -03:00
|
|
|
| :c:data:`PyExc_ModuleNotFoundError` | :exc:`ModuleNotFoundError` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
2011-10-12 13:28:01 -03:00
|
|
|
| :c:data:`PyExc_NameError` | :exc:`NameError` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_NotADirectoryError` | :exc:`NotADirectoryError` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_NotImplementedError` | :exc:`NotImplementedError` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_OSError` | :exc:`OSError` | \(1) |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_OverflowError` | :exc:`OverflowError` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_PermissionError` | :exc:`PermissionError` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_ProcessLookupError` | :exc:`ProcessLookupError` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
2015-07-03 02:04:23 -03:00
|
|
|
| :c:data:`PyExc_RecursionError` | :exc:`RecursionError` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
2011-10-12 13:28:01 -03:00
|
|
|
| :c:data:`PyExc_ReferenceError` | :exc:`ReferenceError` | \(2) |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_RuntimeError` | :exc:`RuntimeError` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
2017-04-02 07:45:40 -03:00
|
|
|
| :c:data:`PyExc_StopAsyncIteration` | :exc:`StopAsyncIteration` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_StopIteration` | :exc:`StopIteration` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
2011-10-12 13:28:01 -03:00
|
|
|
| :c:data:`PyExc_SyntaxError` | :exc:`SyntaxError` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_SystemError` | :exc:`SystemError` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_SystemExit` | :exc:`SystemExit` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
2017-04-02 07:45:40 -03:00
|
|
|
| :c:data:`PyExc_TabError` | :exc:`TabError` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_TimeoutError` | :exc:`TimeoutError` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
2011-10-12 13:28:01 -03:00
|
|
|
| :c:data:`PyExc_TypeError` | :exc:`TypeError` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
2017-04-02 07:45:40 -03:00
|
|
|
| :c:data:`PyExc_UnboundLocalError` | :exc:`UnboundLocalError` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_UnicodeDecodeError` | :exc:`UnicodeDecodeError` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_UnicodeEncodeError` | :exc:`UnicodeEncodeError` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_UnicodeError` | :exc:`UnicodeError` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_UnicodeTranslateError` | :exc:`UnicodeTranslateError` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
2011-10-12 13:28:01 -03:00
|
|
|
| :c:data:`PyExc_ValueError` | :exc:`ValueError` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_ZeroDivisionError` | :exc:`ZeroDivisionError` | |
|
|
|
|
+-----------------------------------------+---------------------------------+----------+
|
|
|
|
|
|
|
|
.. versionadded:: 3.3
|
|
|
|
:c:data:`PyExc_BlockingIOError`, :c:data:`PyExc_BrokenPipeError`,
|
|
|
|
:c:data:`PyExc_ChildProcessError`, :c:data:`PyExc_ConnectionError`,
|
|
|
|
:c:data:`PyExc_ConnectionAbortedError`, :c:data:`PyExc_ConnectionRefusedError`,
|
|
|
|
:c:data:`PyExc_ConnectionResetError`, :c:data:`PyExc_FileExistsError`,
|
|
|
|
:c:data:`PyExc_FileNotFoundError`, :c:data:`PyExc_InterruptedError`,
|
|
|
|
:c:data:`PyExc_IsADirectoryError`, :c:data:`PyExc_NotADirectoryError`,
|
|
|
|
:c:data:`PyExc_PermissionError`, :c:data:`PyExc_ProcessLookupError`
|
|
|
|
and :c:data:`PyExc_TimeoutError` were introduced following :pep:`3151`.
|
|
|
|
|
2015-07-03 02:04:23 -03:00
|
|
|
.. versionadded:: 3.5
|
2017-04-02 07:45:40 -03:00
|
|
|
:c:data:`PyExc_StopAsyncIteration` and :c:data:`PyExc_RecursionError`.
|
2015-07-03 02:04:23 -03:00
|
|
|
|
2017-04-02 07:45:40 -03:00
|
|
|
.. versionadded:: 3.6
|
|
|
|
:c:data:`PyExc_ModuleNotFoundError`.
|
2011-10-12 13:28:01 -03:00
|
|
|
|
|
|
|
These are compatibility aliases to :c:data:`PyExc_OSError`:
|
|
|
|
|
2017-04-02 07:45:40 -03:00
|
|
|
.. index::
|
|
|
|
single: PyExc_EnvironmentError
|
|
|
|
single: PyExc_IOError
|
|
|
|
single: PyExc_WindowsError
|
|
|
|
|
2011-10-12 13:28:01 -03:00
|
|
|
+-------------------------------------+----------+
|
|
|
|
| C Name | Notes |
|
|
|
|
+=====================================+==========+
|
|
|
|
| :c:data:`PyExc_EnvironmentError` | |
|
|
|
|
+-------------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_IOError` | |
|
|
|
|
+-------------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_WindowsError` | \(3) |
|
|
|
|
+-------------------------------------+----------+
|
|
|
|
|
|
|
|
.. versionchanged:: 3.3
|
|
|
|
These aliases used to be separate exception types.
|
|
|
|
|
2007-08-15 11:28:22 -03:00
|
|
|
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.
|
2017-04-02 07:45:40 -03:00
|
|
|
|
2017-05-19 17:37:57 -03:00
|
|
|
.. _standardwarningcategories:
|
2017-04-14 23:06:02 -03:00
|
|
|
|
|
|
|
Standard Warning Categories
|
|
|
|
===========================
|
2017-04-02 07:45:40 -03:00
|
|
|
|
|
|
|
All standard Python warning categories are available as global variables whose
|
|
|
|
names are ``PyExc_`` followed by the Python exception name. These have the type
|
|
|
|
:c:type:`PyObject\*`; they are all class objects. For completeness, here are all
|
|
|
|
the variables:
|
|
|
|
|
|
|
|
.. index::
|
|
|
|
single: PyExc_Warning
|
|
|
|
single: PyExc_BytesWarning
|
2017-05-19 17:37:57 -03:00
|
|
|
single: PyExc_DeprecationWarning
|
2017-04-02 07:45:40 -03:00
|
|
|
single: PyExc_FutureWarning
|
|
|
|
single: PyExc_ImportWarning
|
|
|
|
single: PyExc_PendingDeprecationWarning
|
|
|
|
single: PyExc_ResourceWarning
|
|
|
|
single: PyExc_RuntimeWarning
|
|
|
|
single: PyExc_SyntaxWarning
|
|
|
|
single: PyExc_UnicodeWarning
|
|
|
|
single: PyExc_UserWarning
|
|
|
|
|
|
|
|
+------------------------------------------+---------------------------------+----------+
|
|
|
|
| C Name | Python Name | Notes |
|
|
|
|
+==========================================+=================================+==========+
|
|
|
|
| :c:data:`PyExc_Warning` | :exc:`Warning` | \(1) |
|
|
|
|
+------------------------------------------+---------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_BytesWarning` | :exc:`BytesWarning` | |
|
|
|
|
+------------------------------------------+---------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_DeprecationWarning` | :exc:`DeprecationWarning` | |
|
|
|
|
+------------------------------------------+---------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_FutureWarning` | :exc:`FutureWarning` | |
|
|
|
|
+------------------------------------------+---------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_ImportWarning` | :exc:`ImportWarning` | |
|
|
|
|
+------------------------------------------+---------------------------------+----------+
|
2017-05-19 17:37:57 -03:00
|
|
|
| :c:data:`PyExc_PendingDeprecationWarning`| :exc:`PendingDeprecationWarning`| |
|
2017-04-02 07:45:40 -03:00
|
|
|
+------------------------------------------+---------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_ResourceWarning` | :exc:`ResourceWarning` | |
|
|
|
|
+------------------------------------------+---------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_RuntimeWarning` | :exc:`RuntimeWarning` | |
|
|
|
|
+------------------------------------------+---------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_SyntaxWarning` | :exc:`SyntaxWarning` | |
|
|
|
|
+------------------------------------------+---------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_UnicodeWarning` | :exc:`UnicodeWarning` | |
|
|
|
|
+------------------------------------------+---------------------------------+----------+
|
|
|
|
| :c:data:`PyExc_UserWarning` | :exc:`UserWarning` | |
|
|
|
|
+------------------------------------------+---------------------------------+----------+
|
|
|
|
|
|
|
|
.. versionadded:: 3.2
|
|
|
|
:c:data:`PyExc_ResourceWarning`.
|
|
|
|
|
|
|
|
Notes:
|
|
|
|
|
|
|
|
(1)
|
|
|
|
This is a base class for other standard warning categories.
|