Address Serhiy's new review

* Elaborate _PyErr_SetKeyError() comment to explain the usage of this
  function.
* Explain the purpopose of the KeyError(KeyError('arg')) test.
* Move the test to test_capi.test_exceptions.

Author: vstinner

Lib/test/test_capi/test_exceptions.py

@@ -108,6 +108,26 @@ def __del__(self):
             b'<string>:7: RuntimeWarning: Testing PyErr_WarnEx',
         ])
 
+    def test__pyerr_setkeyerror(self):
+        # Test _PyErr_SetKeyError()
+        _pyerr_setkeyerror = _testinternalcapi._pyerr_setkeyerror
+        for arg in (
+            "key",
+            # check that a tuple argument is not unpacked
+            (1, 2, 3),
+            # PyErr_SetObject(exc_type, exc_value) uses exc_value if it's
+            # already an exception, but _PyErr_SetKeyError() always creates a
+            # new KeyError.
+            KeyError('arg'),
+        ):
+            with self.subTest(arg=arg):
+                with self.assertRaises(KeyError) as cm:
+                    # Test calling _PyErr_SetKeyError() with an exception set
+                    # to check that the function overrides the current
+                    # exception.
+                    _pyerr_setkeyerror(arg)
+                self.assertEqual(cm.exception.args, (arg,))
+
 
 class Test_FatalError(unittest.TestCase):
 

Lib/test/test_capi/test_misc.py

@@ -928,23 +928,6 @@ def test_tp_bases_slot_none(self):
             _testcapi.create_heapctype_with_none_bases_slot
         )
 
-    def test__pyerr_setkeyerror(self):
-        # Test _PyErr_SetKeyError()
-        _pyerr_setkeyerror = _testinternalcapi._pyerr_setkeyerror
-        for arg in (
-            "key",
-            # check that a tuple argument is not unpacked
-            (1, 2, 3),
-            KeyError('arg'),
-        ):
-            with self.subTest(arg=arg):
-                with self.assertRaises(KeyError) as cm:
-                    # Test calling _PyErr_SetKeyError() with an exception set
-                    # to check that the function overrides the current
-                    # exception.
-                    _pyerr_setkeyerror(arg)
-                self.assertEqual(cm.exception.args, (arg,))
-
 
 @requires_limited_api
 class TestHeapTypeRelative(unittest.TestCase):

Python/errors.c

@@ -246,7 +246,11 @@ PyErr_SetObject(PyObject *exception, PyObject *value)
     _PyErr_SetObject(tstate, exception, value);
 }
 
-/* Set a key error with the specified argument.
+/* Set a key error with the specified argument. This function should be used to
+ * raise a KeyError with an argument instead of PyErr_SetObject(PyExc_KeyError,
+ * arg) which has a special behavior. PyErr_SetObject() unpacks arg if it's a
+ * tuple, and it uses arg instead of creating a new exception if arg is an
+ * exception.
  *
  * If an exception is already set, override the exception. */
 void