[Python-checkins] bpo-33609: Document dict insertion order guarantee as of 3.7 (GH-7093)

[Ned Deily]

https://github.com/python/cpython/commit/f822549653d8d09bffff5b7dcddfdf12679a787c
commit: f822549653d8d09bffff5b7dcddfdf12679a787c
branch: master
author: INADA Naoki <methane at users.noreply.github.com>
committer: Ned Deily <nad at python.org>
date: 2018-06-04T18:09:22-04:00
summary:

bpo-33609: Document dict insertion order guarantee as of 3.7 (GH-7093)

files:
M Doc/library/stdtypes.rst

diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index af2b4e1cb66a..80dfe88cc58c 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -4248,6 +4248,29 @@ pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098:
    value)`` pairs. Order comparisons ('<', '<=', '>=', '>') raise
    :exc:`TypeError`.
 
+   Dict preserves insertion order.  Note that updating key doesn't affects the
+   order.  On the other hand, keys added after deletion are inserted to the
+   last. ::
+
+      >>> d = {"one": 1, "two": 2, "three": 3, "four": 4}
+      >>> d
+      {'one': 1, 'two': 2, 'three': 3, 'four': 4}
+      >>> list(d)
+      ['one', 'two', 'three', 'four']
+      >>> list(d.values())
+      [1, 2, 3, 4]
+      >>> d["one"] = 42
+      >>> d
+      {'one': 42, 'two': 2, 'three': 3, 'four': 4}
+      >>> del d["two"]
+      >>> d["two"] = None
+      >>> d
+      {'one': 42, 'three': 3, 'four': 4, 'two': None}
+
+   .. versionchanged:: 3.7
+      Dict order is guaranteed to be insertion order.  This behavior was
+      implementation detail of CPython from 3.6.
+
 .. seealso::
    :class:`types.MappingProxyType` can be used to create a read-only view
    of a :class:`dict`.