How do you refer to an iterator in docs?

[Terry Reedy]

On 4/19/2012 6:16 PM, Cameron Simpson wrote:
> On 19Apr2012 18:07, Terry Reedy<tjreedy at udel.edu>  wrote:
> | 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.

7.4.1. Collections Abstract Base Classes defines a Sequence as a Sized, 
Iterable, Container.

The glossary entry for 'sequence' leaves out the container part:
"An iterable which supports efficient element access using integer 
indices via the __getitem__() special method and defines a len() method 
that returns the length of the sequence. ... Note that dict also 
supports __getitem__() and __len__(), but is considered a mapping rather 
than a sequence because the lookups use arbitrary immutable keys rather 
than integers."

Then there is this: "iter(object[, sentinel])
... object must be ... or it must support the sequence protocol (the 
__getitem__() method with integer arguments starting at 0)."


> On the same topic, when I write a generator my docstring tends to come
> in one of two forms:
>
>    foo() yields values ...
>
> or
>
>    foo() returns an iterable ...

'Generator' is another area of confusion. Here is what the 
implementation says

 >>> def gf(): yield 1

 >>> type(gf)
<class 'function'>
 >>> g = gf()
 >>> type(g)
<class 'generator'>

I and as far as I know, most people, call gf a generator function 
(function that returns a generator) and g a generator, as in instance of 
class 'generator', just as 'a list' is an instance of class 'list'.

Unfortunately, whoever wrote the glossary contradicted the language and 
called gf a 'generator' and g merely an 'iterator'. It is, but 
generators are an important subcategory of iterator with extra api and 
currently unique suspend-resume behavior. Actually, the entry 
contradicts itself and later uses 'generator' as I have, to refer to the 
class 'generator' instance whose .__next__ method suspends and resumes. 
I will have to propose a patch.

> I find the first clumsy, but tend not to think of generators as "returning"
> an iterable as a single action. But of course they do, don't
> they:

A generator function returns a generator, which is a sub-category of 
iterator, which is a sub-category of iterable. A generator function is 
not an iterable itself, because it does not have a .__iter__ method. 
Since there are minor api differences between generators and other 
iterators, I think the docstring should be specific. For gf above, I 
would say "Return a generator that yields 1."

Note that the Python docs are intended to consistently say 'return' 
rather than 'returns'. If the return is the default None, they use some 
other imperative verb such as 'convert' or 'invoke'. I try to do the 
same so I will have that habit when I work on them.

As far as I know, generators are only constructed from Python-coded 
generator functions and expressions, so that there are no built-in 
generators. Still, generators are the easiest to write Python 
equivalents of the various built-in iterator types, such as those in 
itertools. So there are no trivially found generator doc examples that I 
know of, though there must be some in some Python-coded module.

---
Terry Jan Reedy