Opened 2 years ago

Closed 21 months ago

#6180 enhancement closed fixed (fixed)

Alternative Deferred howto

Reported by: jml Owned by: jml
Priority: normal Milestone:
Component: core Keywords: documentation
Cc: teratorn@… Branch: branches/alternative-deferred-6180-3
(diff, github, buildbot, log)
Author: jml Launchpad Bug:

Description

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.

Attachments (2)

proposed.rewords.patch (3.0 KB) - added by teratorn 21 months ago.
proposed rewording of various paragraphs
deferred-conclusions.patch (2.2 KB) - added by teratorn 21 months ago.

Download all attachments as: .zip

Change History (26)

comment:1 Changed 2 years ago by 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.

comment:2 Changed 2 years ago by 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".

comment:3 Changed 2 years ago by 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.

comment:4 Changed 23 months ago by jml

  • Author set to jml
  • Branch set to branches/alternative-deferred-6180

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

comment:5 Changed 23 months ago by jml

  • Keywords review added

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

comment:6 Changed 23 months ago by jml

  • Owner jml deleted

comment:7 Changed 22 months ago by jml

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

http://dpaste.org/PWOZE/

comment:8 Changed 22 months ago by 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

comment:9 Changed 21 months ago by lewq

  • Keywords review removed
  • Owner set to jml

comment:10 Changed 21 months ago by teratorn

  • Cc teratorn@… added

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

Changed 21 months ago by teratorn

proposed rewording of various paragraphs

comment:11 Changed 21 months ago by jml

  • Branch changed from branches/alternative-deferred-6180 to branches/alternative-deferred-6180-2

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

comment:12 Changed 21 months ago by jml

  • Branch changed from branches/alternative-deferred-6180-2 to branches/alternative-deferred-6180-3

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

comment:13 Changed 21 months ago by jml

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

comment:14 Changed 21 months ago by jml

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

comment:15 Changed 21 months ago by jml

  • Keywords review added
  • Owner changed from jml to teratorn

comment:16 Changed 21 months ago by teratorn

  • Keywords review removed
  • Owner changed from teratorn to jml

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

comment:17 Changed 21 months ago by rwall

I get this when I view it directly in Firefox.

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! 
-----^

comment:18 Changed 21 months ago by 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" ?

comment:19 Changed 21 months ago by jml

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

comment:20 Changed 21 months ago by jml

  • Keywords review added
  • Owner changed from jml to teratorn

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

comment:21 Changed 21 months ago by jml

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

comment:22 Changed 21 months ago by teratorn

  • Keywords review removed
  • Owner changed from teratorn to jml

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.

Changed 21 months ago by teratorn

comment:23 Changed 21 months ago by 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.

comment:24 Changed 21 months ago by jml

  • Resolution set to fixed
  • Status changed from new to closed

(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.

Note: See TracTickets for help on using tickets.