classification
Title: Add next(iter(o)) to set.pop, dict.popitem entries.
Type: enhancement Stage: needs patch
Components: Documentation Versions: Python 3.2, Python 3.3, Python 2.7
process
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: docs@python, eric.araujo, nadeem.vawda, rhettinger, terry.reedy
Priority: normal Keywords: patch

Created on 2012-05-16 22:41 by terry.reedy, last changed 2012-05-21 00:12 by rhettinger. This issue is now closed.

Messages (5)
msg160937 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2012-05-16 22:41
There have been several requests for a set.get() (no args) or set.pick() method to get an item without deleting it as .pop() does. Probably the best answer is to use the simple generic composition next(iter(s)). The counter response is that it is hardly obvious and needs to be documented.

Suggesion: after the current

"pop() 
Remove and return an arbitrary element from the set. Raises KeyError if the set is empty."

add "Use next(iter(s)) to return an arbitrary element without removing it."

Then change the following to match.

"popitem() 
Remove and return an arbitrary (key, value) pair from the dictionary.

popitem() is useful to destructively iterate over a dictionary, as often used in set algorithms. If the dictionary is empty, calling popitem() raises a KeyError."

to

"popitem() 
Remove and return an arbitrary (key, value) pair from the dictionary. Raises KeyError if the dict is empty. Use next(iter(d)) to return an arbitrary pair without removing it."

The old comment about destructively iterating over a dict as a set belongs more with set.pop if it is not removed.

The idiom works with all iterators, but there is no other place I can think of to put it, and it is not needed for sequences.
msg160944 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-05-17 00:22
> Use next(iter(s)) to return an arbitrary element
I would suggest s/return/get/

IIUC calling this twice in a row will get the same element; should the doc mention that?
msg160955 - (view) Author: Nadeem Vawda (nadeem.vawda) * (Python committer) Date: 2012-05-17 08:43
> "popitem() 
> Remove and return an arbitrary (key, value) pair from the dictionary. Raises KeyError if the dict is empty. Use next(iter(d)) to return an arbitrary pair without removing it."

Actually, next(iter(d)) on a dict returns an arbitrary *key*; if you want
a pair, you need next(iter(d.items())).
msg161240 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2012-05-20 23:21
I don't think it is a good idea to expand to the pop/popitem docs this way.  The text is not about what pop/popitem does, it is about what another hypothetical method might do.  The text would be a distractor from the focused description of what pop/popitem actually do.  Also, it would face discoverability problems (there is no reason to think that someone who wants a nonmutating getfirst() method would think to look in the docs for a mutating method).

Also, the text talks about a general purpose programming technique (how to get the first element out of *any* iterable without removing it).  That belongs in a tutorial entry or a summary of idioms.

FWIW, the "several requests for set.get" haven't been serious requests accompanied by valid use cases.  Instead, they have mostly been toy discussions about all the ways you could do it ("for x in s: break",  "next(iter(s))", "x=s.pop(); s.add(x)").   The absence of get() or pick() in other language's set implementations suggest that there isn't a real need here.

That said, I don't think there is much of a downside to adding a sentence to the set.pop() docs.   It would be a waste though to also put it in dict.pop() and dict.popitem() where the question never seems to arise and where the docs already have issues with trying to over describe what can be done.
msg161241 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2012-05-20 23:53
Raymond, I pretty much agree with your points and would be happy either with rejection or one simple sentence.  This idiom really belongs in a hypothetical how-to, such as 'Python iterators and generators'. The real use case for it=iter() followed by next(it) it to treat the first item of a collection specially before scanning the rest in a for loop.
History
Date User Action Args
2012-05-21 00:12:41rhettingersetstatus: open -> closed
resolution: rejected
2012-05-20 23:53:28terry.reedysetmessages: + msg161241
2012-05-20 23:21:03rhettingersetmessages: + msg161240
2012-05-19 04:26:05rhettingersetassignee: docs@python -> rhettinger
2012-05-17 08:43:54nadeem.vawdasetnosy: + nadeem.vawda
messages: + msg160955
2012-05-17 00:22:40eric.araujosetnosy: + eric.araujo
messages: + msg160944
2012-05-16 23:15:39ned.deilysetnosy: + rhettinger
2012-05-16 22:41:29terry.reedycreate