bpo-6761: Fix call documentation #7987

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

Doc/reference/datamodel.rst

@@ -2108,7 +2108,7 @@ Emulating callable objects
   .. index:: pair: call; instance

   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 <[email protected]>

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 <[email protected]>

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 <[email protected]>

…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 only security fixes and removed needs backport to 3.7 labels Oct 27, 2020

vstinner merged commit 95f710c into python:master Oct 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 <[email protected]>

bedevere-bot removed the needs backport to 3.9 only security fixes 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 <[email protected]>

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 <[email protected]>

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 <[email protected]>

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

bpo-6761: Fix call documentation #7987

bpo-6761: Fix call documentation #7987

andresdelfino commented Jun 28, 2018 •

edited by bedevere-bot

Loading

vstinner commented Jan 10, 2019

andresdelfino commented Feb 23, 2019

vstinner left a comment

bedevere-bot commented Feb 25, 2019

andresdelfino commented Feb 25, 2019

bedevere-bot commented Feb 25, 2019

vstinner left a comment

vstinner commented Feb 25, 2019

vstinner commented Feb 25, 2019

andresdelfino commented Mar 5, 2019

csabella commented Mar 6, 2019

andresdelfino commented Mar 7, 2019

vstinner commented Mar 7, 2019 •

edited

Loading

mblahay May 13, 2019

andresdelfino Jun 15, 2019

JulienPalard Sep 10, 2019

merwok Oct 23, 2020

andresdelfino Oct 23, 2020

merwok Oct 23, 2020

andresdelfino commented Jun 15, 2019 •

edited

Loading

vstinner left a comment

merwok commented Oct 27, 2020

miss-islington commented Oct 27, 2020

bedevere-bot commented Oct 27, 2020

bedevere-bot commented Oct 27, 2020

vstinner commented Oct 27, 2020

bpo-6761: Fix __call__ documentation #7987

bpo-6761: Fix __call__ documentation #7987

Conversation

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

vstinner commented Jan 10, 2019

andresdelfino commented Feb 23, 2019

vstinner left a comment

Choose a reason for hiding this comment

bedevere-bot commented Feb 25, 2019

andresdelfino commented Feb 25, 2019

bedevere-bot commented Feb 25, 2019

vstinner left a comment

Choose a reason for hiding this comment

vstinner commented Feb 25, 2019

vstinner commented Feb 25, 2019

andresdelfino commented Mar 5, 2019

csabella commented Mar 6, 2019

andresdelfino commented Mar 7, 2019

vstinner commented Mar 7, 2019 • edited Loading

mblahay May 13, 2019

Choose a reason for hiding this comment

andresdelfino Jun 15, 2019

Choose a reason for hiding this comment

JulienPalard Sep 10, 2019

Choose a reason for hiding this comment

merwok Oct 23, 2020

Choose a reason for hiding this comment

andresdelfino Oct 23, 2020

Choose a reason for hiding this comment

merwok Oct 23, 2020

Choose a reason for hiding this comment

andresdelfino commented Jun 15, 2019 • edited Loading

vstinner left a comment

Choose a reason for hiding this comment

merwok commented Oct 27, 2020

miss-islington commented Oct 27, 2020

bedevere-bot commented Oct 27, 2020

bedevere-bot commented Oct 27, 2020

vstinner commented Oct 27, 2020

bpo-6761: Fix call documentation #7987

bpo-6761: Fix call documentation #7987

andresdelfino commented Jun 28, 2018 •

edited by bedevere-bot

Loading

vstinner commented Mar 7, 2019 •

edited

Loading

andresdelfino commented Jun 15, 2019 •

edited

Loading