[Twisted-Python] addCallbacks issue

[Andrew Bennetts]

On Tue, Apr 13, 2004 at 01:19:30AM -0700, Sorin C. wrote:
> Hi,
> 
> Yes, I saw this bit of documentation but what I
> understand from it is that if you chain multiple
> addCallbacks to the same deferred then the error
> handler from the last addCallbacks call will be
> called. What am I missing?

You misunderstand the documentation, which is a shame because that section
is there specifically to be as clear as possible about this point :(  I
wonder how we can do better?

Anyway, have another look at the diagrams in that page; they hopefully will
give you a clear picture of how the callback and errback chains interact.

> Anyway, the API docs say:
> """
> addCallbacks(self, callback, errback=None,
> callbackArgs=None, callbackKeywords=None,
> errbackArgs=None, errbackKeywords=None, asDefaults=0)
> 
> Add a pair of callbacks (success and error) to this
> Deferred.
> """

And this is correct.

> 
> So shouldn't 
> 
> addCallbacks(success, failure)
> 
> be equivalent with
> 
> addCallback(success)
> addErrback(failure)

Definitely not.

Deferred callback chains are a sequence of callback/errback pairs.  Calling
just addCallback or addErrback adds a pair where one half of that pair is
None.  When a Deferred is fired, it calls one of the items in each pair in
turn, depending on whether it's currently handling a result or an error --
but if the item it would call is None, it just moves directly to the pair
without doing anything.

That's a pretty hairy description that's better explained by the diagrams in
the Deferred howto, I think -- but suggestions (and ideally patches) on how
to improve the Deferred docs are of course welcome.

I guess the basic confusion is that people expect addCallbacks(good, bad) to
add 'good' and then add 'bad' to the sequence, when actually they are added
at the same place, which is why an exception in 'good' will be passed to the
next errback after 'bad'.

I've tried to avoid resorting to bad ascii art to explain this... let me
know if I've helped :)

-Andrew.