[issue23006] Improve the doc and indexing of adict.__missing__.
New submission from Terry J. Reedy:
Currently, the only index entry for __missing__ is "__missing__() (collections.defaultdict method)". This entry should probably not exist -- see #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.
----------
assignee: docs@python
components: Documentation
messages: 232279
nosy: docs@python, terry.reedy
priority: normal
severity: normal
stage: needs patch
status: open
title: Improve the doc and indexing of adict.__missing__.
type: behavior
versions: Python 2.7, Python 3.4, Python 3.5
_______________________________________
Python tracker
Changes by Terry J. Reedy
Changes by Ethan Furman
Raymond Hettinger added the comment:
These edits look reasonable, useful and correct.
----------
nosy: +rhettinger
_______________________________________
Python tracker
Roundup Robot added the comment:
New changeset 0fe3fb886c38 by Terry Jan Reedy in branch '2.7':
Issue #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 #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 #23006 whitespace
https://hg.python.org/cpython/rev/41b172fd4479
----------
nosy: +python-dev
_______________________________________
Python tracker
Terry J. Reedy added the comment:
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
----------
resolution: -> fixed
stage: needs patch -> resolved
status: open -> closed
_______________________________________
Python tracker
participants (4)
-
Ethan Furman
-
Raymond Hettinger
-
Roundup Robot
-
Terry J. Reedy