From 9216dffbc8a2aa62789f81f51f64bc1ec7bf6883 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 3 Apr 2018 22:01:46 -0700 Subject: [PATCH] bpo-32337: Update documentats about dict order (GH-4973) (cherry picked from commit dfbbbf16f9aab82330c634913441b5ac73267d9c) Co-authored-by: hui shang --- Doc/library/stdtypes.rst | 16 ++++++------ Doc/tutorial/datastructures.rst | 26 ++++++++----------- Misc/ACKS | 1 + .../2017-12-22-17-29-37.bpo-32337.eZe-ID.rst | 1 + 4 files changed, 21 insertions(+), 23 deletions(-) create mode 100644 Misc/NEWS.d/next/Documentation/2017-12-22-17-29-37.bpo-32337.eZe-ID.rst diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index ad7f578e086..a213189a340 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 b95aca88525..7855ef2d288 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 729e88e5658..c70f62efcf5 100644 --- a/Misc/ACKS +++ b/Misc/ACKS @@ -1449,6 +1449,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 00000000000..a905467cd59 --- /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.