<div dir="ltr">I'd like to see several examples where a new term would improve the reading of the documentation. So far I agree with Akira Li and Brandon Barnwell. The current usage of "iterable" provides the correct level of specificity. I do not think `list(finite_iterable)` improves the function tooltip. I prefer `list(iterable)`. There's no need to cover all edge cases in the tooltip.<div><span style="line-height:1.5"><br></span></div><div><span style="line-height:1.5">Two tasks that require viewing more than one element simultaneously are sorting and finding a median. The functions `sorted(iterable)` and `statistics.median(data)` have reasonable documentation without mentioning the fact that inputting an infinite iterator would be a bad choice.</span></div></div><br><div class="gmail_quote"><div dir="ltr">On Thu, Nov 5, 2015 at 4:17 AM Andrew Barnert <<a href="mailto:abarnert@yahoo.com">abarnert@yahoo.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">On Nov 4, 2015, at 19:45, Michael Selik <<a href="mailto:mike@selik.org" target="_blank">mike@selik.org</a>> wrote:<br>
><br>
> On 02.10.2015 05:49, Steven D'Aprano wrote:<br>
> > At most, some have suggested that we don't have a good<br>
> > word for those iterables which are not iterators.<br>
><br>
> Isn't that a "sequence"? The collections module defines a Sequence as having a __getitem__ and __len__. Is a "non-iterator iterable" something different?<br>
<br>
A mapping isn't a sequence (even though it has __getitem__ and __len__, and also has the same supertypes, which add additional restrictions that you forgot like __contains__). Neither is a set, or any of the kinds of mapping views, or any intentionally-not-quite-sequence (like range before 3.2, or, IIRC, blist.sortedlist), or an iterable that, each time it's iterated, gives you 20 new values in [0, 1) that add up to 1. But they're all non-iterator iterables.<br>
<br>
In fact, there are a number of concepts that largely overlap, but don't completely, including:<br>
<br>
* Iterables that aren't iterators<br>
* Iterables that don't return self from __iter__<br>
* Iterables that always return a new iterator<br>
* Iterables that can repeatably produce a "correct" sequence of values (as long as they aren't mutated in between iterations)<br>
* Iterables that can repeatably produce equal values (as long as they aren't mutated)<br>
* Iterables that can repeatedly produce identical values (as long as they aren't mutated)<br>
<br>
There are also variations of the last three that represent some data that can be "externally mutated" (e.g., a list of all broadcasting SMB servers on the local subnet will always produce equal values unless a server goes up or down between iterations—or, more simply, any view can change values if the thing it's a view of is mutated, without the view itself being mutated).<br>
<br>
Anyway, all of the above are true for sequences, mappings, sets, mapping views, and most not-quite-sequences, but not for the random example, or the SMB example.<br>
<br>
I don't think we need official names for all of these things, just one—as long as it's clear which one, and exactly what it means, I think that will cover well over 90% of all reasonable uses.<br>
<br>
I believe that earlier in the thread, Terry suggested "collection" to mean the last definition, which seems fine at first glance, so let's assume that. If we added that to the documentation (and fixed all the places that sloppily talk about sequences when they don't really mean sequences, etc.), and ideally added an ABC and a static type to match, then code could very easily explain that it produces or requires a collection. Most code that needs two passes over an iterable can just say it requires a collection. The fact that it might also work with some sort-of-repeatable-but-not-quite-collection types is fine (and we don't have to say that such types are "defective" or anything, as long as the documentation makes it clear that there are some very rare iterables that are neither iterators nor collections, and what that means).<br>
<br>
Of course Collection defined this way can't be an implicit ABC, because it doesn't have any interface beyond that of Iterator. But then Sequence and Mapping can't be implicit either, because they have the same interface as each other. In fact, that's the main reason we need ABCs in the first place—for cases where structural/duck typing can't cover the intended semantics.</blockquote></div>