Author eric.snow
Recipients eric.snow, rhettinger
Date 2019-02-01.16:24:42
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1549038282.52.0.139401064667.issue35864@roundup.psfhosted.org>
In-reply-to
Content
Also, there's a potentially misleading detail that you might consider correcting in the text.  However, making it correct might make it slightly less clear, so it's a bit of a judgement call on how important it is to be explicit here.  (FWIW, I think it's worth it to some extent.)

The language reference doesn't guarantee that dictionaries are order-preserving (yet). [1]  Therefore there can be (are?) Python implementations where dict isn't ordered.  Users of those implementations may be confused by the docs (and docstring) saying the method returns a dict.

This could be addressed by changing those places to say something like it returns an insertion-ordered mapping.  The docs entry would also have an "CPython implementation detail" part saying it's actually a dict in CPython.

Since "insertion-ordered mapping" isn't nearly as clear as "dict" (even if more correct), it may make more sense to simply say "dict".  However, in that case I'd recommend at the very least to add a "CPython implementation detail" part to the docs entry which says in CPython it returns a dict, but in other implementations it may be some other order-preserving mapping.

Honestly, after having written that the latter option seems more sensible. :)


[1] https://docs.python.org/3.8/reference/datamodel.html#index-29
History
Date User Action Args
2019-02-01 16:24:43eric.snowsetrecipients: + eric.snow, rhettinger
2019-02-01 16:24:42eric.snowsetmessageid: <1549038282.52.0.139401064667.issue35864@roundup.psfhosted.org>
2019-02-01 16:24:42eric.snowlinkissue35864 messages
2019-02-01 16:24:42eric.snowcreate