1. expose _PyObject_LookupSpecial instead of _PyObject_LookupSpecialMethod;

2. raise AttributeError instead of returning None;
3. add optional `default` parameter, similar to `getattr`: lookup_special(object, name[, default])
4. There are different opinions on which module should the function be
   in. Leave it in `types` until there is consensus.

Author: tanloong

Doc/library/types.rst

@@ -521,41 +521,13 @@ Additional Utility Classes and Functions
 
    .. versionadded:: 3.4
 
-.. function:: lookup_special_method(obj, attr, /)
-
-     Lookup special method name ``attr`` on ``obj``.
-
-     Lookup method ``attr`` on ``obj`` without looking in the instance
-     dictionary. For methods defined in class ``__dict__`` or ``__slots__``, it
-     returns the unbound function (descriptor), not a bound method. The
-     caller is responsible for passing the object as the first argument when
-     calling it:
-
-     .. code-block:: python
-
-         >>> class A:
-         ...    def __enter__(self):
-         ...        return "A.__enter__"
-         ...
-         >>> class B:
-         ...    __slots__ = ("__enter__",)
-         ...    def __init__(self):
-         ...        def __enter__(self):
-         ...            return "B.__enter__"
-         ...        self.__enter__ = __enter__
-         ...
-         >>> a = A()
-         >>> b = B()
-         >>> enter_a = types.lookup_special_method(a, "__enter__")
-         >>> enter_b = types.lookup_special_method(b, "__enter__")
-         >>> enter_a(a)
-         'A.__enter__'
-         >>> enter_b(b)
-         'B.__enter__'
-
-     For other descriptors (property, etc.), it returns the result of the
-     descriptor's ``__get__`` method. Returns ``None`` if the method is not
-     found.
+.. function:: lookup_special(object, name, /)
+              lookup_special(object, name, default, /)
+
+   Lookup method name *name* on *object* skipping the instance dictionary.
+   *name* must be a string. If the named special attribute does not exist,
+   *default* is returned if provided, otherwise :exc:`AttributeError` is
+   raised.
 
    .. versionadded:: next
 

Lib/test/test_types.py

@@ -44,7 +44,7 @@ def test_names(self):
         c_only_names = {'CapsuleType', 'LazyImportType'}
         ignored = {'new_class', 'resolve_bases', 'prepare_class',
                    'get_original_bases', 'DynamicClassAttribute', 'coroutine',
-                   'lookup_special_method'}
+                   'lookup_special'}
 
         for name in c_types.__all__:
             if name not in c_only_names | ignored:
@@ -60,7 +60,7 @@ def test_names(self):
             'MemberDescriptorType', 'MethodDescriptorType', 'MethodType',
             'MethodWrapperType', 'ModuleType', 'NoneType',
             'NotImplementedType', 'SimpleNamespace', 'TracebackType',
-            'UnionType', 'WrapperDescriptorType', 'lookup_special_method',
+            'UnionType', 'WrapperDescriptorType', 'lookup_special',
         }
         self.assertEqual(all_names, set(c_types.__all__))
         self.assertEqual(all_names - c_only_names, set(py_types.__all__))
@@ -727,7 +727,7 @@ def test_frame_locals_proxy_type(self):
         self.assertIsNotNone(frame)
         self.assertIsInstance(frame.f_locals, types.FrameLocalsProxyType)
 
-    def _test_lookup_special_method(self, lookup):
+    def _test_lookup_special(self, lookup):
         class CM1:
             def __enter__(self):
                 return "__enter__ from class __dict__"
@@ -745,31 +745,24 @@ def __enter__(self):
                     return "__enter__ from __slots__"
                 self.__enter__ = __enter__
         cm1 = CM1()
-        meth = lookup(cm1, "__enter__")
-        self.assertIsNotNone(meth)
-        with self.assertRaisesRegex(
-                TypeError, "missing 1 required positional argument") as cm:
-            meth()
-        self.assertEqual(meth(cm1), "__enter__ from class __dict__")
-
-        meth = lookup(cm1, "__missing__")
-        self.assertIsNone(meth)
-
         with self.assertRaisesRegex(TypeError, "attribute name must be string"):
             lookup(cm1, 123)
+        with self.assertRaises(AttributeError):
+            lookup(cm1, "__missing__")
+        self.assertEqual(lookup(cm1, "__missing__", "default"), "default")
+        meth = lookup(cm1, "__enter__")
+        self.assertEqual(meth(), "__enter__ from class __dict__")
 
         cm2 = CM2()
-        meth = lookup(cm2, "__enter__")
-        self.assertIsNone(meth)
+        with self.assertRaises(AttributeError):
+            lookup(cm2, "__enter__")
 
         cm3 = CM3()
         meth = lookup(cm3, "__enter__")
