[issue9536] defaultdict doc makes incorrect reference to __missing__ method
New submission from John Posner jjposner@optimum.net:
The documentation for collections.defaultdict is confusing with respect to the __missing__ method. The fact is that a programmer using defaultdict does not need to know anything about __missing__.
The attached patch contains a rewrite of the entire section (but not the "defaultdict Examples" section, which is fine.
---------- assignee: docs@python components: Documentation files: defaultdict.patch keywords: patch messages: 113105 nosy: docs@python, jjposner priority: normal severity: normal status: open title: defaultdict doc makes incorrect reference to __missing__ method versions: Python 2.7 Added file: http://bugs.python.org/file18417/defaultdict.patch
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9536 _______________________________________
R. David Murray rdmurray@bitdance.com added the comment:
I believe the description of __missing__ is there for those who want to subclass defaultdict, but I'll let Raymond confirm.
---------- nosy: +r.david.murray, rhettinger resolution: -> invalid stage: -> committed/rejected status: open -> pending type: -> behavior
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9536 _______________________________________
John Posner jjposner@optimum.net added the comment:
I think it would be confusing to create of subclass of defaultdict, defining a __missing__ method in that subclass. The existence of the __missing__ method would cancel the main functionality of the defaultdict object: invoking the "default value factory" callable.
I think it would be better to encourage programmers to subclass dict directly, instead of subclassing defaultdict.
---------- status: pending -> open
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9536 _______________________________________
John Posner jjposner@optimum.net added the comment:
On python-list, Wolfram Hinderer objected to the proposed patch's calling __missing__ a "special method".
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9536 _______________________________________
Changes by John Posner jjposner@optimum.net:
---------- status: open -> pending
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9536 _______________________________________
Changes by Ezio Melotti ezio.melotti@gmail.com:
---------- nosy: +ezio.melotti status: pending -> open
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9536 _______________________________________
Changes by Ethan Furman ethan@stoneleaf.us:
---------- nosy: +ethan.furman
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9536 _______________________________________
Terry J. Reedy added the comment:
I agree that the patch is not acceptable as is. The public attribute *defaultdict* should be explicitly documented as it is now, so that it is indexed. On the other hand, users should not directly call .__missing__, and it is not normal to document the private special method implementation of classes. For example, a collections.Counter returns 0 for missing keys but the doc makes no mention of .__missing__ as the implementation. It simply describe how a counter works.
John is correct that people writing other subclasses with __missing__ should usually subclass dict. This might be clearer if that special method were properly documented and indexed. I opened #23006 for this.
---------- nosy: +terry.reedy resolution: not a bug -> stage: resolved -> needs patch
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9536 _______________________________________
Raymond Hettinger added the comment:
[John Posner]
The fact is that a programmer using defaultdict does not need to know anything about __missing__.
I disagree. It seems to help people understand the defaultdict which otherwise seems more magical that it actually is. Also, it is a part of the description of how the default_factory attribute is used. Further, it helps explain why the factory is only called by __getitem__ rather than by get() or other methods.
[David Murray]
I believe the description of __missing__ is there for those who want to subclass defaultdict, but I'll let Raymond confirm.
Yes, it serves that purpose but it also serves to make clear what the actual mechanics are for the defaultdict. I think there is no downside to keeping the current wording which provides some insights and hasn't seemed to cause any problems in practice (this has been around since Python 2.5).
Terry's proposed changes in issue 23006 do seem like a good idea.
I recommend against OP's proposed patch or any variant of it. That patch is predicated on the notion that __missing__ is an irrelevant, unnecessary, and confusing implementation detail. I don't agree that sentiment at all.
Please keep in mind that this part of the documentation was written by Guido van Rossum and it clearly expresses what he had it mind when he implemented the defaultdict back in 2006. I really don't think we should throw away this text because 8 or 9 years later John has opined that Guido was fundamentally misguided when he wrote the documentation (back in the days when the docs were all in TeX markup).
---------- assignee: docs@python -> rhettinger
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9536 _______________________________________
Raymond Hettinger added the comment:
http://svn.python.org/view/python/branches/release25-maint/Doc/lib/libcollec...
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9536 _______________________________________
Changes by Raymond Hettinger raymond.hettinger@gmail.com:
---------- resolution: -> rejected status: open -> closed
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9536 _______________________________________
Changes by Berker Peksag berker.peksag@gmail.com:
---------- stage: needs patch -> resolved
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9536 _______________________________________
participants (7)
-
Berker Peksag -
Ethan Furman
-
Ezio Melotti
-
John Posner
-
R. David Murray
-
Raymond Hettinger
-
Terry J. Reedy