From 666a2a8abeb71e6799219154f0e1e2b0da18d741 Mon Sep 17 00:00:00 2001 From: priyanshu2282-cyber Date: Fri, 9 Jan 2026 15:15:42 +0530 Subject: [PATCH 1/5] gh-143535: Document dispatch behavior of singledispatchmethod --- Doc/library/functools.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst index 221c0712c7c96a..8c4ba3ac6e29bd 100644 --- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -679,7 +679,11 @@ The :mod:`functools` module defines the following functions: decorator. When defining a method using ``@singledispatchmethod``, note that the dispatch happens on the type of the first non-*self* or non-*cls* argument:: - + .. note:: + ``singledispatchmethod`` dispatches the first argument during call + time irrespective of whether the method is bound or unbound, as a result, + ``x.f(a) != C.f(x, a)``.The behavior is intentional and required to support correct dispatch for + ``staticmethod`` and ``classmethod``. class Negator: @singledispatchmethod def neg(self, arg): From ea2fda1cdbde5d32d0c3f57f3b4a8c099853ee87 Mon Sep 17 00:00:00 2001 From: priyanshu2282-cyber Date: Fri, 9 Jan 2026 15:42:01 +0530 Subject: [PATCH 2/5] gh-143535: Move singledispatchmethod note outside example block --- Doc/library/functools.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst index 8c4ba3ac6e29bd..1aa21129b203fc 100644 --- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -679,11 +679,7 @@ The :mod:`functools` module defines the following functions: decorator. When defining a method using ``@singledispatchmethod``, note that the dispatch happens on the type of the first non-*self* or non-*cls* argument:: - .. note:: - ``singledispatchmethod`` dispatches the first argument during call - time irrespective of whether the method is bound or unbound, as a result, - ``x.f(a) != C.f(x, a)``.The behavior is intentional and required to support correct dispatch for - ``staticmethod`` and ``classmethod``. + class Negator: @singledispatchmethod def neg(self, arg): @@ -696,6 +692,11 @@ The :mod:`functools` module defines the following functions: @neg.register def _(self, arg: bool): return not arg + .. note:: + ``singledispatchmethod`` dispatches the first argument during call + time irrespective of whether the method is bound or unbound, as a result, + ``x.f(a) != C.f(x, a)``.The behavior is intentional and required to support correct dispatch for + ``staticmethod`` and ``classmethod``. ``@singledispatchmethod`` supports nesting with other decorators such as :deco:`classmethod`. Note that to allow for From 2834c451993be5335d785680caf29d8ce6f26919 Mon Sep 17 00:00:00 2001 From: priyanshu2282-cyber Date: Fri, 9 Jan 2026 16:36:31 +0530 Subject: [PATCH 3/5] gh-143535: Clarify dispatch semantics of singledispatchmethod --- Doc/library/functools.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst index 1aa21129b203fc..5c4f9a9319e529 100644 --- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -692,11 +692,6 @@ The :mod:`functools` module defines the following functions: @neg.register def _(self, arg: bool): return not arg - .. note:: - ``singledispatchmethod`` dispatches the first argument during call - time irrespective of whether the method is bound or unbound, as a result, - ``x.f(a) != C.f(x, a)``.The behavior is intentional and required to support correct dispatch for - ``staticmethod`` and ``classmethod``. ``@singledispatchmethod`` supports nesting with other decorators such as :deco:`classmethod`. Note that to allow for @@ -723,6 +718,12 @@ The :mod:`functools` module defines the following functions: The same pattern can be used for other similar decorators: :deco:`staticmethod`, :deco:`~abc.abstractmethod`, and others. + ``singledispatchmethod`` always dispatches on the first argument passed at call + time, irrespective of whether the method is bound or unbound. As a result, + calling the method through an instance or through the class may result in + different dispatch behavior. This behavior is required to support correct + dispatch when used with ``staticmethod`` and ``classmethod``. + .. versionadded:: 3.8 .. versionchanged:: 3.15 From 57e6d202603786bff8f6178797c29964315c905f Mon Sep 17 00:00:00 2001 From: Priyanshu Singh Date: Mon, 12 Jan 2026 20:41:51 +0530 Subject: [PATCH 4/5] Update Doc/library/functools.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bartosz Sławecki --- Doc/library/functools.rst | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst index 5c4f9a9319e529..2709db78aeb311 100644 --- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -718,12 +718,10 @@ The :mod:`functools` module defines the following functions: The same pattern can be used for other similar decorators: :deco:`staticmethod`, :deco:`~abc.abstractmethod`, and others. - ``singledispatchmethod`` always dispatches on the first argument passed at call - time, irrespective of whether the method is bound or unbound. As a result, - calling the method through an instance or through the class may result in - different dispatch behavior. This behavior is required to support correct - dispatch when used with ``staticmethod`` and ``classmethod``. - + For every ``singledispatchmethod`` method defined in a class, the value + dispatched on by that method is *always* the first argument passed for the call. + Therefore, dispatching to regular methods can only be sensibly performed by + calling such a method from instances of the class, and not from the class object. .. versionadded:: 3.8 .. versionchanged:: 3.15 From 44f3295b5e76e63000116e5f1cb8a7dcccb80871 Mon Sep 17 00:00:00 2001 From: priyanshu2282-cyber Date: Tue, 13 Jan 2026 00:08:31 +0530 Subject: [PATCH 5/5] Indentation fixes --- Doc/library/functools.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst index 2709db78aeb311..89f2265deb56ec 100644 --- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -722,6 +722,7 @@ The :mod:`functools` module defines the following functions: dispatched on by that method is *always* the first argument passed for the call. Therefore, dispatching to regular methods can only be sensibly performed by calling such a method from instances of the class, and not from the class object. + .. versionadded:: 3.8 .. versionchanged:: 3.15