-        self.assertIsNotNone(meth)
         self.assertEqual(meth(cm3), "__enter__ from __slots__")
 
         meth = lookup([], "__len__")
-        self.assertIsNotNone(meth)
-        self.assertEqual(meth([]), 0)
+        self.assertEqual(meth(), 0)
 
         class Person:
             @classmethod
@@ -782,21 +775,15 @@ def hello():
             def name(self):
                 return "name from property"
         p = Person()
-        meth = lookup(p, "hi")
-        self.assertIsNotNone(meth)
-        self.assertEqual(meth(), "hi from Person")
-
-        meth = lookup(p, "hello")
-        self.assertIsNotNone(meth)
-        self.assertEqual(meth(), "hello from static method")
-
+        self.assertEqual(lookup(p, "hi")(), "hi from Person")
+        self.assertEqual(lookup(p, "hello")(), "hello from static method")
         self.assertEqual(lookup(p, "name"), "name from property")
 
-    def test_lookup_special_method(self):
-        c_lookup = getattr(c_types, "lookup_special_method")
-        py_lookup = getattr(py_types, "lookup_special_method")
-        self._test_lookup_special_method(c_lookup)
-        self._test_lookup_special_method(py_lookup)
+    def test_lookup_special(self):
+        c_lookup = getattr(c_types, "lookup_special")
+        py_lookup = getattr(py_types, "lookup_special")
+        self._test_lookup_special(c_lookup)
+        self._test_lookup_special(py_lookup)
 
 
 class UnionTests(unittest.TestCase):

Lib/types.py

@@ -81,57 +81,27 @@ def _m(self): pass
 
     del sys, _f, _g, _C, _c, _ag, _cell_factory  # Not for export
 
