[Twisted-Python] Re: [Twisted-commits] Updated defer.html so that the first 4 examples are runnable, split the 3rd

[Andrew Bennetts]

On Sun, Mar 09, 2003 at 01:12:22AM -0500, Steve Waterbury wrote:
> As one who has perpetual newbie-mind, I feel I should comment ...

Excellent :)

I was worried that my criticisms were based too much from the perspective of
someone who is already familiar with Deferreds.

> On Sat, 2003-03-08 at 20:49, Andrew Bennetts wrote:
[..snip..]
> > Not all example code
> > in the Howtos must be immediately executable standalone... I think perhaps
> > this example code would be better in the doc/examples directory, where it is
> > more appropriate for examples to be verbose like this.
> 
> Here I disagree.  Newbies are generally served better by 
> examples with lots of (germane) comments ... but not 
> extraneous stuff, like the Timer.  And I think it would be 
> "nice" if they were executable, but if it comes down to 
> choosing between clarity and executability, clarity should win.  

Yeah, true.  I over-emphasised a bit.  I guess I was thinking that the
Deferred doc is already quite long, and padding it with more examples that
are quite similar could be detrimental.  I certainly have no objections to
adding comments :)

> > > -<p>There are several things missing in this simple example.  There is no way to
> > > -know if the data never comes back; no mechanism for handling errors.  There is
> > > -no way to distinguish between different calls to gotData from different
> > > -sessions.  <code>Deferred</code> solves these problems, by creating a single,
> > > -unified way to defer execution of code that depends on blocking calls.</p>
> > > +<p>There are several things missing in this simple example.  There is no way
> > > +to know if the data never comes back; no mechanism for handling errors.  The
> > > +example does not handle a multiple callback functions, nor does it give a
> > > +method to merge arguments before and after execution.  Further, there is no
> > > +way to distinguish between different calls to gotData from different
> > > +producer objects. <code>Deferred</code> solves these problems, by creating 
> > > +a single, unified way to handle callbacks and errors from deferred
> > > +execution.</p>
> > 
> > What does "merge arguments before and after execution" mean to a Twisted
> > newbie?  Why would they want to do it?
> 
> Here I disagree again.  I think I know what is meant (although 
> clarity could be improved, again), and it was one of the first things 
> I wanted to do ... of course, it didn't take too long to suss that 
> lambdas are the preferred idiom for that ... 

Asking "Why would they want to do it?" wasn't meant to question that newbies
wanted to do it.  I meant to point out that it was referring to a concept
that wouldn't be clear to many newbies, and would thus serve to confuse them
because they didn't know what it meant or why it might apply to them.
"Merging arguments" isn't terminology I've ever heard before, in Python or
elsewhere, so if I was a newbie I'd be wondering if this was yet another
Twisted thing.

Probably explicitly spelling out that chaining callbacks is useful for
progressively munging data is worth doing, though, maybe with an example
like:

    d = getItemsFromDB()

    def convertResultlistToHTML(results):
        return '<ul>' + ['<li>' + x for x in results] + '</ul>'
    d.addCallback(convertResultlistToHTML)

Or should it be more contrived?  E.g.:

    d = getNumber()
    d.addCallback(lambda r: r + 10)       # Add ten
    d.addCallback(lambda r: 1.0 / r)      # Take the reciprocal
    def catchDivByZero(failure):
        failure.trap(ZeroDivisionError)
        return 0
    d.addErrback(catchDivByZero)
    d.addCallback(lambda r: '%0.3f' % r)  # Convert to string of up to 3
                                          # decimal places
    d.addCallback(lambda r: '<b>%s</b>' % r) # Wrap in HTML

Is it already clear to newbies how callbacks chain and what they are good
for?

> > ....  I think I'd also like
> > to add back the comment about "This is an asynchronous equivalent of ..." --
> > perhaps it's overly jargonistic, but it is the way I think about Deferreds;
> > they are the primary tool Twisted provides to abstract away blocking
> > operations into a fundamentally asynchronous framework.
> 
> Total agreement.  If they don't know what "asynchronous" 
> means, they can look it up!  Sheesh, it's a standard term.  
> (Twisted-specific jargon is not a problem in the docs 
> either, as it is always defined when introduced.)

And Twisted-specific jargon should be added to the glossary, where possible.
Possibly 'asynchronous' should be added too, if it isn't already there.

> > Again, with the next two examples I think you've obscured the point in your
> > efforts to make everything explicit.  I'd rather have a 10 line example
> > that illustrates a concept, than a 20 line example that obscures the same
> > concept behind irrelevant method definitions, etc.  ...
> 
> Agreed also.  
> 
> That said, I think there are cases where the in-line examples seem
> a trifle too elliptical.  I'll have to be more specific, I know, 
> so I'll send an example when I have time.  

Patches are, of course, welcome :)

-Andrew.