[Python-Dev] Re: anonymous blocks

[Steven Bethard]

On 4/28/05, Greg Ewing <greg.ewing at canterbury.ac.nz> wrote:
> Guido van Rossum wrote:
> > And surely you exaggerate.  How about this then:
> >
> >     The with-statement is similar to the for-loop.  Until you've
> >     learned about the differences in detail, the only time you should
> >     write a with-statement is when the documentation for the function
> >     you are calling says you should.
> 
> I think perhaps I'm not expressing myself very well.
> What I'm after is a high-level explanation that actually
> tells people something useful, and *doesn't* cop out by
> just saying "you're not experienced enough to understand
> this yet".

How about:

"""
A block-statement is much like a for-loop, and is also used to iterate
over the elements of an iterable object.  In a block-statement
however, the iterable object is notified whenever a 'continue',
'break', or 'return' statement is executed inside the block-statement.
 Most iterable objects do not need to be notified of such statement
executions, so for most iteration over iterable objects, you should
use a for-loop.  Functions that return iterable objects that should be
used in a block-statement will be documented as such.
"""

If you need more information, you could also include something like:

"""
When generator objects are used in a block-statement, they are
guaranteed to be "exhausted" at the end of the block-statement.  That
is, any additional call to next() with the generator object will
produce a StopIteration.
"""

STeVe
-- 
You can wordify anything if you just verb it.
        --- Bucky Katt, Get Fuzzy