bpo-35461: Document C API functions which suppress exceptions. (GH-11119) (GH-11210)

(cherry picked from commit 3fcc1e08db6fb7e17acc4a8f63be3e42f52f094b)

Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>

diff --git a/Doc/c-api/buffer.rst b/Doc/c-api/buffer.rst
index 33abb5bb94d9de29fc8c811ae23dc023a91f2535..c7c1e3cc745ac40555b71ee3e8ae464981243f3d 100644 (file)
--- a/Doc/c-api/buffer.rst
+++ b/Doc/c-api/buffer.rst
@@ -429,7 +429,7 @@ Buffer-related functions
 
    Return ``1`` if *obj* supports the buffer interface otherwise ``0``.  When ``1`` is
    returned, it doesn't guarantee that :c:func:`PyObject_GetBuffer` will
-   succeed.
+   succeed.  This function always succeeds.
 
 
 .. c:function:: int PyObject_GetBuffer(PyObject *exporter, Py_buffer *view, int flags)
@@ -470,7 +470,7 @@ Buffer-related functions
 
    Return ``1`` if the memory defined by the *view* is C-style (*order* is
    ``'C'``) or Fortran-style (*order* is ``'F'``) :term:`contiguous` or either one
-   (*order* is ``'A'``).  Return ``0`` otherwise.
+   (*order* is ``'A'``).  Return ``0`` otherwise.  This function always succeeds.
 
 
 .. c:function:: int PyBuffer_ToContiguous(void *buf, Py_buffer *src, Py_ssize_t len, char order)

diff --git a/Doc/c-api/codec.rst b/Doc/c-api/codec.rst
index dfe3d436e5f4b7cf60a899338eb714e33b8c4d33..c55f19970e125dccdcddaf06047d0450a6f55424 100644 (file)
--- a/Doc/c-api/codec.rst
+++ b/Doc/c-api/codec.rst
@@ -13,7 +13,7 @@ Codec registry and support functions
 .. c:function:: int PyCodec_KnownEncoding(const char *encoding)
 
    Return ``1`` or ``0`` depending on whether there is a registered codec for
-   the given *encoding*.
+   the given *encoding*.  This function always succeeds.
 
 .. c:function:: PyObject* PyCodec_Encode(PyObject *object, const char *encoding, const char *errors)
 

diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst
index cfa5e13b9feef8a21d16c6178be7b60771931a7b..68ca25ca548d60d2714a31c341ef1b33981e1256 100644 (file)
--- a/Doc/c-api/dict.rst
+++ b/Doc/c-api/dict.rst
@@ -95,6 +95,10 @@ Dictionary Objects
    Return the object from dictionary *p* which has a key *key*.  Return *NULL*
    if the key *key* is not present, but *without* setting an exception.
 
+   Note that exceptions which occur while calling :meth:`__hash__` and
+   :meth:`__eq__` methods will get suppressed.
+   To get error reporting use :c:func:`PyDict_GetItemWithError()` instead.
+
 
 .. c:function:: PyObject* PyDict_GetItemWithError(PyObject *p, PyObject *key)
 
@@ -109,6 +113,11 @@ Dictionary Objects
    This is the same as :c:func:`PyDict_GetItem`, but *key* is specified as a
    :c:type:`char\*`, rather than a :c:type:`PyObject\*`.
 
+   Note that exceptions which occur while calling :meth:`__hash__` and
+   :meth:`__eq__` methods and creating a temporary string object
+   will get suppressed.
+   To get error reporting use :c:func:`PyDict_GetItemWithError()` instead.
+
 
 .. c:function:: PyObject* PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *default)
 

diff --git a/Doc/c-api/mapping.rst b/Doc/c-api/mapping.rst
index c16fcf4439d4dac0c0eae375a7bf7a13d052d283..cb68ef82ca83448e07a76cf673976a8aabe684a2 100644 (file)
--- a/Doc/c-api/mapping.rst
+++ b/Doc/c-api/mapping.rst
@@ -60,6 +60,10 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and
    This is equivalent to the Python expression ``key in o``.
    This function always succeeds.
 
+   Note that exceptions which occur while calling the :meth:`__getitem__`
+   method will get suppressed.
+   To get error reporting use :c:func:`PyObject_GetItem()` instead.
+
 
 .. c:function:: int PyMapping_HasKeyString(PyObject *o, const char *key)
 
@@ -67,6 +71,10 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and
    This is equivalent to the Python expression ``key in o``.
    This function always succeeds.
 
+   Note that exceptions which occur while calling the :meth:`__getitem__`
+   method and creating a temporary string object will get suppressed.
+   To get error reporting use :c:func:`PyMapping_GetItemString()` instead.
+
 
 .. c:function:: PyObject* PyMapping_Keys(PyObject *o)
 

diff --git a/Doc/c-api/number.rst b/Doc/c-api/number.rst
index 3c7605a67fa226027594b0c6f1e57eb4ef21ad49..296b21c132b79a48f1ca8b37d4bd412653d091cc 100644 (file)
--- a/Doc/c-api/number.rst
+++ b/Doc/c-api/number.rst
@@ -280,3 +280,4 @@ Number Protocol
 
    Returns ``1`` if *o* is an index integer (has the nb_index slot of  the
    tp_as_number structure filled in), and ``0`` otherwise.
+   This function always succeeds.

diff --git a/Doc/c-api/objbuffer.rst b/Doc/c-api/objbuffer.rst
index e7f4fde00256db7bb993a406927d00a0f0f49a2a..9ad7c571c4d8c1aa091818097d68506a02f61369 100644 (file)
--- a/Doc/c-api/objbuffer.rst
+++ b/Doc/c-api/objbuffer.rst
@@ -39,7 +39,11 @@ an object, and :c:func:`PyBuffer_Release` when the buffer view can be released.
 .. c:function:: int PyObject_CheckReadBuffer(PyObject *o)
 
    Returns ``1`` if *o* supports the single-segment readable buffer interface.
-   Otherwise returns ``0``.
+   Otherwise returns ``0``.  This function always succeeds.
+
+   Note that this function tries to get and release a buffer, and exceptions
+   which occur while calling correspoding functions will get suppressed.
+   To get error reporting use :c:func:`PyObject_GetBuffer()` instead.
 
 
 .. c:function:: int PyObject_AsWriteBuffer(PyObject *obj, void **buffer, Py_ssize_t *buffer_len)

diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst
index 8692a2c14ca20f4fb4365e8f3c04b7161191f894..ea0aa8df31e6096aa9d0072814099eb2be6ee358 100644 (file)
--- a/Doc/c-api/object.rst
+++ b/Doc/c-api/object.rst
@@ -33,6 +33,10 @@ Object Protocol
    is equivalent to the Python expression ``hasattr(o, attr_name)``.  This function
    always succeeds.
 
+   Note that exceptions which occur while calling :meth:`__getattr__` and
+   :meth:`__getattribute__` methods will get suppressed.
+   To get error reporting use :c:func:`PyObject_GetAttr()` instead.
+
 
 .. c:function:: int PyObject_HasAttrString(PyObject *o, const char *attr_name)
 
@@ -40,6 +44,11 @@ Object Protocol
    is equivalent to the Python expression ``hasattr(o, attr_name)``.  This function
    always succeeds.
 
+   Note that exceptions which occur while calling :meth:`__getattr__` and
+   :meth:`__getattribute__` methods and creating a temporary string object
+   will get suppressed.
+   To get error reporting use :c:func:`PyObject_GetAttrString()` instead.
+
 
 .. c:function:: PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name)