classification
Title: Wrong function calls and referring to not removed concepts in descriptor HowTo (documentation)
Type: Stage: needs patch
Components: Documentation Versions: Python 3.7, Python 3.6, Python 3.5
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: David Becher, Mariatta, dholth, docs@python, eryksun, marco.buttu, martin.panter, rhettinger
Priority: normal Keywords:

Created on 2015-10-18 18:49 by David Becher, last changed 2017-09-25 08:18 by rhettinger.

Files
File name Uploaded Description Edit
21.diff.txt David Becher, 2015-10-18 18:49 review
Messages (11)
msg253159 - (view) Author: David Becher (David Becher) Date: 2015-10-18 18:49
Since Python 3 removed unbound methods, I found some references using the old terminology in this HowTo about descriptors (https://docs.python.org/3/howto/descriptor.html). Also, since unbound methods have been removed, the function call types.MethodType now only takes two arguments, namely the function to bind and the object to bind to. In the current documentation, however, the old function call with three arguments is still being used.

I made a pull request on github, then I realized that it is just a mirror repo. Attached you will see a patch file with some of the obvious changes that could me made to the document
msg253165 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-10-19 00:40
Thanks for the patch. I left a few comments on the code review. I think the class is meant to represent a real function object, not a wrapper. And it would be good to update the following paragraphs about unbound methods.

Also, it looks like the rest of that page could do with some other updates. E.g. no need for explicit Function(object) base class, no need to mention that a method exists in Python 2.3, code could use @classmethod decorator syntax. But these are a slightly separate issues.
msg253168 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-10-19 03:29
Also further up the page, “unbound methods . . . are . . . based on the descriptor protocol” is probably not really correct or useful. Issue 23702 is already open about mentioning unbound methods.
msg253202 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2015-10-20 02:55
I'll update this document to reflect the current state of the world.
msg270007 - (view) Author: Daniel Holth (dholth) Date: 2016-07-08 19:38
This bit me also. Is there other documentation for how many arguments MethodType() should take?
msg270014 - (view) Author: Eryk Sun (eryksun) * Date: 2016-07-08 23:01
I'm surprised it's not documented for the types module:

https://docs.python.org/3.5/library/types.html#types.MethodType

At least the docstring has the parameters:

    >>> print(types.MethodType.__doc__)
    method(function, instance)
    
    Create a bound instance method object.
msg293162 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2017-05-06 14:23
Raymond I suggest you unassign this and let others work on it.
msg293163 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2017-05-06 15:15
I will have a chance to work on this before long.
msg293237 - (view) Author: Marco Buttu (marco.buttu) * Date: 2017-05-08 15:15
I also noticed that the howto differentiates between objects and classes:

"The details of invocation depend on whether obj is an object or a class."

I think it is misleading, because a class is actually an object.  IMHO is better to differentiate between classes and non-classes objects:

"The details of invocation depend on whether obj is a class or not."
msg293252 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2017-05-08 20:28
> I think it is misleading, because a class is actually an object.

This is only misleading *after* you know all the interesting details about Python and metaclasses.  Prior to that, it is a reasonable and important distinction that I don't want to get lost in weasel words.   The calls from object.__getattribute__ are different that those from type.__getattribute__.  Likewise, data and non-data descriptors can only be described in terms of objects versus classes.  Lastly, descriptors only work when stored in a class, if you store them in instances, they don't get invoked.
msg302921 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2017-09-25 08:18
I've just updated the section on unbound methods.  I'll be working on a number of other improvements over the next few weeks and will incorporate the suggested changes where appropriate.
History
Date User Action Args
2017-09-25 08:18:42rhettingersetmessages: + msg302921
2017-09-25 08:15:17rhettingerunlinkissue23702 dependencies
2017-05-08 20:28:45rhettingersetmessages: + msg293252
2017-05-08 15:15:13marco.buttusetnosy: + marco.buttu
messages: + msg293237
2017-05-06 15:15:56rhettingersetmessages: + msg293163
2017-05-06 14:45:05Mariattasetversions: + Python 3.7, - Python 3.4
2017-05-06 14:23:47martin.pantersetmessages: + msg293162
stage: patch review -> needs patch
2016-10-03 06:05:23Mariattasetnosy: + Mariatta
2016-07-08 23:01:12eryksunsetnosy: + eryksun
messages: + msg270014
2016-07-08 19:38:07dholthsetnosy: + dholth
messages: + msg270007
2015-10-20 02:55:22rhettingersetmessages: + msg253202
2015-10-20 02:54:39rhettingersetassignee: docs@python -> rhettinger
2015-10-19 03:29:04martin.pantersetmessages: + msg253168
2015-10-19 03:26:18martin.panterlinkissue23702 dependencies
2015-10-19 00:40:46martin.pantersetversions: + Python 3.4, Python 3.5
nosy: + martin.panter

messages: + msg253165

stage: patch review
2015-10-18 18:54:57SilentGhostsetnosy: + rhettinger
2015-10-18 18:49:49David Bechercreate