[issue33863] Enum doc correction relating to __members__

Ethan Furman added the comment: Closing as a duplicate of #33866. My apologies for the fractured discussion. At this point I'm going to leave/update the documentation using "an ordered dictionary". See #33866 for further discussion. -- assignee: -> ethan.furman resolution: ->

[issue33863] Enum doc correction relating to __members__

INADA Naoki added the comment: > 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

[issue33863] Enum doc correction relating to __members__

Andrés Delfino added the comment: 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. --

[issue33863] Enum doc correction relating to __members__

Andrés Delfino added the comment: 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

[issue33863] Enum doc correction relating to __members__

INADA Naoki added the comment: 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"

[issue33863] Enum doc correction relating to __members__

Andrés Delfino added the comment: 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. -- ___ Python tracker

[issue33863] Enum doc correction relating to __members__

Andrés Delfino added the comment: 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

[issue33863] Enum doc correction relating to __members__

INADA Naoki added the comment: > 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

[issue33863] Enum doc correction relating to __members__

INADA Naoki added the comment: 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. -- nosy: +inada.naoki ___ Python tracker

[issue33863] Enum doc correction relating to __members__

Andrés Delfino added the comment: 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

[issue33863] Enum doc correction relating to __members__

Ethan Furman added the comment: 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. -- ___ Python

[issue33863] Enum doc correction relating to __members__

Ethan Furman added the comment: 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? --

[issue33863] Enum doc correction relating to __members__

Andrés Delfino added the comment: 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. --

[issue33863] Enum doc correction relating to __members__

Pablo Galindo Salgado added the comment: 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

[issue33863] Enum doc correction relating to __members__

Andrés Delfino added the comment: What about "a dictionary-like object"? -- ___ Python tracker ___ ___ Python-bugs-list mailing

[issue33863] Enum doc correction relating to __members__

Andrés Delfino added the comment: 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. -- ___ Python tracker

[issue33863] Enum doc correction relating to __members__

Pablo Galindo Salgado added the comment: Since dictionaries are ordered "ordered dictionary" can be a synonym of "dictionary" and "OrderDict", right? -- nosy: +pablogsal ___ Python tracker

[issue33863] Enum doc correction relating to __members__

Andrés Delfino added the comment: 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:

[issue33863] Enum doc correction relating to __members__

New submission from Ethan Furman : 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". -- messages: 319543 nosy: adelfino, barry, eli.bendersky, ethan.furman priority: normal