-    def lookup_special_method(obj, attr, /):
-        """Lookup special method name `attr` on `obj`.
-
-        Lookup method `attr` on `obj` without looking in the instance
-        dictionary. For methods defined in class `__dict__` or `__slots__`, it
-        returns the unbound function (descriptor), not a bound method. The
-        caller is responsible for passing the object as the first argument when
-        calling it:
-
-        >>> class A:
-        ...    def __enter__(self):
-        ...        return "A.__enter__"
-        ...
-        >>> class B:
-        ...    __slots__ = ("__enter__",)
-        ...    def __init__(self):
-        ...        def __enter__(self):
-        ...            return "B.__enter__"
-        ...        self.__enter__ = __enter__
-        ...
-        >>> a = A()
-        >>> b = B()
-        >>> enter_a = types.lookup_special_method(a, "__enter__")
-        >>> enter_b = types.lookup_special_method(b, "__enter__")
-        >>> enter_a(a)
-        'A.__enter__'
-        >>> enter_b(b)
-        'B.__enter__'
-
-        For other descriptors (classmethod, staticmethod, property, etc.), it
-        returns the result of the descriptor's `__get__` method. Returns `None`
-        if the method is not found.
+    def lookup_special(object, name, *args):
+        """Lookup method name `name` on `object` skipping the instance
+        dictionary.
+
+        `name` must be a string. If the named special attribute does not exist,
+        `default` is returned if provided, otherwise AttributeError is raised.
         """
         from inspect import getattr_static
-        cls = type(obj)
-        if not isinstance(attr, str):
+        cls = type(object)
+        if not isinstance(name, str):
             raise TypeError(
-                f"attribute name must be string, not '{type(attr).__name__}'"
+                f"attribute name must be string, not '{type(name).__name__}'"
             )
         try:
-            descr = getattr_static(cls, attr)
+            descr = getattr_static(cls, name)
         except AttributeError:
-            return None
+            if args:
+                return args[0]
+            raise
         if hasattr(descr, "__get__"):
-            if isinstance(descr, (
-                FunctionType, MethodDescriptorType, WrapperDescriptorType)):
-                # do not create bound method to mimic the behavior of
-                # _PyObject_LookupSpecialMethod
-                return descr
-            else:
-                return descr.__get__(obj, cls)
+            return descr.__get__(object, cls)
         return descr
 
 

Misc/NEWS.d/next/Library/2026-02-19-17-46-59.gh-issue-144989.JAuJyG.rst

@@ -1,2 +1 @@
-Expose ``_PyObject_LookupSpecialMethod`` as
-:func:`types.lookup_special_method`.
+Expose ``_PyObject_LookupSpecial`` as :func:`types.lookup_special`.

Modules/_typesmodule.c

@@ -6,78 +6,44 @@
 #include "pycore_namespace.h"     // _PyNamespace_Type
 #include "pycore_object.h"        // _PyNone_Type, _PyNotImplemented_Type
 #include "pycore_unionobject.h"   // _PyUnion_Type
-#include "pycore_typeobject.h"    // _PyObject_LookupSpecialMethod
-#include "pycore_stackref.h"      // _PyStackRef
-#include "clinic/_typesmodule.c.h"
+#include "pycore_typeobject.h"    // _PyObject_LookupSpecial
+#include "pycore_modsupport.h"    // _PyArg_CheckPositional
 
-/*[clinic input]
-module _types
-[clinic start generated code]*/
-/*[clinic end generated code: output=da39a3ee5e6b4b0d input=530308b1011b659d]*/
-
-/*[clinic input]
-_types.lookup_special_method
-
-    obj: 'O'
-    attr: 'O'
-    /
-
-Lookup special method name `attr` on `obj`.
-
-Lookup method `attr` on `obj` without looking in the instance
-dictionary. For methods defined in class `__dict__` or `__slots__`, it
-returns the unbound function (descriptor), not a bound method. The
-caller is responsible for passing the object as the first argument when
-calling it:
-
->>> class A:
-...    def __enter__(self):
-...        return "A.__enter__"
-...
->>> class B:
-...    __slots__ = ("__enter__",)
-...    def __init__(self):
-...        def __enter__(self):
-...            return "B.__enter__"
-...        self.__enter__ = __enter__
-...
->>> a = A()
->>> b = B()
->>> enter_a = types.lookup_special_method(a, "__enter__")
->>> enter_b = types.lookup_special_method(b, "__enter__")
->>> enter_a(a)
-'A.__enter__'
->>> enter_b(b)
-'B.__enter__'
-
-For other descriptors (property, etc.), it returns the result of the
-descriptor's `__get__` method. Returns `None` if the method is not
-found.
-[clinic start generated code]*/
+PyDoc_STRVAR(lookup_special_doc,
+"lookup_special(object, name[, default], /)\n\
+\n\
+Lookup method name `name` on `object` skipping the instance dictionary.\n\
+`name` must be a string. If the named special attribute does not\n\
+exist,`default` is returned if provided, otherwise AttributeError is raised.");
 
 static PyObject *
-_types_lookup_special_method_impl(PyObject *module, PyObject *obj,
-                                  PyObject *attr)
-/*[clinic end generated code: output=890e22cc0b8e0d34 input=e317288370125cd5]*/
+_types_lookup_special_impl(PyObject *self, PyObject *const *args, Py_ssize_t nargs)
 {
-    if (!PyUnicode_Check(attr)) {
+    PyObject *v, *name, *result;
+
+    if (!_PyArg_CheckPositional("lookup_special", nargs, 2, 3))
+        return NULL;
+
+    v = args[0];
+    name = args[1];
+    if (!PyUnicode_Check(name)) {
         PyErr_Format(PyExc_TypeError,
                      "attribute name must be string, not '%.200s'",
-                     Py_TYPE(attr)->tp_name);
+                     Py_TYPE(name)->tp_name);
         return NULL;
     }
-    _PyStackRef method_and_self[2];
-    method_and_self[0] = PyStackRef_NULL;
-    method_and_self[1] = PyStackRef_FromPyObjectBorrow(obj);
-    int result = _PyObject_LookupSpecialMethod(attr, method_and_self);
-    if (result == -1) {
-        return NULL;
-    }
-    if (result == 0) {
-        Py_RETURN_NONE;
+    result = _PyObject_LookupSpecial(v, name);
+    if (result == NULL) {
+        if (nargs > 2) {
+            PyObject *dflt = args[2];
+            return Py_NewRef(dflt);
+        } else {
+            PyErr_Format(PyExc_AttributeError,
+                         "'%.50s' object has no special attribute '%U'",
+                         Py_TYPE(v)->tp_name, name);
+        }
     }
-    PyObject *method = PyStackRef_AsPyObjectSteal(method_and_self[0]);
-    return method;
+    return result;
 }
 
 static int
@@ -134,9 +100,9 @@ static struct PyModuleDef_Slot _typesmodule_slots[] = {
 };
 
 static PyMethodDef _typesmodule_methods[] = {
-    _TYPES_LOOKUP_SPECIAL_METHOD_METHODDEF
-    {NULL, NULL, 0, NULL}
-};
+    {"lookup_special", _PyCFunction_CAST(_types_lookup_special_impl),
+     METH_FASTCALL, lookup_special_doc},
+    {NULL, NULL, 0, NULL}};
 
 static struct PyModuleDef typesmodule = {
     .m_base = PyModuleDef_HEAD_INIT,