[Twisted-Python] Deferred documentation.

Glyph Lefkowitz glyph at twistedmatrix.com
Wed Mar 30 13:20:04 EDT 2011

On Mar 30, 2011, at 11:09 AM, Christopher Armstrong wrote:

> Funny, that's what I got on my proprietary application (0.0597) :-) It's a heavily inlineCallbacks-based codebase, and I expect there would be a much larger number of addCallback/addErrback calls if it weren't. Also, looking at the actual uses of addCallbacks (15), they were all written by people other than me (relative Twisted newbies) and I don't think I would have used it where it's used now. This, I think, indicates that we *should* focus more on addCallback and addErrback in the documentation, and stress that they are almost always what you want to use instead of addCallbacks, but definitely point out where addCallbacks is useful.

addCallbacks() is used in places where you'd need a try/except/else in synchronous code; much less frequently than you'd need a try/except, but still enough that it's important.

However, in my experience, a novice's understanding of addCallbacks() is critically important to understanding other uses of Deferred as well; in particular, the "one chain of pairs of callback and errback" concept makes a lot of the behavior clear which might not otherwise be.  If you just vaguely know about chains of callbacks, you can easily get confused.

Some sample confusion that I believe I've heard over the years: thinking that addErrback only affects the previously-added callback, that there's only one errback for the whole chain but as many callbacks as you want, that the callback and errback chains are totally separate, and callbacks are run, then errbacks.

Granted, these types of confusion require more than simply glossing over addCallbacks(), but I do think that emphasizing the pairs-of-callbacks structure helps people get a full understanding of what's going on more quickly.  Of course, now that I've put this in a publicly-archived mailing list archive, a lack of understanding of addCallbacks won't be the problem any more.  People will be confused, search for some terms related to this confusion, and read only that one preceding paragraph of this message, and say to themselves "oh, that's how Deferred works", somehow holding all of those wrong ideas in their head at once, forever.  Hooray for the internet.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://twistedmatrix.com/pipermail/twisted-python/attachments/20110330/26e91941/attachment.htm 

More information about the Twisted-Python mailing list