[Python-checkins] cpython (2.7): Issue #23006: Improve the documentation and indexing of dict.__missing__.
terry.reedy
python-checkins at python.org
Thu Dec 11 00:50:55 CET 2014
https://hg.python.org/cpython/rev/0fe3fb886c38
changeset: 93820:0fe3fb886c38
branch: 2.7
user: Terry Jan Reedy <tjreedy at udel.edu>
date: Wed Dec 10 18:38:07 2014 -0500
summary:
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.
files:
Doc/library/stdtypes.rst | 34 ++++++++++++++++++------
Doc/reference/datamodel.rst | 6 ++++
Misc/NEWS | 5 +++
3 files changed, 36 insertions(+), 9 deletions(-)
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -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 --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -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 --git a/Misc/NEWS b/Misc/NEWS
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -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.
--
Repository URL: https://hg.python.org/cpython
More information about the Python-checkins
mailing list