This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: doc Avoid "ordered dictionary" references now that dictionaries are ordered
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.8, Python 3.7
process
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: docs@python Nosy List: adelfino, docs@python, ethan.furman, methane
Priority: normal Keywords:

Created on 2018-06-14 15:25 by adelfino, last changed 2022-04-11 14:59 by admin. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 7535 closed adelfino, 2018-06-14 15:25
Messages (8)
msg319523 - (view) Author: Andrés Delfino (adelfino) * (Python triager) Date: 2018-06-14 15:25
IMHO, using "ordered dictionaries" references is somewhat confusing now that dictionaries preserve insertion order.

PR changes this references to "OrderedDict object".
msg319524 - (view) Author: Inada Naoki (methane) * (Python committer) Date: 2018-06-14 15:48
"ordered dictionary" means "dict-like object which preserves insertion order".  Both of dict and OrderedDict is "ordered dictionary".

If we change it to OrderedDict, it make harder to change return type from OrderedDict to normal dict.

Do you propose we should never change return type?
msg319525 - (view) Author: Inada Naoki (methane) * (Python committer) Date: 2018-06-14 15:56
Sometime, we chose weak name like "file-like" or "dictionary" over "io.TextIOWrapper" or "dict", to avoid making future improvements harder.

If there are no strong reason to specify concrete type, let's keep using weak name.

In case of enum members, I want to change it to regular dict in Python 3.8, but I'm not sure yet.
msg319531 - (view) Author: Andrés Delfino (adelfino) * (Python triager) Date: 2018-06-14 17:28
Please note that DictReader already mentions "OrderedDict" as a type it returns now. I do see the issue you raise though and I'm not proposing to guarantee that type for next versions.

I see the benefits of using weak names, but "dictionary" alone doesn't seem like a good weak name to me, as it's the common name of an actual type. "ordered dictionary" is the common name of a type, too, which makes the "dictionary" in that phrase less of a weak name. Bacause of this, I don't think we are using weak names in the cases the PR changes.

A dict-like object must preserve insertion order as that's what dict does; specifying it could make people think dicts aren't ordered. I understand a dict-like object as if it were a dict subclass, that is, following the full dict API.

As to what the changes could look like with these things in mind... It's difficult to say without knowing which API are we actually telling people to rely on now: dict, dict-like, OrderedDict, OrderedDict-like?
msg319563 - (view) Author: Andrés Delfino (adelfino) * (Python triager) Date: 2018-06-14 22:52
I believe the discussion in #33863 is relevant. Depending on what the API the user can rely on, perhaps "an ordered mapping" fits here too.
msg319573 - (view) Author: Inada Naoki (methane) * (Python committer) Date: 2018-06-15 02:39
> Please note that DictReader already mentions "OrderedDict" as a type it returns now.

OK, but PR-7535 changes enum too.

> but "dictionary" alone doesn't seem like a good weak name to me, as it's the common name of an actual type.

As I commented in #33863, "dictionary" is really common weak name defined in glossary.  dict ∈ dictionary
msg319578 - (view) Author: Andrés Delfino (adelfino) * (Python triager) Date: 2018-06-15 02:52
Perhaps we can continue the discussion on #33863 as there are more argumnets there, from all points of view, and when a decision is taken there, we can apply it here too.
msg319587 - (view) Author: Ethan Furman (ethan.furman) * (Python committer) Date: 2018-06-15 06:55
As I said on the PR:

This feels like an unnecessary change. The phrase "ordered dictionary" does not always refer to an 'OrderedDict`, and there is more than one way to order a dictionary besides insertion order.

As a side note: it's generally better to have different pull requests for different modules.
History
Date User Action Args
2022-04-11 14:59:01adminsetgithub: 78041
2018-06-15 06:55:10ethan.furmansetstatus: open -> closed

nosy: + ethan.furman
messages: + msg319587

resolution: rejected
stage: resolved
2018-06-15 02:52:05adelfinosetmessages: + msg319578
2018-06-15 02:39:13methanesetmessages: + msg319573
2018-06-14 22:52:28adelfinosetmessages: + msg319563
2018-06-14 17:28:53adelfinosetmessages: + msg319531
2018-06-14 15:56:43methanesetmessages: + msg319525
2018-06-14 15:48:44methanesetnosy: + methane
messages: + msg319524
2018-06-14 15:25:56adelfinocreate