gh-130827: Support typing.Self annotations in singledispatchmethod()

Lib/functools.py

@@ -885,15 +885,7 @@ def _find_impl(cls, registry):
             match = t
     return registry.get(match)
 
-def singledispatch(func):
-    """Single-dispatch generic function decorator.
-
-    Transforms a function into a generic function, which can have different
-    behaviours depending upon the type of its first argument. The decorated
-    function acts as the default implementation, and additional
-    implementations can be registered using the register() attribute of the
-    generic function.
-    """
+def _singledispatchimpl(func, is_method):
     # There are many programs that use functools without singledispatch, so we
     # trade-off making singledispatch marginally slower for the benefit of
     # making start-up of such applications slightly faster.
@@ -963,9 +955,19 @@ def register(cls, func=None):
             func = cls
 
             # only import typing if annotation parsing is necessary
-            from typing import get_type_hints
+            from typing import get_type_hints, Self
             from annotationlib import Format, ForwardRef
-            argname, cls = next(iter(get_type_hints(func, format=Format.FORWARDREF).items()))
+            hints_iter = iter(get_type_hints(func, format=Format.FORWARDREF).items())
+            argname, cls = next(hints_iter)
+            if cls is Self:
+                if not is_method:
+                    raise TypeError(
+                        f"Invalid annotation for {argname!r}. ",
+                        "typing.Self can only be used with singledispatchmethod()"
+                    )
+                else:
+                    argname, cls = next(hints_iter)
+
             if not _is_valid_dispatch_type(cls):
                 if _is_union_type(cls):
                     raise TypeError(
@@ -1010,6 +1012,16 @@ def wrapper(*args, **kw):
     update_wrapper(wrapper, func)
     return wrapper
 
+def singledispatch(func):
+    """Single-dispatch generic function decorator.
+
+    Transforms a function into a generic function, which can have different
+    behaviours depending upon the type of its first argument. The decorated
+    function acts as the default implementation, and additional
+    implementations can be registered using the register() attribute of the
+    generic function.
+    """
+    return _singledispatchimpl(func, is_method=False)
 
 # Descriptor version
 class singledispatchmethod:
@@ -1023,7 +1035,7 @@ def __init__(self, func):
         if not callable(func) and not hasattr(func, "__get__"):
             raise TypeError(f"{func!r} is not callable or a descriptor")
 
-        self.dispatcher = singledispatch(func)
+        self.dispatcher = _singledispatchimpl(func, is_method=True)
         self.func = func
 
     def register(self, cls, method=None):

Lib/test/test_functools.py

@@ -3362,6 +3362,29 @@ def _(item, arg: bytes) -> str:
         self.assertEqual(str(Signature.from_callable(A.static_func)),
                          '(item, arg: int) -> str')
 
+    def test_typing_self(self):
+        # gh-130827: typing.Self with singledispatchmethod() didn't work
+        class Foo:
+            @functools.singledispatchmethod
+            def bar(self: typing.Self, arg: int | str) -> int | str: ...
+
+            @bar.register
+            def _(self: typing.Self, arg: int) -> int:
+                return arg
+
+
+        foo = Foo()
+        self.assertEqual(foo.bar(42), 42)
+
+        @functools.singledispatch
+        def test(self: typing.Self, arg: int | str) -> int | str:
+            pass
+        # But, it shouldn't work on singledispatch()
+        with self.assertRaises(TypeError):
+            @test.register
+            def silly(self: typing.Self, arg: int | str) -> int | str:
+                pass
+
 
 class CachedCostItem:
     _cost = 1

Misc/NEWS.d/next/Library/2025-03-04-06-57-56.gh-issue-130827.XZacmc.rst

@@ -0,0 +1,2 @@
+Fix :exc:`TypeError` when using :func:`functools.singledispatchmethod` with
+a :class:`typing.Self` annotation.