From d95c49d9eb9c2d95d236e09dc27da59d79a2a565 Mon Sep 17 00:00:00 2001 From: Matt Delengowski Date: Sat, 9 Mar 2024 09:22:41 -0500 Subject: [PATCH 1/4] gh-90190: Adds documentation for singledispatch with GenericAlias annotation --- Doc/library/functools.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst index 82c970d25a7aac..5e279f7ccd0c00 100644 --- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -492,6 +492,25 @@ The :mod:`functools` module defines the following functions: ... print(arg.real, arg.imag) ... + For code that dispatches on a collections type, e.g. :data:`list`, but wants + to typehint the items of the collection, e.g. :data:`list[int]`, then 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. :data:`[1,2,3]` will be + dispatched the same as :data:`["foo", "bar", "baz"]`. The annontation + provided in this example is for static type checkers only and has no + runtime application. To enable registering :term:`lambdas` and pre-existing functions, the :func:`register` attribute can also be used in a functional form:: From 92f8c8241b63e090db57b253bf4947c4a186928c Mon Sep 17 00:00:00 2001 From: Matt Delengowski Date: Sat, 9 Mar 2024 09:48:47 -0500 Subject: [PATCH 2/4] Corrects rst syntax --- Doc/library/functools.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst index 5e279f7ccd0c00..0f37e0713b78bf 100644 --- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -492,8 +492,8 @@ The :mod:`functools` module defines the following functions: ... print(arg.real, arg.imag) ... - For code that dispatches on a collections type, e.g. :data:`list`, but wants - to typehint the items of the collection, e.g. :data:`list[int]`, then the + For code that dispatches on a collections type, e.g. ``list``, but wants + to typehint the items of the collection, e.g. ``list[int]``, then the dispatch type should be passed explicitly to the decorator itself with the typehint going into the function definition:: @@ -507,8 +507,8 @@ The :mod:`functools` module defines the following functions: .. note:: At runtime the function will dispatch on an instance of a list regardless - of the type contained within the list i.e. :data:`[1,2,3]` will be - dispatched the same as :data:`["foo", "bar", "baz"]`. The annontation + of the type contained within the list i.e. ``[1,2,3]`` will be + dispatched the same as ``["foo", "bar", "baz"]``. The annontation provided in this example is for static type checkers only and has no runtime application. From 16cd6f08067bc106d709a738d730cf0bc821dd18 Mon Sep 17 00:00:00 2001 From: Matt Delengowski Date: Fri, 10 May 2024 12:36:51 -0400 Subject: [PATCH 3/4] Resolves grammatical errors and wording feedback --- Doc/library/functools.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst index 537a7af2fac61a..8b90d295bba7c2 100644 --- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -492,8 +492,8 @@ 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]``, then the + For code that dispatches on a collections type (e.g., ``list``), but wants + to typehint the items of the collection (e.g., ``list[int]``), then the dispatch type should be passed explicitly to the decorator itself with the typehint going into the function definition:: @@ -508,9 +508,9 @@ The :mod:`functools` module defines the following functions: 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 annontation + dispatched the same as ``["foo", "bar", "baz"]``. The annotation provided in this example is for static type checkers only and has no - runtime application. + runtime impact. To enable registering :term:`lambdas` and pre-existing functions, the :func:`register` attribute can also be used in a functional form:: From dc45be59b45a687ea0d9b0a1f30cb2ec9184d9d9 Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Fri, 27 Sep 2024 13:48:54 -0700 Subject: [PATCH 4/4] minor grammar fix --- Doc/library/functools.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst index fa1fed93df82dc..6be80f78528186 100644 --- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -493,7 +493,7 @@ The :mod:`functools` module defines the following functions: ... For code that dispatches on a collections type (e.g., ``list``), but wants - to typehint the items of the collection (e.g., ``list[int]``), then the + 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::