[Python-checkins] bpo-32337: Update documentats about dict order (GH-4973)

Wed Apr 4 00:55:09 EDT 2018

https://github.com/python/cpython/commit/dfbbbf16f9aab82330c634913441b5ac73267d9c
commit: dfbbbf16f9aab82330c634913441b5ac73267d9c
branch: master
author: hui shang <shangdahao at gmail.com>
committer: INADA Naoki <methane at users.noreply.github.com>
date: 2018年04月04日T13:55:05+09:00
summary:
bpo-32337: Update documentats about dict order (GH-4973)
files:
A Misc/NEWS.d/next/Documentation/2017-12-22-17-29-37.bpo-32337.eZe-ID.rst
M Doc/library/stdtypes.rst
M Doc/tutorial/datastructures.rst
M Misc/ACKS

diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index ad7f578e0860..a213189a3407 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -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
@@ -4293,9 +4293,9 @@ 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]
 
@@ -4303,7 +4303,7 @@ An example of dictionary view usage::
 >>> del dishes['eggs']
 >>> del dishes['sausage']
 >>> list(keys)
- ['spam', 'bacon']
+ ['bacon', 'spam']
 
 >>> # set operations
 >>> keys & {'eggs', 'bacon', 'salad'}
diff --git a/Doc/tutorial/datastructures.rst b/Doc/tutorial/datastructures.rst
index b95aca885252..7855ef2d2882 100644
--- a/Doc/tutorial/datastructures.rst
+++ b/Doc/tutorial/datastructures.rst
@@ -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
@@ -509,9 +509,9 @@ 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::
@@ -519,16 +519,16 @@ 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
@@ -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::
@@ -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:
@@ -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*.
diff --git a/Misc/ACKS b/Misc/ACKS
index c7bdbd4a2312..f7ac37ea7ac8 100644
--- a/Misc/ACKS
+++ b/Misc/ACKS
@@ -1451,6 +1451,7 @@ Ian Seyer
 Dmitry Shachnev
 Anish Shah
 Daniel Shahaf
+Hui Shang
 Mark Shannon
 Ha Shao
 Richard Shapiro
diff --git a/Misc/NEWS.d/next/Documentation/2017-12-22-17-29-37.bpo-32337.eZe-ID.rst b/Misc/NEWS.d/next/Documentation/2017-12-22-17-29-37.bpo-32337.eZe-ID.rst
new file mode 100644
index 000000000000..a905467cd59f
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2017-12-22-17-29-37.bpo-32337.eZe-ID.rst
@@ -0,0 +1 @@
+Update documentation related with ``dict`` order.
