classification
Title: defaultdict doc makes incorrect reference to __missing__ method
Type: behavior Stage: resolved
Components: Documentation Versions: Python 2.7
process
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: docs@python, ethan.furman, ezio.melotti, jjposner, r.david.murray, rhettinger, terry.reedy
Priority: normal Keywords: patch

Created on 2010-08-06 14:55 by jjposner, last changed 2014-12-12 17:04 by berker.peksag. This issue is now closed.

Files
File name Uploaded Description Edit
defaultdict.patch jjposner, 2010-08-06 14:55 SVN diff of library/collections.rst review
Messages (7)
msg113105 - (view) Author: John Posner (jjposner) * Date: 2010-08-06 14:55
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.
msg113140 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2010-08-06 22:02
I believe the description of __missing__ is there for those who want to subclass defaultdict, but I'll let Raymond confirm.
msg113269 - (view) Author: John Posner (jjposner) * Date: 2010-08-08 14:40
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.
msg113270 - (view) Author: John Posner (jjposner) * Date: 2010-08-08 14:43
On python-list, Wolfram Hinderer objected to the proposed patch's calling __missing__ a "special method".
msg232281 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2014-12-07 21:02
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.
msg232359 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2014-12-09 10:09
[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).
msg232366 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2014-12-09 10:42
http://svn.python.org/view/python/branches/release25-maint/Doc/lib/libcollections.tex?r1=38658&r2=42573
History
Date User Action Args
2014-12-12 17:04:37berker.peksagsetstage: needs patch -> resolved
2014-12-12 08:00:36rhettingersetstatus: open -> closed
resolution: rejected
2014-12-09 10:42:44rhettingersetmessages: + msg232366
2014-12-09 10:09:15rhettingersetassignee: docs@python -> rhettinger
messages: + msg232359
2014-12-07 21:02:30terry.reedysetnosy: + terry.reedy
messages: + msg232281

resolution: not a bug -> (no value)
stage: resolved -> needs patch
2014-12-07 20:02:51ethan.furmansetnosy: + ethan.furman
2013-01-30 06:39:29ezio.melottisetstatus: pending -> open
nosy: + ezio.melotti
2010-08-08 14:44:40jjposnersetstatus: open -> pending
2010-08-08 14:43:56jjposnersetmessages: + msg113270
2010-08-08 14:40:23jjposnersetstatus: pending -> open

messages: + msg113269
2010-08-06 22:02:13r.david.murraysetstatus: open -> pending

type: behavior

nosy: + rhettinger, r.david.murray
messages: + msg113140
resolution: not a bug
stage: resolved
2010-08-06 14:55:26jjposnercreate