FYI, Builtin dict is tested for ordering already:
https://github.com/python/cpython/blob/13a6c098c215921e35004f9d3a9b70f601e56500/Lib/test/test_ordered_dict.py#L646-L662

Thanks inada, I removed the tests from the PR.

This part needs editing too, the text and example. https://docs.python.org/3/library/stdtypes.html#dictionary-view-objects

Thanks zhang, I have updated it in the PR.

Raymond, do you want to review the current state of the PR before 3.7.0b4?  Otherwise, I'll probably ask that it be merged as is.

I started to add this comment to #33218 but Raymond closed that ticket while I was editing it.

In 3.6, dicts preserving insertion order remains an implementation detail that cannot be relied on. It only becomes a guarantee in 3.7.

Even in 3.7, I think that it remains best to think of dicts as fundamentally unordered. Dicts might preserve insertion order, but there's no interface for extracting the n-th item, or re-ordering the keys into some alternative order, and for the purposes of equality comparisons, the order is ignored.

I propose changing the description from "It is best to think of a dictionary as an unordered set of key: value pairs" to something like:


    Dicts are an otherwise unordered set of key:value pairs
    that remember the order keys were inserted.


and references to "arbitrary order" should be replaced by "insertion order". But by no means should we suggest that dicts are fundamentally orderable (sortable).

> I started to add this comment to #33218 but Raymond closed that ticket while I was editing it.

Sorry, I closed it, not Raymond.

New changeset dfbbbf16f9aab82330c634913441b5ac73267d9c by INADA Naoki (hui shang) in branch 'master':
bpo-32337: Update documentats about dict order (GH-4973)
https://github.com/python/cpython/commit/dfbbbf16f9aab82330c634913441b5ac73267d9c

New changeset 9216dffbc8a2aa62789f81f51f64bc1ec7bf6883 by Miss Islington (bot) in branch '3.7':
bpo-32337: Update documentats about dict order (GH-4973)
https://github.com/python/cpython/commit/9216dffbc8a2aa62789f81f51f64bc1ec7bf6883

Any other known issue?  May I close this issue?

Thanks for doing this!  Let's close it.  If comments arise prior to its release in 370b4, we can reopen, otherwise please open a new issue.