From: Matt Delengowski <matt.delengowski@gmail.com>
Date: Fri, 27 Sep 2024 21:10:29 +0000 (-0400)
Subject: gh-90190: Add doc for using `singledispatch` with precise collection type hints ... 
X-Git-Tag: v3.14.0a1~274
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=2357d5ba48cd9685cb36bcf92a0eaed86a85f4de;p=thirdparty%2FPython%2Fcpython.git

gh-90190: Add doc for using `singledispatch` with precise collection type hints (#116544)
---

diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst
index c2c25ca67f33..46136def06dc 100644
--- a/Doc/library/functools.rst
+++ b/Doc/library/functools.rst
@@ -543,6 +543,25 @@ The :mod:`functools` module defines the following functions:
      ...     print(arg.real, arg.imag)
      ...
 
+   For code that dispatches on a collections type (e.g., ``list``), but wants
+   to typehint the items of the collection (e.g., ``list[int]``), the
+   dispatch type should be passed explicitly to the decorator itself with the
+   typehint going into the function definition::
+
+     >>> @fun.register(list)
+     ... def _(arg: list[int], verbose=False):
+     ...     if verbose:
+     ...         print("Enumerate this:")
+     ...     for i, elem in enumerate(arg):
+     ...         print(i, elem)
+
+   .. note::
+
+      At runtime the function will dispatch on an instance of a list regardless
+      of the type contained within the list i.e. ``[1,2,3]`` will be
+      dispatched the same as ``["foo", "bar", "baz"]``. The annotation
+      provided in this example is for static type checkers only and has no
+      runtime impact.
 
    To enable registering :term:`lambdas<lambda>` and pre-existing functions,
    the :func:`register` attribute can also be used in a functional form::