gh-139847: Add PyType_Lookup() function

Author: vstinner

Doc/c-api/type.rst

@@ -306,6 +306,21 @@ Type Objects
 
    .. versionadded:: 3.14
 
+
+.. c:function:: int PyType_Lookup(PyTypeObject *type, PyObject *name, PyObject **attr)
+
+   Look for a type attribute through the type
+   :term:`MRO <method resolution order>`.
+
+   *name* must be a :class:`str`.
+
+   * If found, set *\*attr* to a strong reference and return ``1``.
+   * If not found, set *\*attr* to ``NULL`` and return ``0``.
+   * On error, set an exception and return ``-1``.
+
+   .. versionadded:: next
+
+
 .. c:function:: int PyUnstable_Type_AssignVersionTag(PyTypeObject *type)
 
    Attempt to assign a version tag to the given type.

Doc/deprecations/c-api-pending-removal-in-3.19.rst

@@ -0,0 +1,13 @@
+Pending removal in Python 3.19
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* The following private functions are deprecated
+  and planned for removal in Python 3.19:
+
+  * :c:func:`!_PyType_Lookup`: use :c:func:`PyType_Lookup`.
+  * :c:func:`!_PyType_LookupRef`: use :c:func:`PyType_Lookup`.
+
+  The `pythoncapi-compat project
+  <https://github.com/python/pythoncapi-compat/>`__ can be used to get
+  these new public functions on Python 3.14 and older.
+  (Contributed by Victor Stinner in :gh:`128863`.)

Doc/whatsnew/3.13.rst

@@ -2554,6 +2554,8 @@ Deprecated C APIs
 
 .. include:: ../deprecations/c-api-pending-removal-in-3.18.rst
 
+.. include:: ../deprecations/c-api-pending-removal-in-3.19.rst
+
 .. include:: ../deprecations/c-api-pending-removal-in-future.rst
 
 .. _pythoncapi-compat project: https://github.com/python/pythoncapi-compat/

Doc/whatsnew/3.14.rst

@@ -3079,6 +3079,8 @@ Deprecated C APIs
 
 .. include:: ../deprecations/c-api-pending-removal-in-3.18.rst
 
+.. include:: ../deprecations/c-api-pending-removal-in-3.19.rst
+
 .. include:: ../deprecations/c-api-pending-removal-in-future.rst
 
 

Doc/whatsnew/3.15.rst

@@ -852,6 +852,10 @@ New features
 
   (Contributed by Victor Stinner in :gh:`129813`.)
 
+* Add :c:func:`PyType_Lookup` function to look for a type attribute through the
+  type :term:`MRO <method resolution order>`.
+  (Contributed by Victor Stinner in :gh:`139847`.)
+
 
 Porting to Python 3.15
 ----------------------
@@ -869,6 +873,9 @@ Porting to Python 3.15
 
 * Private functions promoted to public C APIs:
 
+  * :c:func:`!_PyType_Lookup`: use :c:func:`PyType_Lookup`.
+  * :c:func:`!_PyType_LookupRef`: use :c:func:`PyType_Lookup`.
+
   The |pythoncapi_compat_project| can be used to get most of these new
   functions on Python 3.14 and older.
 
@@ -915,6 +922,14 @@ Deprecated C APIs
 
 .. Add C API deprecations above alphabetically, not here at the end.
 
+.. include:: ../deprecations/c-api-pending-removal-in-3.16.rst
+
+.. include:: ../deprecations/c-api-pending-removal-in-3.18.rst
+
+.. include:: ../deprecations/c-api-pending-removal-in-3.19.rst
+
+.. include:: ../deprecations/c-api-pending-removal-in-future.rst
+
 Removed C APIs
 --------------
 

Include/cpython/object.h

