How do you refer to an iterator in docs?

[Terry Reedy]

On 4/19/2012 5:32 PM, Cameron Simpson wrote:
> On 19Apr2012 14:32, Terry Reedy<tjreedy at udel.edu>  wrote:
> | On 4/19/2012 11:51 AM, Jacob MacDonald wrote:
> |>  When I talk about an iterable, I say "iterable".
> |
> | Ditto.
>
> I used to, but find myself saying "sequence" these days. It reads
> better, but is it the same thing?

A Python 'sequence' is a collection that has a length and can be indexed 
by counts 0, 1, ... . In other words, len(s) and s[n] work. This 
definition is in the library manual somewhere. With those two, 'in', 
'count', and 'index' and iteration are theoretically trivial. See 4.6.3. 
Range Type but note that ranges were sequences before the 3.2 additions.

'Sequence' excludes all other iterables that do not have length and 
count indexing: sets, dicts, iterators, files, and others, such as user 
defined or extension tree structures. The point of the new iter/next 
iterator protocol added in 2.2 was to expand the notion of iterable from 
'sequence' or 'pseudo-sequence' to 'collection whose items can be 
accessed one at a time' (whether or not the collection is linearly ordered).

The point of documenting an arg as 'iterable', when that is what the 
function expects, is that is does not have to specifically be a sequence 
or worse, a list. It is a wonderful freedom when the restriction is not 
needed.

---
Terry Jan Reedy