bpo-6761: Fix __call__ documentation

[andresdelfino]

https://bugs.python.org/issue6761

[vstinner]

I removed the " needs backport to 3.6" label, the 3.6 branch no longer accept bugfixes (only security fixes are accepted): https://devguide.python.org/#status-of-python-branches

[andresdelfino]

@bitdancer could you take a look at this?

[vstinner]

I prefer (arg1, arg2, ...) syntax rather than (arguments) syntax: IMHO (arg1, arg2, ...) is more explicit.

[bedevere-bot]

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. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

[andresdelfino]

I have made the requested changes; please review again

[bedevere-bot]

Thanks for making the requested changes!

@vstinner: please review the changes made to this pull request.

[vstinner]

LGTM.

[vstinner]

@csabella@JulienPalard: Would you mind to double check and/or merge this PR?

[vstinner]

"needs backport 2.7"

I'm not super excited by continuing to enhance the 2.7 doc. IMHO it's good as it is. I mean, we are close to Python 2 end of life, and I prefer to read Python 3 doc to write Python 2 code. Well, it's just a comment, I'm also fine with backport to 2.7 if you want (but I expect a conflict).

[andresdelfino]

This patch isn't incorrect, however, I'm wondering if something else is needed.

Looking at the original bug ticket, @bitdancer makes the point:

FYI, all special methods are (now) looked up on the type for new style classes.

Taking this a step further, I tried the original example from the tracker with __str__ instead of __call__ and it produced the same result (of proving David's point about special methods being looked up on type(x) instead of x.

This is already defined in the intro of this entire 3.3 section:

For instance, if a class defines a method named __getitem__(), and x is an instance of this class, then x[i] is roughly equivalent to type(x).__getitem__(x, i).

I'm wondering if the object.__call__ section should define what it does without referencing the x. The other sections (like __str__) avoid using an example instance.

I think you are right. Could you take a look at the new wording?

[csabella]

I'm definitely not the one who would be able to have the final say on the wording for this, but I wonder if something like this would work:

Called by ``object(arg1, arg2, ...)`` or an equivalent (such as a decorator) to invoke the instance as a function call. 

[andresdelfino]

@vstinner could you take a look on the new wording I wrote based on Cheryl's comments on #7987 (comment) and also Cheryl's proposed wording on #7987 (comment) and tell us what you think?

[vstinner]

For me, obj(arg1, arg2, ...) is equivalant to (obj.__class__).__call__(obj, arg1, arg2, ...).

Usually, it's also equivalent to type(obj).__call__(arg1, arg2, ...), but I would prefer to use type() in the doc, since technically the builtin function can be overriden or a global variable with the same name can be defined.

[mblahay]

I know what is supposed to be conveyed here, and I find this more confusing than the original. Diving into the internals of how calls to instance methods work is detracting from the discussion of what call does.

[andresdelfino]

Thanks for your insight! Before doing any changes, I'll wait for @bitdancer to give his input.

[JulienPalard]

This current version don't work for me, "if this method is defined, the class receives the instance and all arguments of the call." looks wrong, It's not the class that receives the instance and all arguments.

I'd propose something like:

Called when the instance is "called" as a function. Receives the instance and the function parameters.

If you want to almost keep the example you could add something like:

So ``obj(arg1, arg2, ...)`` calls ``__call__(arg1, arg2, ...)`` on ``obj``.

[merwok]

I don’t think that last suggestion (from Julien) works (call on obj?).

type(x).__call__(x, arg1, ...) is closer to what happens, and the call matches the way the method is defined (with a self parameter).

[andresdelfino]

@merwok I agree. Made a change based on your suggestion, what do you think?

[merwok]

@vstinner You said «I would prefer to [not] use type() in the doc, since technically the builtin function can be overriden» → that’s what we say «roughly»! Is the latest version good for you or you would prefer obj.__class__.__call__(obj, etc)?

@csabella I’m not sure I understand your review; could you comment on the latest version? Thanks!

[andresdelfino]

@bitdancer Could you check the proposed wording out and comment? :)

[vstinner]

LGTM.

[merwok]

I updated the backports labels to get 3.9 and 3.8, and I think this is ready to merge unless another reviewer weighs in.

[miss-islington]

Thanks @andresdelfino for the PR, and @vstinner for merging it 🌮🎉.. I'm working now to backport this PR to: 3.8, 3.9.
🐍🍒⛏🤖

[bedevere-bot]

GH-23004 is a backport of this pull request to the 3.9 branch.

[bedevere-bot]

GH-23005 is a backport of this pull request to the 3.8 branch.

[vstinner]

Thanks @andresdelfino! It's a nice documentation enhancement. I'm fine with "roughly" ;-)