gh-84644: Fix singledispatch annotation parsing

Lib/functools.py

@@ -19,7 +19,7 @@
 # import weakref  # Deferred to single_dispatch()
 from operator import itemgetter
 from reprlib import recursive_repr
-from types import GenericAlias, MethodType, MappingProxyType, UnionType
+from types import FunctionType, GenericAlias, MethodType, MappingProxyType, UnionType
 from _thread import RLock
 
 ################################################################################
@@ -888,6 +888,44 @@ def _find_impl(cls, registry):
             match = t
     return registry.get(match)
 
+def _get_singledispatch_annotated_param(func, *, role):
+    """Find the first positional and user-specified parameter in a callable
+    or descriptor.
+
+    Used by singledispatch for registration by type annotation of the parameter.
+    """
+    if isinstance(func, staticmethod):
+        idx = 0  # Take the very first parameter.
+        func = func.__func__
+    elif isinstance(func, (classmethod, MethodType)):
+        idx = 1  # Skip *cls* or *self*.
+        func = func.__func__
+    else:
+        # Skip *self* when called from `singledispatchmethod.register`.
+        idx = 0 if role == "function" else 1
+    # Fast path: emulate `inspect._signature_from_function` if possible.
+    if isinstance(func, FunctionType) and not hasattr(func, "__wrapped__"):
+        func_code = func.__code__
+        try:
+            return func_code.co_varnames[:func_code.co_argcount][idx]
+        except IndexError:
+            pass
+    # Fall back to `inspect.signature` (slower, but complete).
+    import inspect
+    params = list(inspect.signature(func).parameters.values())
+    try:
+        param = params[idx]
+    except IndexError:
+        pass
+    else:
+        # Allow variadic positional "(*args)" parameters for backward compatibility.
+        if param.kind not in (inspect.Parameter.KEYWORD_ONLY, inspect.Parameter.VAR_KEYWORD):
+            return param.name
+    raise TypeError(
+        f"Invalid first argument to `register()`: {func!r} "
+        f"does not accept positional arguments."
+    )
+
 def singledispatch(func):
     """Single-dispatch generic function decorator.
 
@@ -935,7 +973,7 @@ def _is_valid_dispatch_type(cls):
         return (isinstance(cls, UnionType) and
                 all(isinstance(arg, type) for arg in cls.__args__))
 
-    def register(cls, func=None):
+    def register(cls, func=None, __role__="function"):
         """generic_func.register(cls, func) -> func
 
         Registers a new implementation for the given *cls* on a *generic_func*.
@@ -960,10 +998,22 @@ def register(cls, func=None):
                 )
             func = cls
 
+            argname = _get_singledispatch_annotated_param(func, role=__role__)
+
             # only import typing if annotation parsing is necessary
             from typing import get_type_hints
             from annotationlib import Format, ForwardRef
