<div class="gmail_quote"><div>OK, I'm already making a lot of these changes, I should have a new version Up Soon (TM).<br></div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
<div style="word-wrap: break-word;"><div><div class="im"><blockquote type="cite"><div>Placeholders.<br></div></blockquote><div></div></div><div>Placeholders for what, though?</div></div></div></blockquote><div> <br>Placeholders for that magic lib, that I think I'm going to stop looking for and say, "demonstration purposes only"<br>
<br><div class="im"><blockquote type="cite"><div><blockquote type="cite">How do they use it? Why is it relevant?<br></blockquote>I guess I'm stupid or slow, but it took a while for me to realize that<br>Deferreds were basically a standardized callback mechanism. It's not<br>
really written anywhere on the tin: Deferred was to me a bit of an<br>unobvious name for what it does, and before recently I've always<br>associated it tightly to scheduling and the reactor.<br></div></blockquote><div>
</div></div><div>No, this is a common problem. I think it would be great to address the definition a bit more comprehensively.<br></div></div><div><br>Through example?<br><br></div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
<div style="word-wrap: break-word;"><div><div class="im">It does seem to be a bit disconnected from the flow of the regular text. Perhaps it would be better if it were laid out as a paragraph, and then each sentence, or clause, were examined more closely, perhaps with an accompanying code snippet to clarify it. <br>
</div></div></div></blockquote><div><br>As I said, I don't want to explain that snippet. I just want to put it there, ignore it, and hopefully the user will understand more of it as the tutorial goes on.<br></div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
<div style="word-wrap: break-word;"><div><div class="im"><blockquote type="cite"><div><font color="#000000"></font>Right now, it's a placeholder for that magic library that I haven't found yet.<br></div></blockquote>
</div><div class="im">I can see why you might want to do that. In the narrative flow between urllib and Deferreds, there is a missing step; you may need to fake that out. I'm just saying that you should be very clear and say "this is a fake example, merely for the purpose of illustration". I think that Tornado has some ugly callback-based stuff, but it would be better to leave this example fake than to try to teach users how to use that.<br>
</div></div></div></blockquote><div><br>Will do.<br> </div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;"><div style="word-wrap: break-word;">
<div><div class="im"><blockquote type="cite"><div>Are there specific changes you find that could make it harder to read<br>for newcomers?<br></div></blockquote><div></div></div><div class="im">I thought my previous message was a list of those :-(<br>
</div></div></div></blockquote><div><br>Well, it was a draft, and I felt that most of my changes were already improvements over what was there. I didn't expect it to be "harder to read for newcomers".<br></div>
<blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;"><div style="word-wrap: break-word;"><div><div class="im"><blockquote type="cite"><div>The concept of Deferreds isn't hard at all, once you understand what<br>
they are. The subtle nuances and bits of glue code that Twisted are<br>the things that can trip someone up, and what I'm still learning. A<br>small amount of very specific use cases for Deferreds happen in<br>real-world code and I'd like to show the support that Twisted has for<br>
them built-in.<br><br>My goals for this document are:<br><br> 1) A list of guaranteed rules about Deferreds for reference at any time.<br> 2) An introduction to those rules in a format that doesn't require<br>knowledge of others.<br>
3) Showing techniques or tricks that you can play by "exploiting"<br>parts of those rules in the context of a contrived problem.<br> 4) Showing the built-in support for it.<br></div></blockquote></div><div class="im">
My first goal for this document would be a clear, concise explanation of what a Deferred is and why you need it.<br></div></div></div></blockquote><div><br>As I said, when you understand what a Deferred is, it's not hard. The hard part is *how* to use it. The urllib, fake library, Deferred example is all I really want to go over about what a deferred is, because it's not hard. I want to: untie a lot of the code samples from the reactor, explain in terms of the two other examples that it's fundamentally the same thing, then and go on to the techniques like errbacks, chaining callbacks, and how separating the callback from the request allows things like DeferredList/gatherResults.<br>
</div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;"><div style="word-wrap: break-word;"><div><div class="im"><blockquote type="cite"><div>
This should help clear up my writing style a bit. I think in terms of<br>separating abstraction layers; I always try separate a fact or rule<br>from logic or a technique that can follow when you can exploit that<br>fact (feel free to ask the people about 'evolution' in<br>
#python-offtopic). I also try to think of the code being very linear<br>when it evolves: a new rule is added, you have a problem, you can<br>exploit that rule with a specific technique, the technique is<br>standardized.<br>
<br>Example A:<br> PROBLEM: You need to create a Deferred with a known result<br> RULE: Callbacks will continue running after you've called "callback"<br>or "errback"<br> TECHNIQUE: You can create a Deferred, call 'callback' on it and<br>
return it, without any tricky business<br> STANDARDIZED: twisted.internet.defer.success<br><br>Example B:<br> PROBLEM: You need to get the results from multiple Deferreds without<br>blocking or too much linearity<br> RULE: More than one Deferred can be created and 'run' at the same time<br>
TECHNIQUE: You can add a callback to a Deferred, take the result you<br>get and save it in a list or dictionary<br> STANDARDIZED: DeferredList, gatherResults<br></div></blockquote></div></div></div></blockquote><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
<div style="word-wrap: break-word;"><div><div>These seem more like recipes to me than introductory documentation. Maybe they should be really close together, to try to drive the concept home, but it would be good to really get it clear in the reader's mind why they <i>fundamentally</i> need Deferreds, then to cover all the subtle <i>different</i> ways you might need them and how you could use them.<br>
</div></div></div></blockquote><div><br>But you don't <i>fundamenally</i> <i>need </i>Deferreds at all. The new document isn't going to convince them that they're the right thing or wrong thing, just to show how to get along in their new home in Deferred-ville, USA. For the recipes, they're going to be reading real-world Twisted code, they better know what these recipes do.<br>
<br>And if you can think of some subtly different ways to use them other than the generic "something is happening in the future, I better be prepared for it", I'll put it in the document and attempt to eat my hat.<br>
</div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;"><div style="word-wrap: break-word;"><div><div class="im"><blockquote type="cite"><div>
*snip* <br></div></blockquote></div></div></div></blockquote><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;"><div style="word-wrap: break-word;">
<div><div class="im"><blockquote type="cite"><div>( Also, this is a real recipe, ableit simplified and it makes really<br>easy, delicious chocolate mousse:<br><a href="http://articles.latimes.com/2008/feb/13/food/la-fo-watch13recafeb13" target="_blank">http://articles.latimes.com/2008/feb/13/food/la-fo-watch13recafeb13</a> )<br>
</div></blockquote><div><br></div></div><div>This looks like a fantastic example. It's comprehensible, concrete, not too long, and involves a strict metaphor for a real world situation, without mixing in any obscure technology. I would be happy if the entire Deferred tutorial were to be structured around it.</div>
</div></div></blockquote><div><br>Except it really breaks that "runnable examples" thing. As I said before, recipes are a very convenient match for asynchronous code, but it's not realistic to try to map 1:1 to the other.<br>
</div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;"><div style="word-wrap: break-word;"><div><div>You could also tweak it to introduce additional concepts. For example, errbacks: "If the butter burns...".</div>
</div></div></blockquote><div><br>If the butter burns.... what do I do? Turn off the heat, clean the pan, and restart some more butter? What if I run out of butter? Do I need a "goToStoreToFetchButter" function? Is that another tutorial I should write?<br>
</div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;"><div style="word-wrap: break-word;"><div><div class="im"><blockquote type="cite"><div>
Once I *knew* what a Deferred was, the other pieces started snapping into place.<br></div></blockquote></div><div>So it sounds like we're in agreement here: the existing document isn't clear enough about exactly what a Deferred is, it's described too formally and its uses aren't clear enough before we start diving into the technical specifics. Any modification should strive to make it super clear what it is and why you use it.<br>
</div></div></div></blockquote><div> <br>When I started with Twisted, I used Deferreds because "everything else in Twisted uses it". I didn't really *try* to understand it too much, either. Most of the time I used Twisted, I tried to hack it all up with inlineCallbacks and pretend it was urllib, and then complain in #twisted with a code snippet when it wasn't working.<br>
<br></div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;"><div style="word-wrap: break-word;"><div><div class="im"></div><div class="im">Use 'localhost' URLs and have the user run a 'twistd web' command line for their server; that should be simple enough :).<br>
</div></div></div></blockquote><div class="im"><br>For static pages, is there anything fundamentally wrong with "<a href="http://twistedmatrix.com/documents/11.1.0/static/pi.txt">http://twistedmatrix.com/documents/11.1.0/static/pi.txt</a>", if I can do it?<br>
</div></div>