bpo-6761: Fix __call__ documentation by andresdelfino · Pull Request #7987 · python/cpython

andresdelfino · 2018-06-28T15:07:31Z

https://bugs.python.org/issue6761

vstinner · 2019-01-10T16:04:23Z

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 · 2019-02-23T13:13:45Z

@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 · 2019-02-25T08:31:36Z

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 · 2019-02-25T10:24:12Z

I have made the requested changes; please review again

bedevere-bot · 2019-02-25T10:24:14Z

Thanks for making the requested changes!

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

vstinner

LGTM.

vstinner · 2019-02-25T10:54:54Z

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

vstinner · 2019-02-25T10:56:28Z

"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 · 2019-03-05T23:41:28Z

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 · 2019-03-06T13:40:04Z

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 · 2019-03-07T17:06:55Z

@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 · 2019-03-07T17:22:28Z

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 · 2019-05-13T22:07:39Z


 Called when the instance is "called" as a function; if this method is defined,
-``x(arg1, arg2, ...)`` is a shorthand for ``x.__call__(arg1, arg2, ...)``.
+the class receives the instance and all arguments of the call.


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.

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

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

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).

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

@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 · 2019-06-15T10:40:36Z

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

vstinner

LGTM.

merwok · 2020-10-27T15:10:00Z

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 · 2020-10-27T16:19:02Z

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

(cherry picked from commit 95f710c) Co-authored-by: Andre Delfino <adelfino@gmail.com>

bedevere-bot · 2020-10-27T16:19:15Z

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

(cherry picked from commit 95f710c) Co-authored-by: Andre Delfino <adelfino@gmail.com>

bedevere-bot · 2020-10-27T16:19:23Z

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

vstinner · 2020-10-27T16:19:31Z

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

(cherry picked from commit 95f710c) Co-authored-by: Andre Delfino <adelfino@gmail.com>

…lots1 * origin/master: (365 commits) bpo-42029: Remove IRIX code (pythonGH-23023) bpo-42143: Ensure PyFunction_NewWithQualName() can't fail after creating the func object (pythonGH-22953) bpo-34204: Use pickle.DEFAULT_PROTOCOL in shelve (pythonGH-19639) bpo-41805: Documentation for PEP 585 (pythonGH-22615) bpo-42161: Micro-optimize _collections._count_elements() (pythonGH-23008) bpo-42161: Remove private _PyLong_Zero and _PyLong_One (pythonGH-23003) bpo-42099: Fix reference to ob_type in unionobject.c and ceval (pythonGH-22829) bpo-41659: Disallow curly brace directly after primary (pythonGH-22996) bpo-6761: Enhance __call__ documentation (pythonGH-7987) bpo-42161: Modules/ uses _PyLong_GetZero() and _PyLong_GetOne() (pythonGH-22998) bpo-41474, Makefile: Add dependency on cpython/frameobject.h (pythonGH-22999) bpo-42157: Rename unicodedata.ucnhash_CAPI (pythonGH-22994) bpo-42161: Use _PyLong_GetZero() and _PyLong_GetOne() (pythonGH-22995) bpo-30681: Support invalid date format or value in email Date header (pythonGH-22090) bpo-42161: Add _PyLong_GetZero() and _PyLong_GetOne() (pythonGH-22993) bpo-42123: Run the parser two times and only enable invalid rules on the second run (pythonGH-22111) bpo-42157: Convert unicodedata.UCD to heap type (pythonGH-22991) bpo-42157: unicodedata avoids references to UCD_Type (pythonGH-22990) bpo-39101: Fixes BaseException hang in IsolatedAsyncioTestCase. (pythonGH-22654) bpo-1635741: _PyUnicode_Name_CAPI moves to internal C API (pythonGH-22713) ...

andresdelfino added 2 commits June 28, 2018 11:59

bpo-6761: Fix __call__ documentation
c0da865

Minor fix
6a4e251

the-knights-who-say-ni added the CLA signed label Jun 28, 2018

bedevere-bot added the awaiting review label Jun 28, 2018

andresdelfino added 3 commits June 28, 2018 12:55

Minor change
b4880e0

Minor change
6235331

Update datamodel.rst
a671714

serhiy-storchaka added needs backport to 3.6 docs Documentation in the Doc dir skip news labels Nov 7, 2018

serhiy-storchaka requested a review from bitdancer November 7, 2018 17:34

vstinner removed the needs backport to 3.6 label Jan 10, 2019

vstinner requested changes Feb 25, 2019
View reviewed changes

