bpo-33609: Document dict insertion order guarantee as of 3.7 (GH-7093)
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index af2b4e1..80dfe88 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -4248,6 +4248,29 @@
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`.