[Python-checkins] bpo-35461: Document C API functions which suppress exceptions. (GH-11119)

[Miss Islington (bot)]

https://github.com/python/cpython/commit/f265afec1c2a5acb8cb9c9ddb6cd45f7465c6eb5
commit: f265afec1c2a5acb8cb9c9ddb6cd45f7465c6eb5
branch: 3.7
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: GitHub <noreply at github.com>
date: 2018-12-18T12:24:39-08:00
summary:

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

(cherry picked from commit 3fcc1e08db6fb7e17acc4a8f63be3e42f52f094b)

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

files:
M Doc/c-api/buffer.rst
M Doc/c-api/codec.rst
M Doc/c-api/dict.rst
M Doc/c-api/mapping.rst
M Doc/c-api/number.rst
M Doc/c-api/objbuffer.rst
M Doc/c-api/object.rst

diff --git a/Doc/c-api/buffer.rst b/Doc/c-api/buffer.rst
index 33abb5bb94d9..c7c1e3cc745a 100644
--- 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 dfe3d436e5f4..c55f19970e12 100644
--- 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 b7225faf408c..4e55c1a977ce 100644
--- 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:`const 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 b8eaadbd702c..e37dec9949ab 100644
--- 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 3c7605a67fa2..296b21c132b7 100644
--- 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 e7f4fde00256..9ad7c571c4d8 100644
--- 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 f0b2005f2d12..a64ff2e6b58b 100644
--- 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)