Opened 9 years ago

Closed 9 years ago

#3323 defect closed fixed (fixed)

DeferredList Documentation Lies!

Reported by: nathan.stocks Owned by:
Priority: normal Milestone:
Component: core Keywords:
Cc: Branch: branches/deferredlist-docs-3323
branch-diff, diff-cov, branch-cov, buildbot
Author: exarkun

Description (last modified by Jean-Paul Calderone)

This section on DeferredList's is incorrect:

http://twistedmatrix.com/projects/core/documentation/howto/defer.html#auto7

From the section of the above page:

> # At this point, dl will fire its callback, printing:
> #     [(1, 'one'), (0, 'bang!'), (1, 'three')]
> # (note that defer.SUCCESS == 1, and defer.FAILURE == 0)
> 
> A standard DeferredList will never call errback.

Here's the actual output when run in Twisted 8.0.1:

$ python test_DeferredList.py 
/Library/Python/2.5/site-packages/twisted/internet/defer.py:262: DeprecationWarning: Don't pass strings (like 'bang!') to failure.Failure (replacing with a DefaultException).
  fail = failure.Failure(fail)
[(True, 'one'), (False, <twisted.python.failure.Failure <class 'twisted.python.failure.DefaultException'>>), (True, 'three')]
Unhandled error in Deferred:
Traceback (most recent call last):
Failure: twisted.python.failure.DefaultException: bang!

I see three problems:

  1. The deprecated behaviour. (Passing a string to an errback?)
  2. Output doesn't match. (defer.SUCCESS and defer.FAILURE are True and False, respectively, not 1 and 0)
  3. The docs say "A standard DeferredList will never call errback.", but it appears that an errback was actually called.

Attachments (1)

test_DeferredList.py (486 bytes) - added by nathan.stocks 9 years ago.
A file that has the sample code in question in a runnable form.

Download all attachments as: .zip

Change History (9)

comment:1 Changed 9 years ago by Jean-Paul Calderone

Description: modified (diff)

fixing description markup

Changed 9 years ago by nathan.stocks

Attachment: test_DeferredList.py added

A file that has the sample code in question in a runnable form.

comment:2 Changed 9 years ago by Jean-Paul Calderone

author: exarkun
Branch: branches/deferredlist-docs-3323

(In [24188]) Branching to 'deferredlist-docs-3323'

comment:3 Changed 9 years ago by Jean-Paul Calderone

(In [24189]) Correct the example (with output) for DeferredList

refs #3323

comment:4 Changed 9 years ago by Jean-Paul Calderone

Keywords: review added
Owner: Glyph deleted

comment:5 Changed 9 years ago by nathan.stocks

It appears that the third concern I listed is a misunderstanding on my part. The statement "A standard DeferredList will never call errback." from the documentation does not mean that errors from Deferreds in the DeferredList will be consumed, it only literally means that errback is never called on the DeferredList itself.

It may be helpful to simply state earlier in the documentation something to the effect of "you still need to handle errors in your Deferreds by adding errbacks to them, unless you are going to use the consumeErrors option talked about later."

The other two concerns still stand.

comment:6 Changed 9 years ago by Stephen Thorne

Keywords: review removed
Owner: set to Jean-Paul Calderone

I've tested this code manually in a python interpeter, and am happy with the code listing and the updated paragraph. I think this can be merged.

comment:7 Changed 9 years ago by Jean-Paul Calderone

Resolution: fixed
Status: newclosed

(In [24216]) Merge deferredlist-docs-3323

Author: exarkun Reviewer: jerub Fixes: #3323

Change some of the DeferredList documentation in the deferred howto so that it doesn't use deprecated features (string exceptions), notes that SUCCESS and FAILURE are booleans now, not boolean-style integers, and uses and mentions the consumeErrors feature of DeferredList to avoid putting a confusing failure report onto stdout.

comment:8 Changed 6 years ago by <automation>

Owner: Jean-Paul Calderone deleted
Note: See TracTickets for help on using tickets.