Skip to content

gh-143535: Document dispatch behavior of singledispatchmethod #143592

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
priyanshu2282-cyber wants to merge 4 commits into
base: main
Choose a base branch
from
+6 −0
Open

gh-143535: Document dispatch behavior of singledispatchmethod #143592

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
666a2a8
gh-143535: Document dispatch behavior of singledispatchmethod
priyanshu2282-cyber Jan 9, 2026
ea2fda1
gh-143535: Move singledispatchmethod note outside example block
priyanshu2282-cyber Jan 9, 2026
119a4b1
Merge branch 'main' into doc-singledispatchmethod-dispatch
priyanshu2282-cyber Jan 9, 2026
2834c45
gh-143535: Clarify dispatch semantics of singledispatchmethod
priyanshu2282-cyber Jan 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions Doc/library/functools.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -718,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``.

Comment on lines +721 to +726
Copy link
Member

@johnslavik johnslavik Jan 12, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not clear what "the method" in the first sentence refers to.

As a result, calling the method through an instance or through the class may result in different dispatch behavior.

Exact opposite: it's the same dispatch behavior, but a potentially surprising dispatch result.

This behavior is required to support correct dispatch when used with staticmethod and classmethod.

I assume this is a detail that's not necessary for the reader who's just figuring out singledispatchmethod.
Let's not include it.

My suggestion (click "Commit suggestion" to apply it directly):

Suggested change
``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.

Copy link
Member

@johnslavik johnslavik Jan 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@picnixz, do you like this wording? Do you have a better idea?

.. versionadded:: 3.8

.. versionchanged:: 3.15
Expand Down
Loading