ambiguous documentation for dict.popitem

[mr-nfamous]

BPO	34123
Nosy	@arigo, @rhettinger, @methane, @mr-nfamous
PRs	bpo-34123: Fix missed documentation update for dict.popitem(). #8292 [3.7] bpo-34123: Fix missed documentation update for dict.popitem(). (GH-8292) #8307

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/rhettinger'
closed_at = <Date 2018-07-17.02:08:43.847>
created_at = <Date 2018-07-16.06:00:27.043>
labels = ['3.7', '3.8', 'docs']
title = 'ambiguous documentation for dict.popitem'
updated_at = <Date 2018-07-17.02:08:43.846>
user = 'https://github.com/mr-nfamous'

bugs.python.org fields:

activity = <Date 2018-07-17.02:08:43.846>
actor = 'rhettinger'
assignee = 'rhettinger'
closed = True
closed_date = <Date 2018-07-17.02:08:43.847>
closer = 'rhettinger'
components = ['Documentation']
creation = <Date 2018-07-16.06:00:27.043>
creator = 'bup'
dependencies = []
files = []
hgrepos = []
issue_num = 34123
keywords = ['patch']
message_count = 8.0
messages = ['321708', '321709', '321712', '321714', '321716', '321741', '321782', '321787']
nosy_count = 5.0
nosy_names = ['arigo', 'rhettinger', 'methane', 'docs@python', 'bup']
pr_nums = ['8292', '8307']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue34123'
versions = ['Python 3.7', 'Python 3.8']

[mr-nfamous]

https://docs.python.org/3/library/stdtypes.html#dict.popitem

dict.popitem no longer returns an "arbitrary" (key, value) pair as the documentation suggests. Rather, it always returns the pair whose key was most recently inserted (ie., the last entry in dk_entries).

Perhaps the docs could reflect that this method is now always LIFO rather arbitrary now that insertion order is guaranteed?

[methane]

I think it is implementation detail yet.
Only iteration order is guaranteed.

[rhettinger]

My opinion is that it is in fact guaranteed. It makes no sense for all other aspects of the dict behavior to be guaranteed and not this one. This is what PyPy and CPython already do and there is no scenario where an implementation would be able to append a new pair at the end but unable to reverse the operation.

IMO, leaving this in an ambiguous state would created problems unnecessarily and it would preclude reasonable uses of the the ordering feature.

[methane]

@armin Rigo
How do you think about this?
Is there no possible optimizations by breaking LIFO dict.popitem()?

[rhettinger]

Is there no possible optimizations by breaking LIFO dict.popitem()?

Even if there were a possible optimization, we wouldn't care. The API is too desirable to forgo in the name of micro-optimization. We don't design our APIs that way -- trading the relevant and actionable for ethereal and unknown.

Also, it is common sense that addition of a key/value pair at the end is a readily undoable operation (no more expensive to remove than it was to add). There will be a dummy entry in the hash array just like there is now.

[arigo]

Agreed with Raymond.

[rhettinger]

New changeset 01b7d58 by Raymond Hettinger in branch 'master':
bpo-34123: Fix missed documentation update for dict.popitem(). (GH-8292)
01b7d58

[rhettinger]

New changeset bfa8a35 by Raymond Hettinger (Miss Islington (bot)) in branch '3.7':
bpo-34123: Fix missed documentation update for dict.popitem(). (GH-8292) (GH#8307)
bfa8a35