[Twisted-Python] Deferred documentation rewrite

[Terry Jones]

> Right.  Everything you could do synchronously, you can do asynchronously
> (and a bit more too).  It just /looks/ really weird.

At some point I realized that it helps to realize that code that looks
synchronous really isn't at all. Probably all the programming that almost
all of us will ever do is not synchronous. You type

  x = y + 3

and you get into the habit of thinking that x just got assigned the value
of y + 3. But there's a whole set of levels of operations, all invisible to
you, that are frantically rearranging atoms behind the scenes to pull off
this tiny miracle. Instead of trying to wrap your head around the so-called
"weird" asynchronous operation of Twisted, it's easier to let fall the
comforting illusion that you're in the synchronous world to begin with -
whatever that's supposed to mean (it's more like a fairy tale IMO). You're
not.

It's more accurate to think that that line of code arranges for x to
*eventually* hold the value of y + 3. Then it's a small step to thinking
that

  x = y + 3
  z = f(x)

is just another slightly bigger part of the same illusion. Those lines of
code aren't executed one after another at all. You're just brought up with
the fairy tale that they are - or at least you study computer science and
spend so much time with high-level languages that you start to take it for
granted that they are done one after the other. But the second line is
*eventually* executed after the first, assuming nothing went wrong (e.g., y
could be None).

At that point - everything is asynchronous - you have the right mindset to
think perfectly clearly about Twisted code. And there's no jump to make at
all. The only things you have to get your head around are 1) the fact that
Twisted code doesn't give you the comforting linear illusion of so-called
synchronous code as you type it in your editor (inlineCallbacks helps a lot
with improving that), and 2) that Twisted's deferreds are the way of
maintaining the flow of results (both correct and incorrect) through time
as your program executes. I.e., you've lost the step-at-a-time line-by-line
results computed on line N are available on line N+1 flow of code you can
so easily read in your editor, and in exchange you have deferreds.

I could go on, obviously :-) But I just wanted to point out that the shift
from thinking "synchronously" to "asynchronously" is much easier to make if
you realize the former is a convenient illusion and in fact you've always
been doing things asynchronously.

Terry