bpo-39879: Update datamodel docs to include dict ordering (GH-19006)
Co-authored-by: furkanonder <furkantahaonder@gmail.com>
(cherry picked from commit 59c644eaa72b0cc48302f59d66852c4ea8332eba)
Co-authored-by: Lahfa Samy <lahfa121999@gmail.com>
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index 1530775..de1e717 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -420,6 +420,11 @@
equal (e.g., ``1`` and ``1.0``) then they can be used interchangeably to index
the same dictionary entry.
+ Dictionaries preserve insertion order, meaning that keys will be produced
+ in the same order they were added sequentially over the dictionary.
+ Replacing an existing key does not change the order, however removing a key
+ and re-inserting it will add it to the end instead of keeping its old place.
+
Dictionaries are mutable; they can be created by the ``{...}`` notation (see
section :ref:`dict`).
@@ -431,6 +436,11 @@
additional examples of mapping types, as does the :mod:`collections`
module.
+ .. versionchanged:: 3.7
+ Dictionaries did not preserve insertion order in versions of Python before 3.6.
+ In CPython 3.6, insertion order was preserved, but it was considered
+ an implementation detail at that time rather than a language guarantee.
+
Callable types
.. index::
object: callable