Deprecate singledispatch registration by return annotation

Doc/deprecations/pending-removal-in-3.18.rst

@@ -7,3 +7,11 @@ Pending removal in Python 3.18
     specifier ``'N'``, which is only supported in the :mod:`!decimal` module's
     C implementation, has been deprecated since Python 3.13.
     (Contributed by Serhiy Storchaka in :gh:`89902`.)
+
+* :mod:`functools`:
+
+  * Using a return annotation to infer the dispatch type for
+    :func:`functools.singledispatch` or
+    :class:`functools.singledispatchmethod` is deprecated since Python 3.16
+    and will raise :exc:`TypeError` in Python 3.18. Annotate the dispatch
+    parameter or pass the dispatch type explicitly instead.

Doc/library/functools.rst

@@ -506,9 +506,9 @@ The :mod:`!functools` module defines the following functions:
       :no-typesetting:
 
    To add overloaded implementations to the function, use the :func:`!register`
-   attribute of the generic function, which can be used as a decorator.  For
-   functions annotated with types, the decorator will infer the type of the
-   first argument automatically::
+   attribute of the generic function, which can be used as a decorator. For
+   functions annotated with types, the decorator can infer the dispatch type
+   automatically::
 
      >>> @fun.register
      ... def _(arg: int, verbose=False):
@@ -540,8 +540,9 @@ The :mod:`!functools` module defines the following functions:
     ...         print(i, elem)
     ...
 
-   For code which doesn't use type annotations, the appropriate type
-   argument can be passed explicitly to the decorator itself::
+   For code which doesn't use type annotations, or where the first resolved
+   annotation does not belong to the dispatch argument, the appropriate type
+   can be passed explicitly to the decorator itself::
 
      >>> @fun.register(complex)
      ... def _(arg, verbose=False):
@@ -662,6 +663,12 @@ The :mod:`!functools` module defines the following functions:
       The :func:`~singledispatch.register` attribute now supports
       :class:`typing.Union` as a type annotation.
 
+   .. deprecated:: 3.16
+      Using a return annotation to infer the dispatch type is deprecated and
+      will raise :exc:`TypeError` in Python 3.18. Annotate the dispatch
+      parameter or pass the dispatch type explicitly to :func:`!register`
+      instead.
+
 
 .. class:: singledispatchmethod(func)
 
@@ -686,6 +693,20 @@ The :mod:`!functools` module defines the following functions:
         def _(self, arg: bool):
             return not arg
 
+   When *self* or *cls* is annotated, pass the dispatch type explicitly rather
+   than relying on annotation inference::
+
+    from typing import Self
+
+    class Negator:
+        @singledispatchmethod
+        def neg(self, arg):
+            raise NotImplementedError("Cannot negate a")
+
+        @neg.register(int)
+        def _(self: Self, arg: int):
+            return -arg
+
    ``@singledispatchmethod`` supports nesting with other decorators such as
    :deco:`classmethod`. Note that to allow for
    ``dispatcher.register``, ``singledispatchmethod`` must be the *outer most*

Doc/whatsnew/3.15.rst

@@ -748,13 +748,6 @@ functools
   if it wraps a regular method and is called as a class attribute.
   (Contributed by Bartosz Sławecki in :gh:`143535`.)
 
-* When registering a callable or descriptor to :func:`functools.singledispatch`
-  or :func:`functools.singledispatchmethod` via a type annotation,
-  it is now validated that the first non-*self* or non-*cls* parameter is used.
-  Previously, a callable could be registered based on its return type
-  annotation or an irrelevant parameter type annotation.
-  (Contributed by Bartosz Sławecki in :gh:`84644`.)
-
 
 hashlib
 -------

Lib/functools.py

@@ -893,45 +893,6 @@ 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
-        func = func.__func__
-    elif isinstance(func, (classmethod, MethodType)):
-        idx = 1  # Skip parameter bound by instance-level access.
-        func = func.__func__
-    else:
-        # Assume and skip bound parameter when singledispatchmethod is used.
-        idx = 1 if role == "method" else 0
-    # 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.
 
@@ -979,7 +940,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, *, _role="function"):
+    def register(cls, func=None):
         """generic_func.register(cls, func) -> func
 
         Registers a new implementation for the given *cls* on a *generic_func*.
@@ -1004,22 +965,10 @@ def register(cls, func=None, *, _role="function"):
                 )
             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
-            annotations = get_type_hints(func, format=Format.FORWARDREF)
-
-            try:
-                cls = annotations[argname]
-            except KeyError:
-                raise TypeError(
-                    f"Invalid first argument to `register()`: {func!r}. "
-                    f"Use either `@register(some_class)` or add a type "
-                    f"annotation to parameter {argname!r} of your callable."
-                ) from None
-
+            argname, cls = next(iter(get_type_hints(func, format=Format.FORWARDREF).items()))
             if not _is_valid_dispatch_type(cls):
                 if isinstance(cls, UnionType):
                     raise TypeError(
@@ -1036,6 +985,17 @@ def register(cls, func=None, *, _role="function"):
                         f"Invalid annotation for {argname!r}. "
                         f"{cls!r} is not a class."
                     )
+            if argname == 'return':
+                import os
+                import warnings
+                warnings.warn(
+                    "Using the return annotation to infer the dispatch type "
+                    "is deprecated and will raise TypeError in Python 3.18. "
+                    "Annotate the dispatch parameter or pass the dispatch "
+                    "type explicitly to register().",
+                    DeprecationWarning,
+                    skip_file_prefixes=(os.path.dirname(__file__),),
+                )
 
         if isinstance(cls, UnionType):
             for arg in cls.__args__:
@@ -1056,7 +1016,6 @@ def wrapper(*args, **kw):
     funcname = getattr(func, '__name__', 'singledispatch function')
     registry[object] = func
     wrapper.register = register
-    wrapper.register.__text_signature__ = "(cls, func=None)"  # Hide _role from help().
     wrapper.dispatch = dispatch
     wrapper.registry = MappingProxyType(registry)
     wrapper._clear_cache = dispatch_cache.clear
@@ -1084,7 +1043,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, _role="method")
+        return self.dispatcher.register(cls, func=method)
 
     def __get__(self, obj, cls=None):
         return _singledispatchmethod_get(self, obj, cls)