As of 3.7 [1], dict is guaranteed to preserve insertion order:

  the insertion-order preservation nature of dict
  objects has been declared to be an official part
  of the Python language spec.

However, at least one key part of the language reference [2] was not updated to reflect this:  "3.2. The standard type hierarchy" > "Mappings" > "Dictionaries".

Note that the library docs [3] *were* updated.


[1] https://docs.python.org/3/whatsnew/3.7.html#summary-release-highlights
[2] https://docs.python.org/3/reference/datamodel.html#index-30
[3] https://docs.python.org/3/library/stdtypes.html#typesmapping

Hi, 

I would like to take this issue as my first contribution to Python, I'm currently subscribed to the python-core-mentorship list.
I do not know exactly how to submit a patch for an issue.

Kind regards.

Patch are submitted as pull request on our GitHub repo.
Here's a write-up on how to do it
https://devguide.python.org/pullrequest/#step-by-step-guide

Following the guide, I've send a patch with the fix, I'm waiting for a review. Once the patch will be reviewed and accepted. My patch will need to be backported from 3.9 to 3.7.

I sent pr. All tests passed successfully. If accepted, this will be my first contribution :)
https://github.com/python/cpython/pull/19027

Hi Furkan.  Please note that Lahfa Samy had already submitted a PR for this issue after "claiming" it with a note here; proper "netiquette" suggests not jumping in with your own PR in such a situation.

Fortuitously though, it looks like the both of you have actually implemented about half of the final change that we need here :).  I'll be leaving review comments on both PRs; I recommend that the two of you work together to combine your PRs into a single PR with both of your (revised) changes.

Hi Furkan, would you mind to combine your revised PR with mine so that we can do as suggested by Zachary?

Hello Samy,
I sent you pr from the docs-dict-ordered branch in your cpython repository. Now both of us have merged pr. I closed my own pr. You can also close your pr and send these changes again as bpo-39879.

It's my pr,https://github.com/AkechiShiro/cpython/pull/1

Thank you for your quick work, I have successfully merged your changes in the branch of the first PR, now awaiting review from Zachary.

New changeset 59c644eaa72b0cc48302f59d66852c4ea8332eba by Lahfa Samy in branch 'master':
bpo-39879: Update datamodel docs to include dict ordering (GH-19006)
https://github.com/python/cpython/commit/59c644eaa72b0cc48302f59d66852c4ea8332eba

New changeset ea0eeb8d3a0544334f8836c98a761b2e3df2bd94 by Miss Islington (bot) in branch '3.7':
bpo-39879: Update datamodel docs to include dict ordering (GH-19006)
https://github.com/python/cpython/commit/ea0eeb8d3a0544334f8836c98a761b2e3df2bd94

New changeset 96686c761d0587080effc113367431a0d396eb45 by Miss Islington (bot) in branch '3.8':
bpo-39879: Update datamodel docs to include dict ordering (GH-19006)
https://github.com/python/cpython/commit/96686c761d0587080effc113367431a0d396eb45

Thanks for the patch!

What's New in Python 3.7 says:

> the insertion-order preservation nature of dict objects has been declared to be an official part of the Python language spec.

Reference: https://mail.python.org/pipermail/python-dev/2017-December/151283.html

I just wanted to add a reference for this change. I wanted to check if it is ok to modify the doc: yes, it is :-)