[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).