the order of dict isn't documented in an example

[Yzi-Li]

Documentation

I am reading the documentation of dictionary.
There is an example

>>> a = dict(one=1, two=2, three=3)
>>> b = {'one': 1, 'two': 2, 'three': 3}
>>> c = dict(zip(['one', 'two', 'three'], [1, 2, 3]))
>>> d = dict([('two', 2), ('one', 1), ('three', 3)])
>>> e = dict({'three': 3, 'one': 1, 'two': 2})
>>> f = dict({'one': 1, 'three': 3}, two=2)
>> a == b == c == d == e == f
True

For new users, they might not know that the dictionary is unorderd in 3.7+ (not everyone reads data model before reading this). So they might feel confused and think {one: 1, two: 2} shoudn't be equal to {two:2, one:1}.

Maybe we could link date model for explaning.

Linked PRs

• gh-133361: move the explanation of dict equal before its use #133424
• [3.14] gh-133361: move the explanation of dict equal before its use (GH-133424) #133620
• [3.13] gh-133361: move the explanation of dict equal before its use (GH-133424) #133621

[skirpichev]

So they might feel confused and think {one: 1, two: 2} shoudn't be equal to {two:2, one:1}.

Why? They could read the rest of dict docs on same page:

Dictionaries compare equal if and only if they have the same (key, value) pairs (regardless of ordering). Order comparisons (‘<’, ‘<=’, ‘>=’, ‘>’) raise TypeError.

[Yzi-Li]

Oh, it mentions in values() and I just realized this. Would it be better if we explain for it?

[skirpichev]

Oh, it mentions in values() and I just realized this.

It's just after description of dict's methods.

Would it be better if we explain for it?

Explain what? What's unclear in the above sentence?

[Yzi-Li]

It's just after description of dict's methods.

Yes, you're right. I didn't notice the indent.

Explain what? What's unclear in the above sentence?

I'm not sure if it is right. Some important things like the order of dict should say first. It shouldn't be after its methods. This might be more friendly for new users.

[Yzi-Li]

Would it be better if we explain for it?

"it" refers to the example instead of the above sentence.

[skirpichev]

"it" refers to the example instead of the above sentence.

Ok. Examples here are to illustrate dict() constructor. And there are several cases, which differ by ordering of keys. I doubt that adding something does make sense here.

[terryjreedy]

Dicts became ordered (by insertion), not unordered, in 3.6/7. And it is documented: Dictionaries preserve insertion order. Note that updating a key does not affect the order. Keys added after deletion are inserted at the end." This is followed by examples and version note. Nothing more is needed.

I think the following explains equality quite sufficiently, but should be moved before the example.

Dictionaries compare equal if and only if they have the same (key, value) pairs (regardless of ordering). Order comparisons (‘<’, ‘<=’, ‘>=’, ‘>’) raise TypeError.

I am reopening to move the explanation of == before its use.

[Yzi-Li]

Do you need me to create a PR to move this explanation?