Issue 33863: Enum doc correction relating to members (original) (raw)

Issue33863

Created on 2018-06-14 19:57 by ethan.furman, last changed 2022-04-11 14:59 by admin. This issue is now closed.

Messages (19)
msg319543 - (view)	Author: Ethan Furman (ethan.furman) *	Date: 2018-06-14 19:57
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".
msg319545 - (view)	Author: Andrés Delfino (adelfino) *	Date: 2018-06-14 20:20
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
msg319548 - (view)	Author: Pablo Galindo Salgado (pablogsal) *	Date: 2018-06-14 20:36
Since dictionaries are ordered "ordered dictionary" can be a synonym of "dictionary" and "OrderDict", right?
msg319550 - (view)	Author: Andrés Delfino (adelfino) *	Date: 2018-06-14 20:48
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.
msg319551 - (view)	Author: Andrés Delfino (adelfino) *	Date: 2018-06-14 20:50
What about "a dictionary-like object"?
msg319552 - (view)	Author: Pablo Galindo Salgado (pablogsal) *	Date: 2018-06-14 20:51
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.
msg319553 - (view)	Author: Andrés Delfino (adelfino) *	Date: 2018-06-14 21:05
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.
msg319554 - (view)	Author: Ethan Furman (ethan.furman) *	Date: 2018-06-14 21:05
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?
msg319555 - (view)	Author: Andrés Delfino (adelfino) *	Date: 2018-06-14 21:09
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.
msg319556 - (view)	Author: Ethan Furman (ethan.furman) *	Date: 2018-06-14 21:14
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.
msg319571 - (view)	Author: Inada Naoki (methane) *	Date: 2018-06-15 02:26
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.
msg319572 - (view)	Author: Inada Naoki (methane) *	Date: 2018-06-15 02:34
> 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.
msg319576 - (view)	Author: Andrés Delfino (adelfino) *	Date: 2018-06-15 02:45
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.
msg319577 - (view)	Author: Andrés Delfino (adelfino) *	Date: 2018-06-15 02:49
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.
msg319579 - (view)	Author: Inada Naoki (methane) *	Date: 2018-06-15 02:56
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".
msg319580 - (view)	Author: Andrés Delfino (adelfino) *	Date: 2018-06-15 03:29
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).
msg319582 - (view)	Author: Andrés Delfino (adelfino) *	Date: 2018-06-15 03:48
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.
msg319583 - (view)	Author: Inada Naoki (methane) *	Date: 2018-06-15 04:11
> 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.
msg319588 - (view)	Author: Ethan Furman (ethan.furman) *	Date: 2018-06-15 07:05
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.