Skip to content

defaultdict doc makes incorrect reference to __missing__ method #53745

Closed

Description

@jjposner
mannequin
BPO 9536
Nosy @rhettinger, @terryjreedy, @ezio-melotti, @bitdancer, @ethanfurman
Files
  • defaultdict.patch: SVN diff of library/collections.rst
  • 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 = 'https://github.com/rhettinger'
    closed_at = <Date 2014-12-12.08:00:36.804>
    created_at = <Date 2010-08-06.14:55:26.569>
    labels = ['type-bug', 'docs']
    title = 'defaultdict doc makes incorrect reference to __missing__ method'
    updated_at = <Date 2014-12-12.17:04:37.673>
    user = 'https://bugs.python.org/jjposner'

    bugs.python.org fields:

    activity = <Date 2014-12-12.17:04:37.673>
    actor = 'berker.peksag'
    assignee = 'rhettinger'
    closed = True
    closed_date = <Date 2014-12-12.08:00:36.804>
    closer = 'rhettinger'
    components = ['Documentation']
    creation = <Date 2010-08-06.14:55:26.569>
    creator = 'jjposner'
    dependencies = []
    files = ['18417']
    hgrepos = []
    issue_num = 9536
    keywords = ['patch']
    message_count = 7.0
    messages = ['113105', '113140', '113269', '113270', '232281', '232359', '232366']
    nosy_count = 7.0
    nosy_names = ['rhettinger', 'terry.reedy', 'ezio.melotti', 'r.david.murray', 'jjposner', 'docs@python', 'ethan.furman']
    pr_nums = []
    priority = 'normal'
    resolution = 'rejected'
    stage = 'resolved'
    status = 'closed'
    superseder = None
    type = 'behavior'
    url = 'https://bugs.python.org/issue9536'
    versions = ['Python 2.7']

    Activity

    1. jjposner commented on Aug 6, 2010

      jjposnermannequin
      MannequinAuthor

      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.

    2. bitdancer commented on Aug 6, 2010

      @bitdancer
      Member

      I believe the description of __missing__ is there for those who want to subclass defaultdict, but I'll let Raymond confirm.

    3. jjposner commented on Aug 8, 2010

      jjposnermannequin
      MannequinAuthor

      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.

    4. jjposner commented on Aug 8, 2010

      jjposnermannequin
      MannequinAuthor

      On python-list, Wolfram Hinderer objected to the proposed patch's calling __missing__ a "special method".

    5. terryjreedy commented on Dec 7, 2014

      @terryjreedy
      Member

      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 bpo-23006 for this.

    6. rhettinger commented on Dec 9, 2014

      @rhettinger
      Contributor

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

    7. transferred this issue fromon Apr 10, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

    Metadata

    Metadata

    Assignees

    Labels

    docsDocumentation in the Doc dirtype-bugAn unexpected behavior, bug, or error

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions