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

[Steve Waterbury]

As one who has perpetual newbie-mind, I feel I should comment ...

On Sat, 2003-03-08 at 20:49, Andrew Bennetts wrote:
> You've sacrificed clarity for runnability.  

Having read it carefully, I have to agree with Andrew here.  

> I'm not sure that's the right
> thing to do; the point of this example is now obscured behind details like
> how threading.Timer works, and spelling out a dummy "nonBlockingOperation"
> method where before it was quite clear without it.  

These were criticisms I had, too.

> 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.  

> Also, the way the example used to be reflected an idiomatic use in Twisted:
> where there is some event handler, e.g. onResult, fired at an arbitrary time
> by some external source.  Think of e.g. Protocol objects with dataReceived.
> The example as it was emphasised that Deferreds can apply equally well when
> you don't have control over when some event completes -- regardless of
> whether it came from a thread, or the network, or anywhere.

Which is almost always the case, of course.

> > -<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 ... 

> ....  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.)

> 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.  

- Steve.