gh-143535: Document dispatch behavior of singledispatchmethod #143592
Conversation
|
All commit authors signed the Contributor License Agreement. |
Doc/library/functools.rst
Outdated
| @neg.register | ||
| def _(self, arg: bool): | ||
| return not arg | ||
| .. note:: |
There was a problem hiding this comment.
- Don't use a note.
- Put the paragraph after we mention the behavior of classmethod/staticmethod
- Don't write
x.f(a) != C.f(x,a)it's confusing and ca be wrong.
There was a problem hiding this comment.
Thanks for the clarification, I will remove the note and describe the behaviour in paragraph format, in text. I will update the PR shortly.
|
A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated. Once you have made the requested changes, please leave a comment on this pull request containing the phrase |
|
I have made the requested changes; please review again. |
|
Thanks for making the requested changes! @picnixz: please review the changes made to this pull request. |
| ``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``. | ||
|
|
There was a problem hiding this comment.
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
staticmethodandclassmethod.
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):
| ``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. |
There was a problem hiding this comment.
@picnixz, do you like this wording? Do you have a better idea?
3 participants
The PR clarifies the behavior of
singledispatchmethodin the documentation. It always dispatches the first argument during call, regardless of whether the method is bound or unbound, as a resultxf(a)!=c.f(x,a). The behavior is intentional and required to support correct dispatch forstaticmethodandclassmethod.singledispatchmethoddispatches on theselfargument when invoked from class level #143535📚 Documentation preview 📚: https://cpython-previews--143592.org.readthedocs.build/