@@ -506,24 +506,37 @@ The :mod:`!functools` module defines the following functions:
506506 :no-typesetting:
507507
508508 To add overloaded implementations to the function, use the :func: `!register `
509- attribute of the generic function, which can be used as a decorator. For
510- functions annotated with types, the decorator will infer the type of the
511- first argument automatically::
509+ attribute of the generic function, which can be used as a decorator.
510+ Pass the dispatch type to the decorator::
512511
513- >>> @fun.register
514- ... def _(arg: int , verbose=False):
512+ >>> @fun.register(int)
513+ ... def _(arg, verbose=False):
515514 ... if verbose:
516515 ... print("Strength in numbers, eh?", end=" ")
517516 ... print(arg)
518517 ...
519- >>> @fun.register
520- ... def _(arg: list , verbose=False):
518+ >>> @fun.register(list)
519+ ... def _(arg, verbose=False):
521520 ... if verbose:
522521 ... print("Enumerate this:")
523522 ... for i, elem in enumerate(arg):
524523 ... print(i, elem)
525524
526- :class: `typing.Union ` can also be used::
525+ As a shortcut, for functions annotated with types, the decorator can infer
526+ the dispatch type without an explicit type argument::
527+
528+ >>> @fun.register
529+ ... def _(arg: int, verbose=False):
530+ ... if verbose:
531+ ... print("Strength in numbers, eh?", end=" ")
532+ ... print(arg)
533+ ...
534+
535+ This shortcut uses the first annotation, even if it belongs to another
536+ parameter or the return value. Annotate the dispatch parameter, or pass the
537+ dispatch type explicitly if its annotation is not first.
538+
539+ :class: `typing.Union ` can also be used with this shortcut::
527540
528541 >>> @fun.register
529542 ... def _(arg: int | float, verbose=False):
@@ -540,16 +553,6 @@ The :mod:`!functools` module defines the following functions:
540553 ... print(i, elem)
541554 ...
542555
543- For code which doesn't use type annotations, the appropriate type
544- argument can be passed explicitly to the decorator itself::
545-
546- >>> @fun.register(complex)
547- ... def _(arg, verbose=False):
548- ... if verbose:
549- ... print("Better than complicated.", end=" ")
550- ... print(arg.real, arg.imag)
551- ...
552-
553556 For code that dispatches on a collections type (e.g., ``list ``), but wants
554557 to typehint the items of the collection (e.g., ``list[int] ``), the
555558 dispatch type should be passed explicitly to the decorator itself with the
@@ -662,6 +665,12 @@ The :mod:`!functools` module defines the following functions:
662665 The :func: `~singledispatch.register ` attribute now supports
663666 :class: `typing.Union ` as a type annotation.
664667
668+ .. deprecated :: 3.16
669+ Using a return annotation to infer the dispatch type is deprecated and
670+ will raise :exc: `TypeError ` in Python 3.21. Annotate the dispatch
671+ parameter or pass the dispatch type explicitly to :func: `!register `
672+ instead.
673+
665674
666675.. class :: singledispatchmethod(func)
667676
@@ -686,6 +695,20 @@ The :mod:`!functools` module defines the following functions:
686695 def _(self, arg: bool):
687696 return not arg
688697
698+ When *self * or *cls * is annotated, pass the dispatch type explicitly rather
699+ than relying on annotation inference::
700+
701+ from typing import Self
702+
703+ class Negator:
704+ @singledispatchmethod
705+ def neg(self, arg):
706+ raise NotImplementedError("Cannot negate a")
707+
708+ @neg.register(int)
709+ def _(self: Self, arg: int):
710+ return -arg
711+
689712 ``@singledispatchmethod `` supports nesting with other decorators such as
690713 :deco: `classmethod `. Note that to allow for
691714 ``dispatcher.register ``, ``singledispatchmethod `` must be the *outer most *
0 commit comments