From 0f0ffc8451887b77192dd3f911768d6cfdad3ca0 Mon Sep 17 00:00:00 2001 From: Weilin Du <108666168+LamentXU123@users.noreply.github.com> Date: Tue, 8 Jul 2025 23:16:42 +0800 Subject: [PATCH 01/10] Update functools.rst --- Doc/library/functools.rst | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst index 3e75621be6dad3..32d2d8bfa64707 100644 --- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -200,11 +200,11 @@ The :mod:`functools` module defines the following functions: has no effect. To help measure the effectiveness of the cache and tune the *maxsize* - parameter, the wrapped function is instrumented with a :func:`cache_info` + parameter, the wrapped function is instrumented with a :func:`!cache_info` function that returns a :term:`named tuple` showing *hits*, *misses*, *maxsize* and *currsize*. - The decorator also provides a :func:`cache_clear` function for clearing or + The decorator also provides a :func:`!cache_clear` function for clearing or invalidating the cache. The original underlying function is accessible through the @@ -284,9 +284,9 @@ The :mod:`functools` module defines the following functions: class decorator supplies the rest. This simplifies the effort involved in specifying all of the possible rich comparison operations: - The class must define one of :meth:`__lt__`, :meth:`__le__`, - :meth:`__gt__`, or :meth:`__ge__`. - In addition, the class should supply an :meth:`__eq__` method. + The class must define one of :meth:`~object.__lt__`, :meth:`~object.__le__`, + :meth:`~object.__gt__`, or :meth:`~object.__ge__`. + In addition, the class should supply an :meth:`~object.__eq__` method. For example:: @@ -418,7 +418,7 @@ The :mod:`functools` module defines the following functions: like normal functions, are handled as descriptors). When *func* is a descriptor (such as a normal Python function, - :func:`classmethod`, :func:`staticmethod`, :func:`abstractmethod` or + :func:`classmethod`, :func:`staticmethod`, :func:`~abc.abstractmethod` or another instance of :class:`partialmethod`), calls to ``__get__`` are delegated to the underlying descriptor, and an appropriate :ref:`partial object` returned as the result. @@ -499,7 +499,7 @@ The :mod:`functools` module defines the following functions: ... print("Let me just say,", end=" ") ... print(arg) - To add overloaded implementations to the function, use the :func:`register` + 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:: @@ -565,14 +565,14 @@ The :mod:`functools` module defines the following functions: runtime impact. To enable registering :term:`lambdas` and pre-existing functions, - the :func:`register` attribute can also be used in a functional form:: + the :func:`!register` attribute can also be used in a functional form:: >>> def nothing(arg, verbose=False): ... print("Nothing.") ... >>> fun.register(type(None), nothing) - The :func:`register` attribute returns the undecorated function. This + The :func:`!register` attribute returns the undecorated function. This enables decorator stacking, :mod:`pickling`, and the creation of unit tests for each variant independently:: @@ -650,10 +650,10 @@ The :mod:`functools` module defines the following functions: .. versionadded:: 3.4 .. versionchanged:: 3.7 - The :func:`register` attribute now supports using type annotations. + The :func:`!register` attribute now supports using type annotations. .. versionchanged:: 3.11 - The :func:`register` attribute now supports + The :func:`!register` attribute now supports :class:`typing.Union` as a type annotation. @@ -783,7 +783,7 @@ The :mod:`functools` module defines the following functions: 'Docstring' Without the use of this decorator factory, the name of the example function - would have been ``'wrapper'``, and the docstring of the original :func:`example` + would have been ``'wrapper'``, and the docstring of the original :func:`!example` would have been lost. From 8c11b08efdd798a89f78b77cdd71337354d91f5f Mon Sep 17 00:00:00 2001 From: Weilin Du <108666168+LamentXU123@users.noreply.github.com> Date: Tue, 8 Jul 2025 23:18:17 +0800 Subject: [PATCH 02/10] Update .nitignore --- Doc/tools/.nitignore | 1 - 1 file changed, 1 deletion(-) diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore index 4f5396857f3024..ae9627fc1c4c2b 100644 --- a/Doc/tools/.nitignore +++ b/Doc/tools/.nitignore @@ -16,7 +16,6 @@ Doc/library/ast.rst Doc/library/asyncio-extending.rst Doc/library/email.charset.rst Doc/library/email.parser.rst -Doc/library/functools.rst Doc/library/http.cookiejar.rst Doc/library/http.server.rst Doc/library/importlib.rst From f74a61cefafe70164a2a565026d01232425b075a Mon Sep 17 00:00:00 2001 From: Weilin Du <108666168+LamentXU123@users.noreply.github.com> Date: Wed, 9 Jul 2025 01:15:33 +0800 Subject: [PATCH 03/10] add index entries and anchors for cache_info, cache_clear and register --- Doc/library/functools.rst | 25 ++++++++++++++++++------- 1 file changed, 18 insertions(+), 7 deletions(-) diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst index 32d2d8bfa64707..9e7a220dc31f3a 100644 --- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -151,6 +151,14 @@ The :mod:`functools` module defines the following functions: .. decorator:: lru_cache(user_function) lru_cache(maxsize=128, typed=False) + .. method:: cache_info() + :no-typesetting: + + + .. method:: cache_clear() + :no-typesetting: + + Decorator to wrap a function with a memoizing callable that saves up to the *maxsize* most recent calls. It can save time when an expensive or I/O bound function is periodically called with the same arguments. @@ -200,11 +208,11 @@ The :mod:`functools` module defines the following functions: has no effect. To help measure the effectiveness of the cache and tune the *maxsize* - parameter, the wrapped function is instrumented with a :func:`!cache_info` + parameter, the wrapped function is instrumented with a :func:`cache_info` function that returns a :term:`named tuple` showing *hits*, *misses*, *maxsize* and *currsize*. - The decorator also provides a :func:`!cache_clear` function for clearing or + The decorator also provides a :func:`cache_clear` function for clearing or invalidating the cache. The original underlying function is accessible through the @@ -485,6 +493,9 @@ The :mod:`functools` module defines the following functions: .. decorator:: singledispatch + .. method:: register() + :no-typesetting: + Transform a function into a :term:`single-dispatch ` :term:`generic function`. @@ -499,7 +510,7 @@ The :mod:`functools` module defines the following functions: ... print("Let me just say,", end=" ") ... print(arg) - To add overloaded implementations to the function, use the :func:`!register` + 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:: @@ -565,14 +576,14 @@ The :mod:`functools` module defines the following functions: runtime impact. To enable registering :term:`lambdas` and pre-existing functions, - the :func:`!register` attribute can also be used in a functional form:: + the :func:`register` attribute can also be used in a functional form:: >>> def nothing(arg, verbose=False): ... print("Nothing.") ... >>> fun.register(type(None), nothing) - The :func:`!register` attribute returns the undecorated function. This + The :func:`register` attribute returns the undecorated function. This enables decorator stacking, :mod:`pickling`, and the creation of unit tests for each variant independently:: @@ -650,10 +661,10 @@ The :mod:`functools` module defines the following functions: .. versionadded:: 3.4 .. versionchanged:: 3.7 - The :func:`!register` attribute now supports using type annotations. + The :func:`register` attribute now supports using type annotations. .. versionchanged:: 3.11 - The :func:`!register` attribute now supports + The :func:`register` attribute now supports :class:`typing.Union` as a type annotation. From 06e1364ca4eff891c3bf324536a54d139d19acf5 Mon Sep 17 00:00:00 2001 From: Weilin Du <108666168+LamentXU123@users.noreply.github.com> Date: Thu, 10 Jul 2025 18:08:10 +0800 Subject: [PATCH 04/10] Update functools.rst --- Doc/library/functools.rst | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst index 9e7a220dc31f3a..dd8e0682002da8 100644 --- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -151,14 +151,6 @@ The :mod:`functools` module defines the following functions: .. decorator:: lru_cache(user_function) lru_cache(maxsize=128, typed=False) - .. method:: cache_info() - :no-typesetting: - - - .. method:: cache_clear() - :no-typesetting: - - Decorator to wrap a function with a memoizing callable that saves up to the *maxsize* most recent calls. It can save time when an expensive or I/O bound function is periodically called with the same arguments. @@ -207,12 +199,18 @@ The :mod:`functools` module defines the following functions: and *typed*. This is for information purposes only. Mutating the values has no effect. + .. method:: functools.cache_info() + :no-typesetting: + To help measure the effectiveness of the cache and tune the *maxsize* - parameter, the wrapped function is instrumented with a :func:`cache_info` + parameter, the wrapped function is instrumented with a :func:`!cache_info` function that returns a :term:`named tuple` showing *hits*, *misses*, *maxsize* and *currsize*. - The decorator also provides a :func:`cache_clear` function for clearing or + .. method:: functools.cache_clear() + :no-typesetting: + + The decorator also provides a :func:`!cache_clear` function for clearing or invalidating the cache. The original underlying function is accessible through the From a07190e93de8e52c4b0935023b66e305c088ead3 Mon Sep 17 00:00:00 2001 From: Weilin Du <108666168+LamentXU123@users.noreply.github.com> Date: Fri, 11 Jul 2025 20:38:27 +0800 Subject: [PATCH 05/10] Apply suggestions from code review Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- Doc/library/functools.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst index dd8e0682002da8..5827da11849902 100644 --- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -199,7 +199,7 @@ The :mod:`functools` module defines the following functions: and *typed*. This is for information purposes only. Mutating the values has no effect. - .. method:: functools.cache_info() + .. method:: lru_cache.cache_info() :no-typesetting: To help measure the effectiveness of the cache and tune the *maxsize* @@ -207,7 +207,7 @@ The :mod:`functools` module defines the following functions: function that returns a :term:`named tuple` showing *hits*, *misses*, *maxsize* and *currsize*. - .. method:: functools.cache_clear() + .. method:: lru_cache.cache_clear() :no-typesetting: The decorator also provides a :func:`!cache_clear` function for clearing or From 8864e6d98dfe7018feafe9562f2df2d2d8d88d5b Mon Sep 17 00:00:00 2001 From: Weilin Du <108666168+LamentXU123@users.noreply.github.com> Date: Fri, 11 Jul 2025 20:42:24 +0800 Subject: [PATCH 06/10] Update functools.rst --- Doc/library/functools.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst index 5827da11849902..5f56c2d729cec2 100644 --- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -491,7 +491,7 @@ The :mod:`functools` module defines the following functions: .. decorator:: singledispatch - .. method:: register() + .. method:: singledispatch.register() :no-typesetting: Transform a function into a :term:`single-dispatch ` and pre-existing functions, - the :func:`register` attribute can also be used in a functional form:: + the :func:`!register` attribute can also be used in a functional form:: >>> def nothing(arg, verbose=False): ... print("Nothing.") ... >>> fun.register(type(None), nothing) - The :func:`register` attribute returns the undecorated function. This + The :func:`!register` attribute returns the undecorated function. This enables decorator stacking, :mod:`pickling`, and the creation of unit tests for each variant independently:: @@ -659,10 +659,10 @@ The :mod:`functools` module defines the following functions: .. versionadded:: 3.4 .. versionchanged:: 3.7 - The :func:`register` attribute now supports using type annotations. + The :func:`!register` attribute now supports using type annotations. .. versionchanged:: 3.11 - The :func:`register` attribute now supports + The :func:`!register` attribute now supports :class:`typing.Union` as a type annotation. From f65d178c1b829859be961322b80cf7203a23ed8e Mon Sep 17 00:00:00 2001 From: Weilin Du <108666168+LamentXU123@users.noreply.github.com> Date: Fri, 11 Jul 2025 21:12:03 +0800 Subject: [PATCH 07/10] Apply suggestions from code review Co-authored-by: Serhiy Storchaka --- 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 5f56c2d729cec2..bb6279e27c4116 100644 --- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -574,7 +574,7 @@ The :mod:`functools` module defines the following functions: runtime impact. To enable registering :term:`lambdas` and pre-existing functions, - the :func:`!register` attribute can also be used in a functional form:: + the :func:`~singledispatch.register` attribute can also be used in a functional form:: >>> def nothing(arg, verbose=False): ... print("Nothing.") From f82b0c485d8282cfb62464ff86b084969824fd71 Mon Sep 17 00:00:00 2001 From: Weilin Du <108666168+LamentXU123@users.noreply.github.com> Date: Fri, 11 Jul 2025 21:13:13 +0800 Subject: [PATCH 08/10] Update functools.rst --- Doc/library/functools.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst index bb6279e27c4116..8799aa34aa54bf 100644 --- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -491,9 +491,6 @@ The :mod:`functools` module defines the following functions: .. decorator:: singledispatch - .. method:: singledispatch.register() - :no-typesetting: - Transform a function into a :term:`single-dispatch ` :term:`generic function`. @@ -508,6 +505,9 @@ The :mod:`functools` module defines the following functions: ... print("Let me just say,", end=" ") ... print(arg) + .. method:: singledispatch.register() + :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 From 1edf2c4769f39f6b61a7f3400fd2be10bf4f54fe Mon Sep 17 00:00:00 2001 From: Weilin Du <108666168+LamentXU123@users.noreply.github.com> Date: Fri, 11 Jul 2025 21:19:55 +0800 Subject: [PATCH 09/10] Update functools.rst --- 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 8799aa34aa54bf..3c558b13cacdb6 100644 --- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -508,7 +508,7 @@ The :mod:`functools` module defines the following functions: .. method:: singledispatch.register() :no-typesetting: - To add overloaded implementations to the function, use the :func:`!register` + To add overloaded implementations to the function, use the :func:`~singledispatch.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:: @@ -581,7 +581,7 @@ The :mod:`functools` module defines the following functions: ... >>> fun.register(type(None), nothing) - The :func:`!register` attribute returns the undecorated function. This + The :func:`~singledispatch.register` attribute returns the undecorated function. This enables decorator stacking, :mod:`pickling`, and the creation of unit tests for each variant independently:: @@ -659,10 +659,10 @@ The :mod:`functools` module defines the following functions: .. versionadded:: 3.4 .. versionchanged:: 3.7 - The :func:`!register` attribute now supports using type annotations. + The :func:`~singledispatch.register` attribute now supports using type annotations. .. versionchanged:: 3.11 - The :func:`!register` attribute now supports + The :func:`~singledispatch.register` attribute now supports :class:`typing.Union` as a type annotation. From 3265c93651367d919933e7a483bdb9e4dea5195f Mon Sep 17 00:00:00 2001 From: Weilin Du <108666168+LamentXU123@users.noreply.github.com> Date: Fri, 11 Jul 2025 21:21:28 +0800 Subject: [PATCH 10/10] Update functools.rst --- 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 3c558b13cacdb6..beec9b942afc0f 100644 --- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -508,7 +508,7 @@ The :mod:`functools` module defines the following functions: .. method:: singledispatch.register() :no-typesetting: - To add overloaded implementations to the function, use the :func:`~singledispatch.register` + 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::