@@ -252,7 +252,7 @@ struct _specialization_cache {
     // by the specialization machinery, and are invalidated by PyType_Modified.
     // The rules for using them are as follows:
     // - If getitem is non-NULL, then it is the same Python function that
-    //   PyType_Lookup(cls, "__getitem__") would return.
+    //   _PyType_Lookup(cls, "__getitem__") would return.
     // - If getitem is NULL, then getitem_version is meaningless.
     // - If getitem->func_version == getitem_version, then getitem can be called
     //   with two positional arguments and no keyword arguments, and has neither
@@ -289,8 +289,16 @@ typedef struct _heaptypeobject {
 } PyHeapTypeObject;
 
 PyAPI_FUNC(const char *) _PyType_Name(PyTypeObject *);
-PyAPI_FUNC(PyObject *) _PyType_Lookup(PyTypeObject *, PyObject *);
-PyAPI_FUNC(PyObject *) _PyType_LookupRef(PyTypeObject *, PyObject *);
+PyAPI_FUNC(int) PyType_Lookup(
+    PyTypeObject *type,
+    PyObject *name,
+    PyObject **attr);
+_Py_DEPRECATED_EXTERNALLY(3.15) PyAPI_FUNC(PyObject *) _PyType_Lookup(
+    PyTypeObject *type,
+    PyObject *name);
+_Py_DEPRECATED_EXTERNALLY(3.15) PyAPI_FUNC(PyObject *) _PyType_LookupRef(
+    PyTypeObject *type,
+    PyObject *name);
 PyAPI_FUNC(PyObject *) PyType_GetDict(PyTypeObject *);
 
 PyAPI_FUNC(int) PyObject_Print(PyObject *, FILE *, int);

Lib/test/test_capi/test_type.py

@@ -274,3 +274,20 @@ def test_extension_managed_dict_type(self):
         obj.__dict__ = {'bar': 3}
         self.assertEqual(obj.__dict__, {'bar': 3})
         self.assertEqual(obj.bar, 3)
+
+    def test_type_lookup(self):
+        type_lookup = _testcapi.type_lookup
+
+        class Parent:
+            parent_attr = "parent"
+
+        class Child(Parent):
+            child_attr = "child"
+
+        self.assertEqual(type_lookup(Child, "parent_attr"), "parent")
+        self.assertEqual(type_lookup(Child, "child_attr"), "child")
+        self.assertEqual(type_lookup(Child, "xxx"), AttributeError)
+
+        # name parameter must be a str
+        self.assertRaises(TypeError, type_lookup, Child, b'name')
+        self.assertRaises(TypeError, type_lookup, Child, 123)

Misc/NEWS.d/next/C_API/2025-10-09-15-43-15.gh-issue-139847.dZb1v_.rst

@@ -0,0 +1,2 @@
+Add :c:func:`PyType_Lookup` function to look for a type attribute through
+the type :term:`MRO <method resolution order>`. Patch by Victor Stinner.

Misc/NEWS.d/next/C_API/2025-10-09-15-44-22.gh-issue-139847.-1_Pnx.rst

@@ -0,0 +1,3 @@
+Deprecate the private functions :c:func:`!_PyType_Lookup` and
+:c:func:`!_PyType_LookupRef`: use the new public :c:func:`PyType_LookupRef`
+function instead. Patch by Victor Stinner.

Modules/_testcapi/gc.c

@@ -98,8 +98,14 @@ slot_tp_del(PyObject *self)
         PyErr_SetRaisedException(exc);
         return;
     }
+
     /* Execute __del__ method, if any. */
-    del = _PyType_LookupRef(Py_TYPE(self), tp_del);
+    if (PyType_Lookup(Py_TYPE(self), tp_del, &del) < 0) {
+        Py_DECREF(tp_del);
+        PyErr_FormatUnraisable("Exception ignored while deallocating");
+        PyErr_SetRaisedException(exc);
+        return;
+    }
     Py_DECREF(tp_del);
     if (del != NULL) {
         res = PyObject_CallOneArg(del, self);