diff options
| -rw-r--r-- | Doc/library/stdtypes.rst | 34 | ||||
| -rw-r--r-- | Doc/reference/datamodel.rst | 6 | ||||
| -rw-r--r-- | Misc/NEWS | 5 |
3 files changed, 36 insertions, 9 deletions
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index fa4304c..bc437a4 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -2031,16 +2031,32 @@ pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098: 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 index 206853b..5a6c763 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -1904,6 +1904,12 @@ sequences, it should iterate through the values. 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 @@ -30,6 +30,11 @@ Library 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. |