I think that: d.addCallback(cb) d.addErrback(eb) is the more common idiom because it avoids the double-helix nature of deferred handling, opting instead for a single node-to-node chain of handling, which is less complex conceptually. --snip!--

Another way of approaching the concept might be to say that each stage in the chain has to deal with the errors in the chain before it - that is, if you do:

d.addCallbacks(cb, eb)

then eb needs to handle any errors that arise from the data source, while if you do:

d.addCallback(cb) d.addErrback(eb)

then eb needs to handle any errors that arise from the data source, AND any errors that arise from cb.

I think that this chunk is the important concept to document. This explanation in addition to the imperitave example given by Stephen would ensure that this concept is documented and explained sufficiently. In fact, i'd never thought to consider deferreds as a try/except/else statement. very useful concept! It's funny, because when i read the original posting to this thread, I had the same confusion. "Waitasec, that errback /should/ get called!" this thread has helped to elucidate a subtle and important point about deferreds.