On Dec 12, 2019, at 21:52, Tim Peters <tim.peters@gmail.com> wrote:
I couldn't care less whether things are "obvious" at first - unless they're Dutch ;-) Nothing about programming is obvious at first. What I do care about is explanations that "stick" _after_ someone makes the effort to learn them.
Sure, but you can also explain first just fine by saying it returns the first thing in its argument, and that will stick as well. This whole subthread is an attempt to come up with wording that solves a problem that I don’t think exists: Wes suggested everyone will be confused by using first on a set. I don’t think anyone will be. Do you disagree? If not, why do we need to solve that nonexistent confusion?
For that matter, even if they do know this leaves a bound to something useful, do they know what it does with a set? If not, what have we solved here?
You seriously want to claim that it's A Mystery to people what iterating over a set does? That even a newbie would be baffled by the output of:
for a in {1, 2, 3}: print(a)
No, I want to claim almost the exact opposite: that they won’t be baffled by that, and they won’t be baffled by the fact that first on their set returns 2 either. The first time you have to learn that sets iterate in arbitrary order, you have to learn it. But then you know it, and it’s not baffling when a for statement gives you an arbitrary order just like print did, but it’s also not baffling when list(s) gives you an arbitrary order just like print and for did, or when more_itertools.first gives you the first element of an arbitrary order just like everything else does.
Plus, if first really has to be this completely understandable to people who don’t know about iter, how can we put it in itertools, a module whose docs start off with a nice friendly introduction about the building blocks of an algebra for iterators that you can compose into powerful tools?
As above, I didn't really have newbies in mind. I did have the learning curve all Python programmers need to climb in mind. `next()` and `iter()` didn't even exist in earlier versions of Python, yet we somehow managed ;-)
Neither did itertools. And, just as with next and iter, you can go a long way in Python without learning itertools. And by the time you get to looking for functions in itertools to use on a set, you’re not going to be baffled by the fact that a set’s order is just as arbitrary when used with itertools functions as it is with everything else.
Why are you so irked at an attempt to give "the simplest explanation that could possibly work"?
I’m not, but the simplest explanation is just “Return the first item of *iterable*.” Of course you also need to follow up with the details, like “If iterable* is empty, return *default*, or raise ValueError if no *default* is provided.” And add an example, and maybe a sentence on why you might want this function. But the first sentence explains what it does, and it’s hard to get any simpler than that. I’m not all that irked, but it does annoy me a bit that it’s so easy for someone to derail a thread that’s making progress just by raising a spurious problem. People jump to trying to come up with the best solution without asking whether the problem actually needs to be solved.