bpo-35461: Document C API functions which suppress exceptions. (GH-11119)
diff --git a/Doc/c-api/buffer.rst b/Doc/c-api/buffer.rst
index 33abb5b..c7c1e3c 100644
--- a/Doc/c-api/buffer.rst
+++ b/Doc/c-api/buffer.rst
@@ -429,7 +429,7 @@
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 @@
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 dfe3d43..c55f199 100644
--- a/Doc/c-api/codec.rst
+++ b/Doc/c-api/codec.rst
@@ -13,7 +13,7 @@
.. 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 b7225fa..4e55c1a 100644
--- a/Doc/c-api/dict.rst
+++ b/Doc/c-api/dict.rst
@@ -95,6 +95,10 @@
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 @@
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 b8eaadb..e37dec9 100644
--- a/Doc/c-api/mapping.rst
+++ b/Doc/c-api/mapping.rst
@@ -60,6 +60,10 @@
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 @@
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 3c7605a..296b21c 100644
--- a/Doc/c-api/number.rst
+++ b/Doc/c-api/number.rst
@@ -280,3 +280,4 @@
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 e7f4fde..9ad7c57 100644
--- a/Doc/c-api/objbuffer.rst
+++ b/Doc/c-api/objbuffer.rst
@@ -39,7 +39,11 @@
.. 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 f0b2005..a64ff2e 100644
--- a/Doc/c-api/object.rst
+++ b/Doc/c-api/object.rst
@@ -33,6 +33,10 @@
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 @@
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)