Improve the doc and indexing of adict.__missing__.

[terryjreedy]

BPO	23006
Nosy	@rhettinger, @terryjreedy, @ethanfurman
Files	missing.diff: initial patch, 3.4

^{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 = None
closed_at = <Date 2014-12-11.00:02:50.064>
created_at = <Date 2014-12-07.20:49:29.870>
labels = ['type-bug', 'docs']
title = 'Improve the doc and indexing of adict.__missing__.'
updated_at = <Date 2014-12-11.00:02:50.063>
user = 'https://github.com/terryjreedy'

bugs.python.org fields:

activity = <Date 2014-12-11.00:02:50.063>
actor = 'terry.reedy'
assignee = 'docs@python'
closed = True
closed_date = <Date 2014-12-11.00:02:50.064>
closer = 'terry.reedy'
components = ['Documentation']
creation = <Date 2014-12-07.20:49:29.870>
creator = 'terry.reedy'
dependencies = []
files = ['37383']
hgrepos = []
issue_num = 23006
keywords = ['patch']
message_count = 4.0
messages = ['232279', '232349', '232454', '232455']
nosy_count = 5.0
nosy_names = ['rhettinger', 'terry.reedy', 'docs@python', 'ethan.furman', 'python-dev']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue23006'
versions = ['Python 2.7', 'Python 3.4', 'Python 3.5']

[terryjreedy]

Currently, the only index entry for __missing__ is "__missing__() (collections.defaultdict method)". This entry should probably not exist -- see bpo-9536, which inspired this issue. The method is not mentioned in the special-methods doc, and the explanation in the dict doc is not indexed. Two suggestions:

https://docs.python.org/3/reference/datamodel.html#emulating-container-types

After __getitem__ entry, add automatically indexed entry, something like

object.__missing__(self, key):
When present in a dict subclass, called by dict.__getitem__ for missing keys.

https://docs.python.org/3/library/stdtypes.html#mapping-types-dict

Before the d[key] paragraph starting "If a subclass of dict defines a method __missing__()" add explicit __missing__ index directive. The last sentence of the paragraph

"See collections.Counter for a complete implementation including other methods helpful for accumulating and managing tallies."

is confusing because the linked entry makes no mention of __missing__ (as it should not). Change sentence to something like

"There are two stdlib dict subclasses that use (different) __missing__ methods as part of their implementation: collections.Counter and collections.defaultdict."

I will work on a patch and try to get the markup correct.

[rhettinger]

These edits look reasonable, useful and correct.

[python-dev]

New changeset 0fe3fb886c38 by Terry Jan Reedy in branch '2.7':
Issue bpo-23006: Improve the documentation and indexing of dict.__missing__.
https://hg.python.org/cpython/rev/0fe3fb886c38

New changeset 31875b244bdf by Terry Jan Reedy in branch '3.4':
Issue bpo-23006: Improve the documentation and indexing of dict.__missing__.
https://hg.python.org/cpython/rev/31875b244bdf

New changeset 41b172fd4479 by Terry Jan Reedy in branch '3.4':
Issue bpo-23006 whitespace
https://hg.python.org/cpython/rev/41b172fd4479

[terryjreedy]

I made a couple more minor revisions to the 3.4 stdtypes text and copied the revised paragraph, with the code example, to 2.7