[3.15] gh-148829: Add PySentinel_CheckExact() (GH-149725)

Doc/c-api/sentinel.rst

@@ -14,8 +14,20 @@ Sentinel objects
 
 .. c:function:: int PySentinel_Check(PyObject *o)
 
-   Return true if *o* is a :class:`sentinel` object.  The :class:`sentinel` type
-   does not allow subclasses, so this check is exact.
+   Return true if *o* is a :class:`sentinel` object or a subtype.
+   The :class:`sentinel` type does not currently allow subclasses,
+   so this check is exact.
+   Future Python versions may choose to allow subtyping.
+   This function always succeeds.
+
+   .. versionadded:: 3.15
+
+.. c:function:: int PySentinel_CheckExact(PyObject *o)
+
+   Return true if *o* is a :class:`sentinel` object, but not a subtype.
+   The :class:`sentinel` type does not currently allow subclasses.
+   Future Python versions may choose to allow subtyping.
+   This function always succeeds.
 
    .. versionadded:: 3.15
 

Include/cpython/sentinelobject.h

@@ -9,7 +9,10 @@ extern "C" {
 
 PyAPI_DATA(PyTypeObject) PySentinel_Type;
 
-#define PySentinel_Check(op) Py_IS_TYPE((op), &PySentinel_Type)
+#define PySentinel_CheckExact(op) Py_IS_TYPE((op), &PySentinel_Type)
+
+/* Alias as long as subclasses are not allowed. */
+#define PySentinel_Check(op) PySentinel_CheckExact(op)
 
 PyAPI_FUNC(PyObject *) PySentinel_New(
     const char *name,

Lib/test/test_capi/test_object.py

@@ -71,6 +71,8 @@ def test_pysentinel_new(self):
         self.assertIs(type(marker), sentinel)
         self.assertTrue(_testcapi.pysentinel_check(marker))
         self.assertFalse(_testcapi.pysentinel_check(object()))
+        self.assertTrue(_testcapi.pysentinel_checkexact(marker))
+        self.assertFalse(_testcapi.pysentinel_checkexact(object()))
         self.assertEqual(marker.__name__, "CAPI_SENTINEL")
         self.assertEqual(marker.__module__, __name__)
         self.assertEqual(repr(marker), "CAPI_SENTINEL")

Misc/NEWS.d/next/C_API/2026-05-12-16-47-21.gh-issue-149725.HZLBTZ.rst

@@ -0,0 +1,2 @@
+Add :c:func:`PySentinel_CheckExact` for exact :class:`sentinel` type tests
+to accompany the existing :c:func:`PySentinel_Check`.

Modules/_testcapi/object.c

@@ -572,6 +572,12 @@ pysentinel_check(PyObject *self, PyObject *obj)
     return PyBool_FromLong(PySentinel_Check(obj));
 }
 
+static PyObject *
+pysentinel_checkexact(PyObject *self, PyObject *obj)
+{
+    return PyBool_FromLong(PySentinel_CheckExact(obj));
+}
+
 
 static PyMethodDef test_methods[] = {
     {"call_pyobject_print", call_pyobject_print, METH_VARARGS},
@@ -604,6 +610,7 @@ static PyMethodDef test_methods[] = {
     {"pyobject_dump", pyobject_dump, METH_VARARGS},
     {"pysentinel_new", pysentinel_new, METH_VARARGS},
     {"pysentinel_check", pysentinel_check, METH_O},
+    {"pysentinel_checkexact", pysentinel_checkexact, METH_O},
     {NULL},
 };