Alternative Deferred howto

[jml]

I've written a document based on a talk I gave years ago. I think it might be appropriate for inclusion in core Twisted documentation.

The document can be found here:  https://gist.github.com/4040065

Next steps are to make a branch & submit for review properly, but I'd welcome feedback in the mean time.

[radix]

I really like the document you wrote, but I don't think it'd be a good idea to create an "Alternative" Deferred howto. I'm not trying to provide stop energy, though. I just think your document should just replace the existing howto after it's been checked for "feature parity" or whatever.

[radix]

[1] By the way, I noticed a typo. In your explanation of addBoth, you say it's equivalent to d.addCallback(g, g), which should have an "s" as in "addCallbacks".

[jml]

Thanks, I'm glad you like the doc. I've fixed up that typo in my local copy.

I've done basically zero thinking on how it should integrate with the rest of the documentation beyond what you just said: that it should do so rather than be chucked in.

I like the idea of expanding it to match the existing doc for feature parity. Another idea might be to have two docs, with this one being the intro and the second being a reference. Or one doc being "using Deferreds" and the other one being "writing Deferred-returning code". Hmm. I'll try a couple of things & see what I like.

[jml]

(In [36564]) Branching to 'alternative-deferred-6180'

[jml]

I've added the document as "Introduction to Deferred", have converted to Lore, and added an introduction and conclusion, as per the writing standard.

I tried doing a pass over the existing deferred document, but my eyes are glazing over. I'd very much appreciate it if someone (the reviewer perhaps?) could identify the bits in that doc that aren't necessary given the addition of the introduction.

I've used em as the way to mark up the first use of a technical term. I'm not sure if that's correct.

Feedback welcomed!

jml

[jml]

(In [36583]) Recommended changes from Chipaca (refs #6180). Thanks!

 http://dpaste.org/PWOZE/

[lewq]

I think the document is great, it would definitely have helped me when I first learned about Deferreds. A few minor niggles:

Line 29:

  assumes no knowledge of Twisted.  Understanding what an asynchronous will

Perhaps this should be "an asynchronous function"? Or if it's really not necessary to understand what an async function is, perhaps you could drop the whole "Understanding..." sentence?

'em' seems like a fine tag to use for initial definitions of things.

          Why <q>roughly</q>?  Because if <code class="python">f</code>
	  raises, <code class="python">g</code> will be passed a <code class="API"
	  base="twisted.python.failure">Failure</code> object representing the
	  exception.  Otherwise, <code class="python">g</code> will be passed the
	  asynchronous equivalent of the return value
	  of <code class="python">f()</code> (i.e. <code class="python">y</code>).

This bit is hard to parse at first glance because of the large number of single letter variable names. It's not obvious why 'y' is equivalent to 'f()' until you realise it's on the LHS of the assignment operator, so maybe drop the brackets. Personally I preferred the contrived examples to the single letter variables, but either way.

It's not clear from the comments above or the branch whether the doc is intended to replace the Deferred doc (defer.xhtml). I do think that it's better than the original (clearer and more engaging), but it doesn't cover failure.trap, nor does it have the diagrams which some might find helpful, so I'd propose perhaps keeping both, and making the new (simpler one) the default linked to from the Twisted website's documentation page, so long as the new one links to the old one for "further reading".

Cheers, Luke

[teratorn]

Hi jml,

Would like to drop in with a review also, if I may. I like the new intro document very much! Overall it strikes me as more approachable than the defer.html howto, especially for beginners or those new to async programming. I've been over the text several times, trying out structural modifications. I've attached a patch that, I think, makes significant structural improvements to the flow of the text, without changing your core messages much, if at all.

Let me know what you think - I mostly just tried to convey your ideas in simpler terms, perhaps more explicitly - and with slightly less, in my mind, "superfluous prose". Also I like the technique of taking an explict contrived example, then transitioning to generic variables. I think it helps study the different error handling forms without distraction. Cheers, and thanks again, -teratorn

[teratorn]

proposed rewording of various paragraphs

[jml]

(In [36934]) Branching to 'alternative-deferred-6180-2'

[jml]

(In [36935]) Branching to 'alternative-deferred-6180-3'

[jml]

(In [36939]) Remove unnecessary, poorly-formed sentence, per lewq's advice

* refs #6180

[jml]

(In [36940]) Factor in most of teratorn's suggestions.

* refs #6180

[teratorn]

OK checked over the diff - looks pretty good to me. It's just missing a newsfile. Please merge after adding one! :)

[rwall]

I get this when I view it directly in Firefox.

• http://twistedmatrix.com/trac/export/36948/branches/alternative-deferred-6180-3/doc/core/howto/defer-intro.xhtml

Do you need the entity if the encoding is UTF-8?

XML Parsing Error: undefined entity
Location: http://twistedmatrix.com/trac/export/36948/branches/alternative-deferred-6180-3/doc/core/howto/defer-intro.xhtml
Line Number 18, Column 6:  yet&emdash;that's why you are here! 
-----^

[teratorn]

Dang, for some reason I thought that was right without checking the lore processed output :( I guess it is supposed to be "mdash" not "emdash" ?

[jml]

(In [37046]) Fix incorrect HTML markup for dash (refs #6180)

[jml]

rwall, you need to browse the HTML generated by lore, rather than the XHTML document.

teratorn, fixed. I've also run the lore build locally and verified that the output has no errors and the doc looks good.

The TwistedDevelopment page says how:

cd ./path/to/Twisted-checkout/doc; ../bin/lore/lore --config template=core/howto/template.tpl

[jml]

(In [37047]) Add NEWS file (refs #6180)

[teratorn]

Thanks jml. I've been through the doc once more and fixed two typos in the branch. Also the conclusion, though there is nothing actually *wrong* with it - it seemed like a bit bland to me, and I thought it could be worded in a way to sound a bit more, "active", perhaps? Patch attached, just "sounds better" to my ear - let me know what you think :)

+1 to merge either way.

[jml]

I've applied the patch on the final paragraph. I prefer the "You have been ..." bit as is, even though it's not as active, because it permits the bullet point items to be more actively phrased. Thanks very much for the suggestions though, and the typo fixes.

Merging now.

[jml]

(In [37070]) Introductory howto on using Deferreds

Author: jml

Reviewer: teratorn

Fixes: #6180

Document explaining how Deferreds work and how to map basic Python control flow to Deferreds. The existing Deferred howto is now linked as a reference document.