changeset:   93820:0fe3fb886c38
branch:      2.7
user:        Terry Jan Reedy <tjreedy@udel.edu>
date:        Wed Dec 10 18:38:07 2014 -0500
files:       Doc/library/stdtypes.rst Doc/reference/datamodel.rst Misc/NEWS
description:
Issue #23006: Improve the documentation and indexing of dict.__missing__.
Add an entry in the language datamodel special methods section.
Revise and index its discussion in the stdtypes mapping/dict section.
Backport the code example from 3.4.


diff -r aeeec8a4b9b8 -r 0fe3fb886c38 Doc/library/stdtypes.rst
--- a/Doc/library/stdtypes.rst	Wed Dec 10 23:05:33 2014 +0200
+++ b/Doc/library/stdtypes.rst	Wed Dec 10 18:38:07 2014 -0500
@@ -2031,16 +2031,32 @@
       Return the item of *d* with key *key*.  Raises a :exc:`KeyError` if *key*
       is not in the map.
 
+      .. index:: __missing__()
+
+      If a subclass of dict defines a method :meth:`__missing__` and *key*
+      is not present, the ``d[key]`` operation calls that method with the key *key*
+      as argument.  The ``d[key]`` operation then returns or raises whatever is
+      returned or raised by the ``__missing__(key)`` call.
+      No other operations or methods invoke :meth:`__missing__`. If
+      :meth:`__missing__` is not defined, :exc:`KeyError` is raised.
+      :meth:`__missing__` must be a method; it cannot be an instance variable::
+
+          >>> class Counter(dict):
+          ...     def __missing__(self, key):
+          ...         return 0
+          >>> c = Counter()
+          >>> c['red']
+          0
+          >>> c['red'] += 1
+          >>> c['red']
+          1
+
+      The example above shows part of the implementation of
+      :class:`collections.Counter`.  A different ``__missing__`` method is used
+      by :class:`collections.defaultdict`.
+
       .. versionadded:: 2.5
-         If a subclass of dict defines a method :meth:`__missing__`, if the key
-         *key* is not present, the ``d[key]`` operation calls that method with
-         the key *key* as argument.  The ``d[key]`` operation then returns or
-         raises whatever is returned or raised by the ``__missing__(key)`` call
-         if the key is not present. No other operations or methods invoke
-         :meth:`__missing__`. If :meth:`__missing__` is not defined,
-         :exc:`KeyError` is raised.  :meth:`__missing__` must be a method; it
-         cannot be an instance variable. For an example, see
-         :class:`collections.defaultdict`.
+         Recognition of __missing__ methods of dict subclasses.
 
    .. describe:: d[key] = value
 
diff -r aeeec8a4b9b8 -r 0fe3fb886c38 Doc/reference/datamodel.rst
--- a/Doc/reference/datamodel.rst	Wed Dec 10 23:05:33 2014 +0200
+++ b/Doc/reference/datamodel.rst	Wed Dec 10 18:38:07 2014 -0500
@@ -1904,6 +1904,12 @@
       indexes to allow proper detection of the end of the sequence.
 
 
+.. method:: object.__missing__(self, key)
+
+   Called by :class:`dict`\ .\ :meth:`__getitem__` to implement ``self[key]`` for dict subclasses
+   when key is not in the dictionary.
+
+
 .. method:: object.__setitem__(self, key, value)
 
    Called to implement assignment to ``self[key]``.  Same note as for
diff -r aeeec8a4b9b8 -r 0fe3fb886c38 Misc/NEWS
--- a/Misc/NEWS	Wed Dec 10 23:05:33 2014 +0200
+++ b/Misc/NEWS	Wed Dec 10 18:38:07 2014 -0500
@@ -30,6 +30,11 @@
 Documentation
 -------------
 
+- Issue #23006: Improve the documentation and indexing of dict.__missing__.
+  Add an entry in the language datamodel special methods section.
+  Revise and index its discussion in the stdtypes mapping/dict section.
+  Backport the code example from 3.4.
+
 - Issue #21514: The documentation of the json module now refers to new JSON RFC
   7159 instead of obsoleted RFC 4627.