Fix misunderstanding about PyDict_GetItemWithError() in containers_and_refcounts.rst.

Author: paulross

doc/sphinx/source/containers_and_refcounts.rst

@@ -1534,7 +1534,6 @@ This section describes other dictionary APIs that are simple to describe and hav
 
 .. index::
     single: Dictionary; PyDict_GetItemWithError()
-    pair: Documentation Lacunae; PyDict_GetItemWithError()
 
 .. _chapter_containers_and_refcounts.dictionaries.pydict_getitemwitherror:
 
@@ -1550,34 +1549,12 @@ The C signature is:
 
     PyObject *PyDict_GetItemWithError(PyObject *p, PyObject *key);
 
-.. warning::
-
-    This function is incorrectly documented as it fails to set an exception with a missing key as this code
-    demonstrates:
-
-    .. code-block:: c
+Currently, the only failure mode is if the first argument is not a dictionary.
 
-        assert(!PyErr_Occurred());
-        PyObject *container = PyDict_New();
-        assert(container && Py_REFCNT(container) == 1);
-
-        PyObject *key = new_unique_string(__FUNCTION__, NULL);
-
-        assert(!PyErr_Occurred());
-        PyObject *get_item = PyDict_GetItemWithError(container, key);
-        /* This is the failure point. An exception should have been set with
-         * an absent key but it isn't.  */
-        assert(!PyErr_Occurred());
-
-        assert(get_item == NULL);
-
-        Py_DECREF(container);
-        Py_DECREF(key);
-
-    For code and tests see:
+For code and tests see:
 
-    * C, in ``src/cpy/Containers/DebugContainers.c``:
-        * ``dbg_PyDict_GetItemWithError_fails()``
+* C, in ``src/cpy/Containers/DebugContainers.c``:
+    * ``dbg_PyDict_GetItemWithError_fails()``
 
 .. index::
     single: Dictionary; PyDict_DelItem()

src/cpy/Containers/DebugContainers.c

@@ -2220,9 +2220,26 @@ void dbg_PyDict_GetItemWithError_fails(void) {
     assert(!PyErr_Occurred());
     get_item = PyDict_GetItemWithError(container, key);
     assert(get_item == NULL);
-    /* This is the failure point. An exception should have been set with an absent key but it isn't.  */
+    /* This is correct, the key is absent. */
     assert(!PyErr_Occurred());
 
+    /* So what error conditinos are handled?
+     * Firstly this will segfault. */
+#if 0
+    assert(!PyErr_Occurred());
+    get_item = PyDict_GetItemWithError(container, NULL);
+    assert(get_item == NULL);
+    assert(PyErr_Occurred());
+#endif
+
+    PyObject *new_container = PyList_New(0);
+    assert(!PyErr_Occurred());
+    get_item = PyDict_GetItemWithError(new_container, key);
+    assert(get_item == NULL);
+    assert(PyErr_Occurred());
+    PyErr_Print(); /* Clears exception. */
+    Py_DECREF(new_container);
+
     Py_DECREF(container);
     ref_count = Py_REFCNT(key);
     assert(ref_count == 1);