bpo-46014: Add docs regarding `functools.singledispatch` changes in 3.11 (#32282)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>

2 files changed, 51 insertions, 0 deletions

diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst
index e23946a..dd4d76e 100644
--- a/Doc/library/functools.rst
+++ b/Doc/library/functools.rst
@@ -436,6 +436,23 @@ The :mod:`functools` module defines the following functions:
      ...     for i, elem in enumerate(arg):
      ...         print(i, elem)
 
+   :data:`types.UnionType` and :data:`typing.Union` can also be used::
+
+    >>> @fun.register
+    ... def _(arg: int | float, verbose=False):
+    ...     if verbose:
+    ...         print("Strength in numbers, eh?", end=" ")
+    ...     print(arg)
+    ...
+    >>> from typing import Union
+    >>> @fun.register
+    ... def _(arg: Union[list, set], verbose=False):
+    ...     if verbose:
+    ...         print("Enumerate this:")
+    ...     for i, elem in enumerate(arg):
+    ...         print(i, elem)
+    ...
+
    For code which doesn't use type annotations, the appropriate type
    argument can be passed explicitly to the decorator itself::
 
@@ -535,6 +552,10 @@ The :mod:`functools` module defines the following functions:
    .. versionchanged:: 3.7
       The :func:`register` attribute now supports using type annotations.
 
+   .. versionchanged:: 3.11
+      The :func:`register` attribute now supports :data:`types.UnionType`
+      and :data:`typing.Union` as type annotations.
+
 
 .. class:: singledispatchmethod(func)
 
diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst
index baff687..6540a25 100644
--- a/Doc/whatsnew/3.11.rst
+++ b/Doc/whatsnew/3.11.rst
@@ -267,6 +267,36 @@ fractions
   that an ``isinstance(some_fraction, typing.SupportsInt)`` check passes.
   (Contributed by Mark Dickinson in :issue:`44547`.)
 
+functools
+---------
+
+* :func:`functools.singledispatch` now supports :data:`types.UnionType`
+  and :data:`typing.Union` as annotations to the dispatch argument.::
+
+    >>> from functools import singledispatch
+    >>> @singledispatch
+    ... def fun(arg, verbose=False):
+    ...     if verbose:
+    ...         print("Let me just say,", end=" ")
+    ...     print(arg)
+    ...
+    >>> @fun.register
+    ... def _(arg: int | float, verbose=False):
+    ...     if verbose:
+    ...         print("Strength in numbers, eh?", end=" ")
+    ...     print(arg)
+    ...
+    >>> from typing import Union
+    >>> @fun.register
+    ... def _(arg: Union[list, set], verbose=False):
+    ...     if verbose:
+    ...         print("Enumerate this:")
+    ...     for i, elem in enumerate(arg):
+    ...         print(i, elem)
+    ...
+
+  (Contributed by Yurii Karabas in :issue:`46014`.)
+
 hashlib
 -------