Enum doc correction relating to __members__

[ethanfurman]

BPO	33863
Nosy	@warsaw, @methane, @ethanfurman, @pablogsal, @andresdelfino
Superseder	bpo-33866: Stop using OrderedDict in enum

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/ethanfurman'
closed_at = <Date 2018-06-15.07:05:12.306>
created_at = <Date 2018-06-14.19:57:49.917>
labels = ['3.7', '3.8']
title = 'Enum doc correction relating to __members__'
updated_at = <Date 2018-06-15.07:05:12.305>
user = 'https://github.com/ethanfurman'

bugs.python.org fields:

activity = <Date 2018-06-15.07:05:12.305>
actor = 'ethan.furman'
assignee = 'ethan.furman'
closed = True
closed_date = <Date 2018-06-15.07:05:12.306>
closer = 'ethan.furman'
components = []
creation = <Date 2018-06-14.19:57:49.917>
creator = 'ethan.furman'
dependencies = []
files = []
hgrepos = []
issue_num = 33863
keywords = []
message_count = 19.0
messages = ['319543', '319545', '319548', '319550', '319551', '319552', '319553', '319554', '319555', '319556', '319571', '319572', '319576', '319577', '319579', '319580', '319582', '319583', '319588']
nosy_count = 6.0
nosy_names = ['barry', 'eli.bendersky', 'methane', 'ethan.furman', 'pablogsal', 'adelfino']
pr_nums = []
priority = 'normal'
resolution = 'duplicate'
stage = 'resolved'
status = 'closed'
superseder = '33866'
type = None
url = 'https://bugs.python.org/issue33863'
versions = ['Python 3.6', 'Python 3.7', 'Python 3.8']

[ethanfurman]

Checking the docs for Enum I see that section 8.13.15.3.1 says:

__members__ is an OrderedDict

which is incorrect. It should say "an ordered dictionary".

[andresdelfino]

I'm not sure "ordered dictionary" is the right term. To me, "ordered dictionary" and "OrderedDict" are synonyms, just like "dictionary" and "dict" are. Documentation follows this path in several places.

You can see my reasons for this in this issue: https://bugs.python.org/issue33860

[pablogsal]

Since dictionaries are ordered "ordered dictionary" can be a synonym of "dictionary" and "OrderDict", right?

[andresdelfino]

It doesn't seem right to me to change a term's meaning. Plus, saying "ordered dictionary" makes me think a "dictionary" isn't ordered.

[andresdelfino]

What about "a dictionary-like object"?

[pablogsal]

Well, technically a function can say that it returns a dictionary and this dictionary will be ordered in 3.6> but is not important for the function return value. If a function says that it returns a "ordered dictionary" I now (1) that the order is important in the return value, (2) that it can be a regular dict or an OrderDict depending on the python version. The important thing here is that it preserves insertion order.

[andresdelfino]

What about "a dictionary-like object" for master/3.7, and "a dictionary-like object with insertion order preservation" for 3.6 (or something like that).

I'd avoid "ordered dictionary" altogether as that's the common name of an actual type.

[ethanfurman]

I am open to suggestions, but I will say that there are other types of ordered dictionaries besides OrderedDict. Also, if you have some generic dictionary that happens to be ordered but is not an OrderedDict, how would you describe it?

[andresdelfino]

What do you mean by "a generic dictionary"? If it's a dict-like object, then it *must* be ordered starting with 3.7.

I believe we should make it clear that a dictionary is always a dict object.

If you refer to a mapping with no specific API, then "an ordered mapping" is clear and correct.

[ethanfurman]

An ordered mapping sounds good to me. Let's let this sit for a couple days in case anyone else wants to chime in. If there are no other ideas or objections then we can make the change mid-next week.

[methane]

We use the word "dictionary" for "dict-like" or "maybe dict or it's subclass" many places.
I don't feel it worth enough to change all wording about it.

[methane]

What do you mean by "a generic dictionary"? If it's a dict-like object, then it *must* be ordered starting with 3.7.

No. Even though dict is ordered, no guarantee about ordering of "dictionary". Glossary says:

dictionary
An associative array, where arbitrary keys are mapped to values. The keys can be any object with __hash__() and __eq__() methods. Called a hash in Perl.

So there can be dict-like object without preserving insertion order.

[andresdelfino]

IMHO, the Glossary is just a quick & dirty reference. I wouldn't search for hard definitions in there. See Built-in Types: "dictionary" is used specifically for dict.

I believe we should make clear use of definitions so users known exactly what they get. I know there's a significant effort in reviewing and merging PRs; all I can say is that if the change is deemed reasonable, I can take the task of making this clear everywhere in the docs.

[andresdelfino]

To be a little more clear about this: I don't think one implements a dict-like object by reading the Glossary reference. At least, we shouldn't expect nor encourage this.

[methane]

I feel "dictionary" implies "most likely dict or it's subclass" too. But I don't think "ordered dictionary" is bad wording because:

• Historically, dict didn't preserve insertion order.
• Dict subclass can provide other ordering.

So "ordered dictionary" implies "most likely dict or it's subclass, without customizing ordering".

[andresdelfino]

The problem here is that while the historical issue is real, new programmers will come and they won't see a "non-ordered" dict, and having this "dictionaries" vs "ordered dictionaries" that aren't actual OrderedDict objects (which have the common name "ordered dictionaries", though), will be really confusing for them.

A dictionary (treated as a synonym for dict) can't have an order different than insertion order, because that is one of the guarantees a *dictionary* provides. If one needs to have an object with another sort of ordering, then we talk about a dict-like object, or a dict subclass; but IMHO "dictionary" alone should imply not only a very specific order, but a very specific type too: dict. A dict subclass with different ordering is nothing but that, not a dictionary with different ordering, that would imply one can setup the ordering method of a dict class.

Plus, ordered dictionaries (OrderedDict objects) don't provide exactly the same API as dictionaries, so it gets tricky to use that term to also include dictionaries. It's quite reasonable to expect "ordered dictionaries" to be confused with "OrderedDict objects".

Also, I feel somewhat uncomfortable about "most likely". It's fine to use weak names (dict-like, subclass of dict, mapping, etc.), but not knowing exactly what you can *rely on* (i.e. a required subset of whatever the implementation actually provides) from a given API is quite confusing. Notice that it doesn't have to be an actual type, but at least some sort of description of what is guaranteed (i.e. a mapping).

[andresdelfino]

Something I forgot: we shouldn't write documentation that expects the user *not* to know that dictionaries are ordered now. It's described in What's New and in Built-in Types. That's why "ordered dictionaries" seems so wrong to me.

[methane]

A dictionary (treated as a synonym for dict) can't have an order different than insertion order, because that is one of the guarantees a *dictionary* provides.

When subclassing dict and overrides __iter__ etc., the subclass is dict (isinstance(subclass, dict) is True) and it have order different than insertion order.

So when "dictionary" includes dict subclasses, it doesn't guarantee preserving insertion order.

Exact dict and OrderedDict guarantee insertion order, but when saying "dictionary", it's not guaranteed.

Anyway, word "dictionary" and "ordered dictionary" have vary meanings regarding to context.
So talking about general rule doesn't worth enough to use time and energy to discuss. Let's focus on concrete cases.

For enum, I created pull request to change OrderedDict to dict. (PR-7698)

And for csv.DictReader, it uses OrderedDict already. So I don't against changing "ordered dictionary" to OrderedDict.

[ethanfurman]

Closing as a duplicate of bpo-33866. My apologies for the fractured discussion.

At this point I'm going to leave/update the documentation using "an ordered dictionary". See bpo-33866 for further discussion.