-            argname, cls = next(iter(get_type_hints(func, format=Format.FORWARDREF).items()))
+            annotations = get_type_hints(func, format=Format.FORWARDREF)
+
+            try:
+                cls = annotations[argname]
+            except KeyError:
+                raise TypeError(
+                    f"Invalid first argument to `register()`: {func!r}. "
+                    "Use either `@register(some_class)` or add a type "
+                    f"annotation to parameter {argname!r} of your callable."
+                ) from None
+
             if not _is_valid_dispatch_type(cls):
                 if isinstance(cls, UnionType):
                     raise TypeError(
@@ -1000,6 +1050,7 @@ def wrapper(*args, **kw):
     funcname = getattr(func, '__name__', 'singledispatch function')
     registry[object] = func
     wrapper.register = register
+    wrapper.register.__text_signature__ = "(cls, func)"  # Hide private parameters from help().
     wrapper.dispatch = dispatch
     wrapper.registry = MappingProxyType(registry)
     wrapper._clear_cache = dispatch_cache.clear
@@ -1027,7 +1078,7 @@ def register(self, cls, method=None):
 
         Registers a new implementation for the given *cls* on a *generic_method*.
         """
-        return self.dispatcher.register(cls, func=method)
+        return self.dispatcher.register(cls, func=method, __role__="method")
 
     def __get__(self, obj, cls=None):
         return _singledispatchmethod_get(self, obj, cls)

Lib/test/test_functools.py

@@ -2721,6 +2721,22 @@ def __eq__(self, other):
                 return self.arg == other
         self.assertEqual(i("str"), "str")
 
+    def test_annotations_positional_only(self):
+        """Regression test for GH-143888."""
+        @functools.singledispatch
+        def f(arg, /, extra):
+            return "base"
+        @f.register
+        def f_int(arg: int, /, extra: str):
+            return "int"
+        @f.register
+        def f_str(arg: str, /, extra: int):
+            return "str"
+
+        self.assertEqual(f(None, "extra"), "base")
+        self.assertEqual(f(1, "extra"), "int")
+        self.assertEqual(f("s", "extra"), "str")
+
     def test_method_register(self):
         class A:
             @functools.singledispatchmethod
@@ -2955,6 +2971,44 @@ def _(cls, arg: str):
         self.assertEqual(A.t('').arg, "str")
         self.assertEqual(A.t(0.0).arg, "base")
 
+    def test_method_type_ann_register_correct_param_skipped(self):
+        class C:
+            @functools.singledispatchmethod
+            def t(self, x):
+                return "base"
+
+            # This tests GH-130827.
+            @t.register
+            def _(self: typing.Self, x: int) -> str:
+                return "int"
+
+            @t.register
+            @classmethod
+            def _(self: type['C'], x: complex) -> str:
+                return "complex"
+
+            @t.register
+            @staticmethod  # 'x' cannot be skipped.
+            def _(x: float) -> str:
+                return "float"
+
+            def _bytes(self: typing.Self, x: bytes) -> None:
+                return "bytes"
+
+            def _bytearray(self: typing.Self, x: bytearray) -> None:
+                return "bytearray"
+
+        c = C()
+        C.t.register(c._bytes)
+        c.t.register(C._bytearray)
+
+        self.assertEqual(c.t(NotImplemented), "base")
+        self.assertEqual(c.t(42), "int")
+        self.assertEqual(c.t(1991j), "complex")
+        self.assertEqual(c.t(.572), "float")
+        self.assertEqual(c.t(b'ytes'), "bytes")
+        self.assertEqual(c.t(bytearray(3)), "bytearray")
+
     def test_method_wrapping_attributes(self):
         class A:
             @functools.singledispatchmethod
@@ -3175,7 +3229,7 @@ def i(arg):
         with self.assertRaises(TypeError) as exc:
             @i.register(42)
             def _(arg):
-                return "I annotated with a non-type"
+                return "I passed a non-type"
         self.assertStartsWith(str(exc.exception), msg_prefix + "42")
         self.assertEndsWith(str(exc.exception), msg_suffix)
         with self.assertRaises(TypeError) as exc:
@@ -3187,6 +3241,10 @@ def _(arg):
         )
         self.assertEndsWith(str(exc.exception), msg_suffix)
 
+    def test_type_ann_register_invalid_types(self):
+        @functools.singledispatch
+        def i(arg):
+            return "base"
         with self.assertRaises(TypeError) as exc:
             @i.register
             def _(arg: typing.Iterable[str]):
@@ -3213,6 +3271,100 @@ def _(arg: typing.Union[int, typing.Iterable[str]]):
             'int | typing.Iterable[str] not all arguments are classes.'
         )
 
+    def test_type_ann_register_missing_annotation(self):
+        add_missing_re = (
+            r"Invalid first argument to `register\(\)`: <function .+>. "
+            r"Use either `@register\(some_class\)` or add a type annotation "
+            r"to parameter 'arg' of your callable."
+        )
+        no_positional_re = (
+            r"Invalid first argument to `register\(\)`: <function .+> "
+            r"does not accept positional arguments."
+        )
+
+        @functools.singledispatch
+        def d(arg):
+            pass
+
+        with self.assertRaisesRegex(TypeError, add_missing_re):
+            # This tests GH-84644.
+            @d.register
+            def _(arg) -> int:
+                """I only annotated the return type."""
+                return 42
+
+        with self.assertRaisesRegex(TypeError, add_missing_re):
+            @d.register
+            def _(arg, /, arg2) -> int:
+                """I did not annotate the first param."""
+                return 42
+
+        with self.assertRaisesRegex(TypeError, no_positional_re):
+            @d.register
+            def _(*, arg: int = 13, arg2: int = 37) -> int:
+                """I do not accept positional arguments."""
+                return 42
+
+        with self.assertRaisesRegex(TypeError, add_missing_re):
+            @d.register
+            def _(arg, **kwargs: int):
+                """I only annotated keyword arguments type."""
+                return 42
+
+    def test_method_type_ann_register_missing_annotation(self):
+        add_missing_re = (
+            r"Invalid first argument to `register\(\)`: <%s.+>. "
+            r"Use either `@register\(some_class\)` or add a type annotation "
+            r"to parameter 'arg' of your callable."
+        )
+        no_positional_re = (
+            r"Invalid first argument to `register\(\)`: <%s.+> "
+            r"does not accept positional arguments."
+        )
+
+        class C:
+            @functools.singledispatchmethod
+            def d(self, arg):
+                return "base"
+
+            with self.assertRaisesRegex(TypeError, no_positional_re % "function"):
+                @d.register
+                def _() -> None:
+                    """I am not a incorrect method."""
+                    return 42
+
+            with self.assertRaisesRegex(TypeError, no_positional_re % "function"):
+                @d.register
+                def _(self: typing.Self):
+                    """I only take self."""
+                    return 42
+
+            with self.assertRaisesRegex(TypeError, no_positional_re % "function"):
+                @d.register
+                def _(self: typing.Self, *, arg):
+                    """I did not annotate the key parameter."""
+                    return 42
+
+            with self.assertRaisesRegex(TypeError, add_missing_re % "classmethod"):
+                @d.register
+                @classmethod
+                def _(cls: type[typing.Self], arg) -> int:
+                    """I did not annotate the key parameter again."""
+                    return 42
+
+            with self.assertRaisesRegex(TypeError, add_missing_re % "staticmethod"):
+                @d.register
+                @staticmethod
+                def _(arg, arg2: int, /, *, arg3: int = 1991):
+                    """I missed first arg again."""
+                    return 42
+
+            def later(self, arg, **kwargs: int):
+                return 42
+
+        with self.assertRaisesRegex(TypeError, add_missing_re % "bound method"):
+            C.d.register(C().later)
+
     def test_invalid_positional_argument(self):
         @functools.singledispatch
         def f(*args, **kwargs):

Misc/NEWS.d/next/Library/2026-01-06-09-13-53.gh-issue-84644.V_cYP3.rst

@@ -0,0 +1,5 @@
+:func:`functools.singledispatch` and :func:`functools.singledispatchmethod`
+now require callables to be correctly annotated if registering without a type explicitly
+specified in the decorator. The first user-specified positional parameter of a callable
+must always be annotated. Before, a callable could be registered based on its return type
+annotation or based on an irrelevant parameter type annotation. Contributed by Bartosz Sławecki.