From 19d6511b0b8f3f74e668ae32ccef89bcbf1a8a62 Mon Sep 17 00:00:00 2001
From: "Gregory P. Smith" <greg@krypto.org>
Date: Sat, 24 Jun 2023 16:29:26 -0700
Subject: [PATCH] gh-106033: [docs] Improve C API GetItem & HasAttr notes.
 (#106047)

Use a note:: tag so that these dict and object API deficiencies show up clearly.

A caution:: tag was considered, but our current python docs rendering doesn't do much with that (no box or color change).  warning:: seemed too extreme.  note looks good.
---
 Doc/c-api/dict.rst   | 19 ++++++++++++-------
 Doc/c-api/object.rst | 18 +++++++++++-------
 2 files changed, 23 insertions(+), 14 deletions(-)

diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst
index 0ca8ad624b2..bd0c36a217e 100644
--- a/Doc/c-api/dict.rst
+++ b/Doc/c-api/dict.rst
@@ -98,9 +98,11 @@ 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.
+   .. note::
+
+      Exceptions that occur while this calls :meth:`~object.__hash__` and
+      :meth:`~object.__eq__` methods are silently ignored.
+      Prefer the :c:func:`PyDict_GetItemWithError` function instead.
 
    .. versionchanged:: 3.10
       Calling this API without :term:`GIL` held had been allowed for historical
@@ -120,10 +122,13 @@ Dictionary Objects
    This is the same as :c:func:`PyDict_GetItem`, but *key* is specified as a
    :c:expr:`const char*`, rather than a :c:expr:`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.
+   .. note::
+
+      Exceptions that occur while this calls :meth:`~object.__hash__` and
+      :meth:`~object.__eq__` methods or while creating the temporary :class:`str`
+      object are silently ignored.
+      Prefer using the :c:func:`PyDict_GetItemWithError` function with your own
+      :c:func:`PyUnicode_FromString` *key* instead.
 
 
 .. c:function:: PyObject* PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *defaultobj)
diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst
index a25ff244c9f..22e7458013f 100644
--- a/Doc/c-api/object.rst
+++ b/Doc/c-api/object.rst
@@ -33,9 +33,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 will get suppressed.
-   To get error reporting use :c:func:`PyObject_GetAttr()` instead.
+   .. note::
+
+      Exceptions that occur when this calls :meth:`~object.__getattr__` and
+      :meth:`~object.__getattribute__` methods are silently ignored.
+      For proper error handling, use :c:func:`PyObject_GetAttr` instead.
 
 
 .. c:function:: int PyObject_HasAttrString(PyObject *o, const char *attr_name)
@@ -44,10 +46,12 @@ 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.
+   .. note::
+
+      Exceptions that occur when this calls :meth:`~object.__getattr__` and
+      :meth:`~object.__getattribute__` methods or while creating the temporary :class:`str`
+      object are silently ignored.
+      For proper error handling, use :c:func:`PyObject_GetAttrString` instead.
 
 
 .. c:function:: PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name)