Class calling

[onlyme]

BPO	6761
Nosy	@birkenfeld, @vstinner, @bitdancer, @sigmavirus24, @andresdelfino, @miss-islington
PRs	bpo-6761: Fix __call__ documentation #7987 [3.9] bpo-6761: Enhance __call__ documentation (GH-7987) #23004 [3.8] bpo-6761: Enhance __call__ documentation (GH-7987) #23005

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2020-10-27.18:56:34.222>
created_at = <Date 2009-08-22.17:13:57.342>
labels = ['type-bug', '3.8', '3.9', '3.10', 'docs']
title = 'Class calling'
updated_at = <Date 2020-10-27.18:56:34.221>
user = 'https://bugs.python.org/onlyme'

bugs.python.org fields:

activity = <Date 2020-10-27.18:56:34.221>
actor = 'eric.araujo'
assignee = 'docs@python'
closed = True
closed_date = <Date 2020-10-27.18:56:34.222>
closer = 'eric.araujo'
components = ['Documentation']
creation = <Date 2009-08-22.17:13:57.342>
creator = 'onlyme'
dependencies = []
files = []
hgrepos = []
issue_num = 6761
keywords = ['patch']
message_count = 8.0
messages = ['91864', '91920', '91921', '91922', '320670', '379770', '379772', '379774']
nosy_count = 7.0
nosy_names = ['georg.brandl', 'vstinner', 'r.david.murray', 'onlyme', 'icordasc', 'adelfino', 'miss-islington']
pr_nums = ['7987', '23004', '23005']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue6761'
versions = ['Python 3.8', 'Python 3.9', 'Python 3.10']

[onlyme]

From:
http://docs.python.org/reference/datamodel.html#the-standard-type-hierarchy

"Class instances
Class instances are described below. Class instances are callable
only when the class has a __call__() method; x(arguments) is a shorthand
for x.__call__(arguments)."

The following program demonstrates otherwise regarding that last statement.

def call(self):
    print "inserted __call__ in object of class A"

class A(object):
    def __call__(self):
        print "__call__ method in class A"
        
x = A()               # Equates: x = type(A).__call__(A)
x.__call__ = call

x()                   # Calls the method of class A.
x.__call__(x)         # Calls function "call".
type(x).__call__(x)   # The correct longhand of x() IMHO

If I were to rephrase the documentation:
"Class instances
Class instances are described below. Class instances are callable
only when the class has a __call__() method; x(arguments) is a shorthand
for type(x).__call__(x, arguments)."

[onlyme]

On further reading it seems my objections only apply to new style classes.

[bitdancer]

FYI, all special methods are (now) looked up on the type for new style
classes. Your suggested rewrite makes things more confusing, IMO
(partly because to make it accurate it would need to be something like
type(x).__call__(x, *args, **kw), which doesn't really make the sentence
clearer).

So far I haven't thought of a rewording I like. The best I've come up
with is "x(arguments) invokes the __call__ method, passing it the
arguments." This leaves it to other parts of the language spec to
explain how __call__ gets resolved.

Whatever we decide to do, section 3.4.4 will need a similar update.

[bitdancer]

For some reason the 3.2 docs don't contain the sentence you reference,
but they do have the same mistake in section 3.4.4. Which is even more
of a mistake in 3.x, since there are only new style classes there.

[andresdelfino]

The PR uses a slight rewording of David's phrasing.

[vstinner]

New changeset 95f710c by Andre Delfino in branch 'master':
bpo-6761: Enhance __call__ documentation (GH-7987)
95f710c

[miss-islington]

New changeset b1ce044 by Miss Skeleton (bot) in branch '3.8':
bpo-6761: Enhance __call__ documentation (GH-7987)
b1ce044

[miss-islington]

New changeset 2cb259f by Miss Skeleton (bot) in branch '3.9':
bpo-6761: Enhance __call__ documentation (GH-7987)
2cb259f