Eric Snow <ericsnowcurren...@gmail.com> added the comment:
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 ---------- _______________________________________ Python tracker <rep...@bugs.python.org> <https://bugs.python.org/issue35864> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
