Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
bpo-32337: Update documentats about dict order (GH-4973)
(cherry picked from commit dfbbbf1)

Co-authored-by: hui shang <shangdahao@gmail.com>
  • Loading branch information
miss-islington and shangdahao committed Apr 4, 2018
1 parent 74735e2 commit 9216dff
Show file tree
Hide file tree
Showing 4 changed files with 21 additions and 23 deletions.
16 changes: 8 additions & 8 deletions Doc/library/stdtypes.rst
Expand Up @@ -4256,17 +4256,17 @@ support membership tests:
Return an iterator over the keys, values or items (represented as tuples of
``(key, value)``) in the dictionary.

Keys and values are iterated over in an arbitrary order which is non-random,
varies across Python implementations, and depends on the dictionary's history
of insertions and deletions. If keys, values and items views are iterated
over with no intervening modifications to the dictionary, the order of items
will directly correspond. This allows the creation of ``(value, key)`` pairs
Keys and values are iterated over in insertion order.
This allows the creation of ``(value, key)`` pairs
using :func:`zip`: ``pairs = zip(d.values(), d.keys())``. Another way to
create the same list is ``pairs = [(v, k) for (k, v) in d.items()]``.

Iterating views while adding or deleting entries in the dictionary may raise
a :exc:`RuntimeError` or fail to iterate over all entries.

.. versionchanged:: 3.7
Dict order is guaranteed to be insertion order.

.. describe:: x in dictview

Return ``True`` if *x* is in the underlying dictionary's keys, values or
Expand All @@ -4293,17 +4293,17 @@ An example of dictionary view usage::
>>> print(n)
504

>>> # keys and values are iterated over in the same order
>>> # keys and values are iterated over in the same order (insertion order)
>>> list(keys)
['eggs', 'bacon', 'sausage', 'spam']
['eggs', 'sausage', 'bacon', 'spam']
>>> list(values)
[2, 1, 1, 500]

>>> # view objects are dynamic and reflect dict changes
>>> del dishes['eggs']
>>> del dishes['sausage']
>>> list(keys)
['spam', 'bacon']
['bacon', 'spam']

>>> # set operations
>>> keys & {'eggs', 'bacon', 'salad'}
Expand Down
26 changes: 11 additions & 15 deletions Doc/tutorial/datastructures.rst
Expand Up @@ -497,7 +497,7 @@ You can't use lists as keys, since lists can be modified in place using index
assignments, slice assignments, or methods like :meth:`append` and
:meth:`extend`.

It is best to think of a dictionary as an unordered set of *key: value* pairs,
It is best to think of a dictionary as a set of *key: value* pairs,
with the requirement that the keys are unique (within one dictionary). A pair of
braces creates an empty dictionary: ``{}``. Placing a comma-separated list of
key:value pairs within the braces adds initial key:value pairs to the
Expand All @@ -509,26 +509,26 @@ pair with ``del``. If you store using a key that is already in use, the old
value associated with that key is forgotten. It is an error to extract a value
using a non-existent key.

Performing ``list(d.keys())`` on a dictionary returns a list of all the keys
used in the dictionary, in arbitrary order (if you want it sorted, just use
``sorted(d.keys())`` instead). [2]_ To check whether a single key is in the
Performing ``list(d)`` on a dictionary returns a list of all the keys
used in the dictionary, in insertion order (if you want it sorted, just use
``sorted(d)`` instead). To check whether a single key is in the
dictionary, use the :keyword:`in` keyword.

Here is a small example using a dictionary::

>>> tel = {'jack': 4098, 'sape': 4139}
>>> tel['guido'] = 4127
>>> tel
{'sape': 4139, 'guido': 4127, 'jack': 4098}
{'jack': 4098, 'sape': 4139, 'guido': 4127}
>>> tel['jack']
4098
>>> del tel['sape']
>>> tel['irv'] = 4127
>>> tel
{'guido': 4127, 'irv': 4127, 'jack': 4098}
>>> list(tel.keys())
['irv', 'guido', 'jack']
>>> sorted(tel.keys())
{'jack': 4098, 'guido': 4127, 'irv': 4127}
>>> list(tel)
['jack', 'guido', 'irv']
>>> sorted(tel)
['guido', 'irv', 'jack']
>>> 'guido' in tel
True
Expand All @@ -539,7 +539,7 @@ The :func:`dict` constructor builds dictionaries directly from sequences of
key-value pairs::

>>> dict([('sape', 4139), ('guido', 4127), ('jack', 4098)])
{'sape': 4139, 'jack': 4098, 'guido': 4127}
{'sape': 4139, 'guido': 4127, 'jack': 4098}

In addition, dict comprehensions can be used to create dictionaries from
arbitrary key and value expressions::
Expand All @@ -551,7 +551,7 @@ When the keys are simple strings, it is sometimes easier to specify pairs using
keyword arguments::

>>> dict(sape=4139, guido=4127, jack=4098)
{'sape': 4139, 'jack': 4098, 'guido': 4127}
{'sape': 4139, 'guido': 4127, 'jack': 4098}


.. _tut-loopidioms:
Expand Down Expand Up @@ -710,7 +710,3 @@ interpreter will raise a :exc:`TypeError` exception.

.. [1] Other languages may return the mutated object, which allows method
chaining, such as ``d->insert("a")->remove("b")->sort();``.
.. [2] Calling ``d.keys()`` will return a :dfn:`dictionary view` object. It
supports operations like membership test and iteration, but its contents
are not independent of the original dictionary -- it is only a *view*.
1 change: 1 addition & 0 deletions Misc/ACKS
Expand Up @@ -1449,6 +1449,7 @@ Ian Seyer
Dmitry Shachnev
Anish Shah
Daniel Shahaf
Hui Shang
Mark Shannon
Ha Shao
Richard Shapiro
Expand Down
@@ -0,0 +1 @@
Update documentation related with ``dict`` order.

0 comments on commit 9216dff

Please sign in to comment.