[Twisted-Python] Deferred documentation.

Jasper St. Pierre jstpierre at mecheye.net
Mon Mar 21 19:30:54 MDT 2011


On IRC, exarkun, glyph, spiv and idnar encouraged me to do a bit of
work on the Defer documentation. I kept get confused between the
things like returning a Deferred from a callback and chainDeferred,
which I found out wasn't that useful:

<idnar> I suppose it's useful for "forking" a deferred
<idnar> you have an "existing" deferred
<idnar> and you want a "new" deferred that starts with the value from
the end of the existing deferred's callback chain
<idnar> but you don't want the rest of the existing deferred's
callback chain to be affected by the new deferred's callback chain
<idnar> that's still not really a use case though, just a description
of the situation that must arise in the use case
<idnar> I guess I should search for actual uses of chainDeferred

Well, I was getting frustrated myself, and I suggested to fix the docs
once and for all. People pointed me to three documents, all of which
felt way too dense for me:

http://twistedmatrix.com/documents/current/core/howto/defer.html
http://twistedmatrix.com/documents/current/core/howto/gendefer.html
http://twistedmatrix.com/documents/current/core/howto/deferredindepth.html

Jessica also pointed me to http://twistedmatrix.com/trac/ticket/3943,
which admittedly I haven't read yet.

So, I started writing. I opened up a session of emacs, and produced two things:

http://magcius.mecheye.net/twisted/DeferHowTo-Rewrite.html
http://magcius.mecheye.net/twisted/DeferHowTo-Fixup.html

Sources:

http://magcius.mecheye.net/twisted/DeferHowTo-Rewrite.rst
http://magcius.mecheye.net/twisted/DeferHowTo-Fixup.lore

The former is a tutorial that I tried to make informal as possible,
and the latter is a fixup and rewrite of defer.xhtml stuff to make it
a bit less, uh, dense.

My eventual goal is to reduce the number of documentation about defer
down to a near-impossible two documents. I'm hoping to merge some of
the good stuff of the other thousands of documents.

Thoughts so far?




More information about the Twisted-Python mailing list