[Twisted-Python] Re: [Twisted-commits] Updated defer.html so that the first 4 examples are runnable, split the 3rd
golux at comcast.net
Sun Mar 9 01:12:22 EST 2003
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. ...
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.
More information about the Twisted-Python