bedevere-bot removed the awaiting review label Feb 25, 2019

bedevere-bot added the awaiting changes label Feb 25, 2019

Address comment from Victor
860857d

bedevere-bot added awaiting change review and removed awaiting changes labels Feb 25, 2019

vstinner approved these changes Feb 25, 2019
View reviewed changes

bedevere-bot added awaiting merge and removed awaiting change review labels Feb 25, 2019

Address comment from Cheryl
73b5422

mblahay reviewed May 13, 2019
View reviewed changes

JulienPalard removed the needs backport to 2.7 label Sep 10, 2019

gpshead added the needs backport to 3.8 label Sep 12, 2019

Update datamodel.rst
26cebc5

vstinner approved these changes Oct 27, 2020
View reviewed changes

merwok approved these changes Oct 27, 2020
View reviewed changes

merwok added needs backport to 3.9 and removed needs backport to 3.7 labels Oct 27, 2020

vstinner merged commit 95f710c into python:masterOct 27, 2020

bedevere-bot removed the awaiting merge label Oct 27, 2020

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Oct 27, 2020
bpo-6761: Enhance __call__ documentation (pythonGH-7987)
184e985
(cherry picked from commit 95f710c) Co-authored-by: Andre Delfino <adelfino@gmail.com>

bedevere-bot removed the needs backport to 3.9 label Oct 27, 2020

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Oct 27, 2020
bpo-6761: Enhance __call__ documentation (pythonGH-7987)
ecd4359
(cherry picked from commit 95f710c) Co-authored-by: Andre Delfino <adelfino@gmail.com>

bedevere-bot removed the needs backport to 3.8 label Oct 27, 2020

miss-islington added a commit that referenced this pull request Oct 27, 2020
bpo-6761: Enhance __call__ documentation (GH-7987)
b1ce044
(cherry picked from commit 95f710c) Co-authored-by: Andre Delfino <adelfino@gmail.com>

miss-islington added a commit that referenced this pull request Oct 27, 2020
bpo-6761: Enhance __call__ documentation (GH-7987)
2cb259f
(cherry picked from commit 95f710c) Co-authored-by: Andre Delfino <adelfino@gmail.com>

andresdelfino deleted the bpo-6761-call-method branch October 27, 2020 16:51

adorilson pushed a commit to adorilson/cpython that referenced this pull request Mar 13, 2021
bpo-6761: Enhance __call__ documentation (pythonGH-7987)
fbbf2f6

Uh oh!

Uh oh!

Conversation

andresdelfino commented Jun 28, 2018• edited by bedevere-bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vstinner commented Jan 10, 2019

Uh oh!

andresdelfino commented Feb 23, 2019

Uh oh!

vstinner left a comment

Choose a reason for hiding this comment

Uh oh!

bedevere-bot commented Feb 25, 2019

Uh oh!

andresdelfino commented Feb 25, 2019

Uh oh!

bedevere-bot commented Feb 25, 2019

Uh oh!

vstinner left a comment

Choose a reason for hiding this comment

Uh oh!

vstinner commented Feb 25, 2019

Uh oh!

vstinner commented Feb 25, 2019

Uh oh!

andresdelfino commented Mar 5, 2019

Uh oh!

csabella commented Mar 6, 2019

Uh oh!

andresdelfino commented Mar 7, 2019

Uh oh!

vstinner commented Mar 7, 2019• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mblahayMay 13, 2019

Choose a reason for hiding this comment

Uh oh!

andresdelfinoJun 15, 2019

Choose a reason for hiding this comment

Uh oh!

JulienPalardSep 10, 2019

Choose a reason for hiding this comment

Uh oh!

merwokOct 23, 2020

Choose a reason for hiding this comment

Uh oh!

andresdelfinoOct 23, 2020

Choose a reason for hiding this comment

Uh oh!

merwokOct 23, 2020

Choose a reason for hiding this comment

Uh oh!

andresdelfino commented Jun 15, 2019• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vstinner left a comment

Choose a reason for hiding this comment

Uh oh!

merwok commented Oct 27, 2020

Uh oh!

miss-islington commented Oct 27, 2020

Uh oh!

bedevere-bot commented Oct 27, 2020

Uh oh!

bedevere-bot commented Oct 27, 2020

Uh oh!

vstinner commented Oct 27, 2020

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

11 participants

andresdelfino commented Jun 28, 2018•
edited by bedevere-bot
Loading

vstinner commented Mar 7, 2019•
edited
Loading

andresdelfino commented Jun 15, 2019•
edited
Loading