diff --git a/Doc/howto/functional.rst b/Doc/howto/functional.rst index 280749c022a..9c1003de29b 100644 --- a/Doc/howto/functional.rst +++ b/Doc/howto/functional.rst @@ -291,10 +291,10 @@ dictionary's keys:: Note that the order is essentially random, because it's based on the hash ordering of the objects in the dictionary. -Applying ``iter()`` to a dictionary always loops over the keys, but dictionaries -have methods that return other iterators. If you want to iterate over keys, -values, or key/value pairs, you can explicitly call the ``iterkeys()``, -``itervalues()``, or ``iteritems()`` methods to get an appropriate iterator. +Applying :func:`iter` to a dictionary always loops over the keys, but +dictionaries have methods that return other iterators. If you want to iterate +over values or key/value pairs, you can explicitly call the +:meth:`values` or :meth:`items` methods to get an appropriate iterator. The :func:`dict` constructor can accept an iterator that returns a finite stream of ``(key, value)`` tuples:: diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst index d6e3291af95..97399f5cd27 100644 --- a/Doc/library/itertools.rst +++ b/Doc/library/itertools.rst @@ -414,7 +414,7 @@ can be combined. :: # Show a dictionary sorted and grouped by value >>> from operator import itemgetter >>> d = dict(a=1, b=2, c=1, d=2, e=1, f=2, g=3) - >>> di = sorted(d.iteritems(), key=itemgetter(1)) + >>> di = sorted(d.items(), key=itemgetter(1)) >>> for k, g in groupby(di, key=itemgetter(1)): ... print(k, map(itemgetter(0), g)) ... @@ -464,9 +464,6 @@ incur interpreter overhead. :: "Return function(0), function(1), ..." return imap(function, count()) - def iteritems(mapping): - return izip(mapping.iterkeys(), mapping.itervalues()) - def nth(iterable, n): "Returns the nth item or raise StopIteration" return islice(iterable, n, None).next() diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 17962c22dc7..66270ba25a1 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -1804,39 +1804,24 @@ types should support too): .. method:: dict.items() - Return a copy of the dictionary's list of ``(key, value)`` pairs. + Return an iterator over the dictionary's ``(key, value)`` pairs. .. note:: Keys and values are listed in an arbitrary order which is non-random, varies across Python implementations, and depends on the dictionary's history of - insertions and deletions. If :meth:`items`, :meth:`keys`, :meth:`values`, - :meth:`iteritems`, :meth:`iterkeys`, and :meth:`itervalues` are called with no + insertions and deletions. If :meth:`items`, :meth:`keys`, and + :meth:`values` are called with no intervening modifications to the dictionary, the lists will directly correspond. This allows the creation of ``(value, key)`` pairs using :func:`zip`: ``pairs = zip(d.values(), d.keys())``. The same relationship holds for the :meth:`iterkeys` and :meth:`itervalues` methods: ``pairs = zip(d.itervalues(), d.iterkeys())`` provides the same value for ``pairs``. Another way to create the - same list is ``pairs = [(v, k) for (k, v) in d.iteritems()]``. - -.. method:: dict.iteritems() - - Return an iterator over the dictionary's ``(key, value)`` pairs. - See the note for :meth:`dict.items`. - -.. method:: dict.iterkeys() - - Return an iterator over the dictionary's keys. See the note for - :meth:`dict.items`. - -.. method:: dict.itervalues() - - Return an iterator over the dictionary's values. See the note for - :meth:`dict.items`. + same list is ``pairs = [(v, k) for (k, v) in d.items()]``. .. method:: dict.keys() - Return a copy of the dictionary's list of keys. See the note for + Return an iterator over the dictionary's keys. See the note for :meth:`dict.items`. .. method:: dict.pop(key[, default]) @@ -1855,13 +1840,13 @@ types should support too): .. method:: dict.setdefault(key[, default]) - If *key* is in the dictionary, return its value. If not, insert *key* with a - value of *default* and return *default*. *default* defaults to ``None``. + If *key* is in the dictionary, return its value. If not, insert *key* with + a value of *default* and return *default*. *default* defaults to ``None``. .. method:: dict.update([other]) - Update the dictionary with the key/value pairs from *other*, overwriting existing - keys. Return ``None``. + Update the dictionary with the key/value pairs from *other*, overwriting + existing keys. Return ``None``. :func:`update` accepts either another dictionary object or an iterable of key/value pairs (as a tuple or other iterable of length two). If keyword @@ -1870,8 +1855,8 @@ types should support too): .. method:: dict.values() - Return a copy of the dictionary's list of values. See the note for - :meth:`mapping.items`. + Return an iterator over the dictionary's values. See the note for + :meth:`dict.items`. .. _bltin-file-objects: diff --git a/Doc/library/userdict.rst b/Doc/library/userdict.rst index d15f51858a8..0490118d316 100644 --- a/Doc/library/userdict.rst +++ b/Doc/library/userdict.rst @@ -33,7 +33,8 @@ The :mod:`UserDict` module defines the :class:`UserDict` class and .. note:: - For backward compatibility, instances of :class:`UserDict` are not iterable. + For backward compatibility, instances of :class:`UserDict` are not + iterable. .. class:: IterableUserDict([initialdata]) @@ -62,8 +63,8 @@ provide the following attribute: :meth:`__delitem__` will preclude only :meth:`pop` and :meth:`popitem` from the full interface. - In addition to the four base methods, progressively more efficiency comes with - defining :meth:`__contains__`, :meth:`__iter__`, and :meth:`iteritems`. + In addition to the four base methods, progressively more efficiency comes + with defining :meth:`__contains__` and :meth:`__iter__`. Since the mixin has no knowledge of the subclass constructor, it does not define :meth:`__init__` or :meth:`copy`. @@ -93,10 +94,11 @@ The :mod:`UserList` module defines the :class:`UserList` class: .. class:: UserList([list]) Class that simulates a list. The instance's contents are kept in a regular - list, which is accessible via the :attr:`data` attribute of :class:`UserList` + list, which is accessible via the :attr:`data` attribute of + :class:`UserList` instances. The instance's contents are initially set to a copy of *list*, - defaulting to the empty list ``[]``. *list* can be any iterable, e.g. a - real Python list or a :class:`UserList` object. + defaulting to the empty list ``[]``. *list* can be any iterable, for + example a real Python list or a :class:`UserList` object. In addition to supporting the methods and operations of mutable sequences (see section :ref:`typesseq`), :class:`UserList` instances provide the following diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index 7c2ed4db739..9e847cc74e4 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -1589,8 +1589,8 @@ a sequence, the allowable keys should be the integers *k* for which ``0 <= k < N`` where *N* is the length of the sequence, or slice objects, which define a range of items. It is also recommended that mappings provide the methods :meth:`keys`, :meth:`values`, :meth:`items`, :meth:`has_key`, :meth:`get`, -:meth:`clear`, :meth:`setdefault`, :meth:`iterkeys`, :meth:`itervalues`, -:meth:`iteritems`, :meth:`pop`, :meth:`popitem`, :meth:`copy`, and +:meth:`clear`, :meth:`setdefault`, +:meth:`pop`, :meth:`popitem`, :meth:`copy`, and :meth:`update` behaving similar to those for Python's standard dictionary objects. The :mod:`UserDict` module provides a :class:`DictMixin` class to help create those methods from a base set of :meth:`__getitem__`, @@ -1608,7 +1608,7 @@ should be equivalent of :meth:`has_key`; for sequences, it should search through the values. It is further recommended that both mappings and sequences implement the :meth:`__iter__` method to allow efficient iteration through the container; for mappings, :meth:`__iter__` should be the same as -:meth:`iterkeys`; for sequences, it should iterate through the values. +:meth:`keys`; for sequences, it should iterate through the values. .. method:: object.__len__(self) @@ -1677,7 +1677,7 @@ container; for mappings, :meth:`__iter__` should be the same as This method is called when an iterator is required for a container. This method should return a new iterator object that can iterate over all the objects in the container. For mappings, it should iterate over the keys of the container, and - should also be made available as the method :meth:`iterkeys`. + should also be made available as the method :meth:`keys`. Iterator objects also need to implement this method; they are required to return themselves. For more information on iterator objects, see :ref:`typeiter`.