[Twisted-Python] Deferred documentation rewrite

Itamar Shtull-Trauring itamar at itamarst.org
Fri Jul 31 22:16:39 EDT 2009

On Fri, 2009-07-31 at 18:40 -0400, Edward Z. Yang wrote:
> You can view an initial draft of the rewrite here:
> http://ezyang.com/twisted/defer2.html
> For reference, this is the planned outline (X means done, ? means
> almost done):
> X Synchronous to Asynchronous: The Method to the Madness
>     X Convert synchronous code to asynchronous code
>     X Why asynchronous?

It's great you're working on this! The docs on deferreds certainly need

The problem with this is that it perpetuates the misunderstanding the
Deferreds *make* things asynchronous, even with the intro that says
otherwise. I think it's better to assume already asynchronous code,
handling the transition from synchronous to async in an intro event loop

A better comparative exposition might be with normal callbacks, e.g.:

"def foo(x, gotResultCallback): pass" vs. "def foo(x): # return

At the very least having that async but callbacky version in the middle
helps understanding.

It also omits half the story: how you *create* Deferreds. There should
be a section on that as well.

An example involving a parser, where you just wave your hands about who
pushes data in to the parser exactly (so no need to go into event loop
details), may work well. In particular, the object that wants the result
of the parsing wants to get parse errors, *not* whoever pushes data in.
Often it's same object, but not always. Deferreds help with that.

More information about the Twisted-Python mailing list