PEP 318

[David Eppstein]

In article <c3r8c6$2b5g98$1 at ID-169208.news.uni-berlin.de>,
 "Greg Ewing (using news.cis.dfn.de)" <ieyf4fu02 at sneakemail.com> wrote:

> Eyal Lotem wrote:
> > You are not supposed to be looking for it, IMHO.
> > Generators follow the Sequence protocol and are to be
> > treated as sequences.  Thus, you should simply make it
> > clear in the
> > function-name/conventions/interface-documentation that
> > the function returns a sequence.  Whether that
> > sequence is implemented via a generator or not is an
> > implementation detail.
> 
> That may be true when you're *using* the generator, but
> when looking at the implementation, it can be helpful
> if you're warned ahead of time that you're wading into
> generator code, to get you into the right frame of
> mind.
> 
> I had that experience just the other day -- started
> reading a function, had some moments of wondering
> "how does this work?", then thought "oh, I know, I
> bet this is a generator"... skimmed through it, and
> sure enough, there was a 'yield'.

I think this can be alleviated by following a convention of using 
"Yields" as the first word of the docstring for all simple generators.  
E.g., http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/117119

Of course, that doesn't help for code not following the convention...

-- 
David Eppstein                      http://www.ics.uci.edu/~eppstein/
Univ. of California, Irvine, School of Information & Computer Science