Re: [Twisted-Python] Deferred documentation.

[Jasper St. Pierre]

Big wall of text incoming. If you're going to read any part of this
email, search for *IMPORTANT* and read that part.

Right now I'm stuck at creating a simple example for "deferred dependencies".

On Tue, Mar 22, 2011 at 10:03 PM, Glyph Lefkowitz
 wrote:
> On Mar 21, 2011, at 9:30 PM, Jasper St. Pierre wrote:
>
>> On IRC, exarkun, glyph, spiv and idnar encouraged me to do a bit of
>> work on the Defer documentation.
>
> Yay!  This documentation could definitely use some work.
>
>> I kept get confused between the things like returning a Deferred from a
>> callback and chainDeferred, which I found out wasn't that useful:
>
> Yeah, chainDeferred is not a great method.  Now that Deferreds are
> non-recursive, I think it's purely worse than inserting an additional
> Deferred as a result from a callback.
>
> My eventual goal is to reduce the number of documentation about defer
> down to a near-impossible two documents. I'm hoping to merge some of
> the good stuff of the other thousands of documents.
>
> That would be absolutely great.
>
>> Thoughts so far?
>
> While I applaud your intent, these drafts look quite rough.  The random
> interjections and asides in
>  seem distracting
> and confusing to me.  Trying to put myself in the mind of a newcomer, I find
> myself asking many questions which are irrelevant to what I'm trying to
> learn:
>
> What's "async"?  Why is it hard?  (The original document mentions
> asynchronous stuff, but in the context of full english sentences.)

Should I mention blocking with something like urllib, then showcase
another example library that uses regular callbacks?

> Where are we going shopping?  What does shopping have to do with this?

Pop culture reference. Killed.

> What's gevent?  Does this have something to do with Twisted?
> What's node.js?  This looks like Javascript, what does it have to do with
> Twisted, which I thought was in Python?

Placeholders.

> (Now I've gotten distracted and I'm reading about gevent and node.js rather
> than making my Twisted application work and completing the Deferred
> tutorial.  Epic fail.  But, if I were to continue...)
>
> What's "this pattern"?  Functions?  Don't lots of programs use functions?

I guess this is a bit obvious when you have first-class-functions as a
language feature, but it's still a "pattern."

> How do they use it?  Why is it relevant?

I guess I'm stupid or slow, but it took a while for me to realize that
Deferreds were basically a standardized callback mechanism. It's not
really written anywhere on the tin: Deferred was to me a bit of an
unobvious name for what it does, and before recently I've always
associated it tightly to scheduling and the reactor.

> Why is Twisted's right hand blue?  (Forget about being a beginner: I
> honestly don't even get this reference.  Googling seems to suggest it has
> something to do with symptoms of heart disease and doesn't seem funny or
> relevant at all.)

Another pop culture reference. Baleeted.

> Why is the first explanation of what a Deferred is referred to as "technical
> mumbo-jumbo"? Is this really complicated?  If I am not super good at
> programming already, should I not be reading this?

It was prefixed with "The abstract" before. I put it back to "The
abstract". To me, it seems like it's written in a way that makes sense
only if you understand what a Deferred is, but it was useful, so I
didn't rip it out. I see it as a paragraph that will make more sense
as you're reading the article, and once you go back and understand it,
there's that happy "snap" feeling as you get the concept.

> What's an "operation"?  Does that mean 'function' or 'method' or some other
> special thing?  It says "most operations in Twisted return a Deferred"; but
> I've called lots of functions in Twisted which returned other objects before
> reading this tutorial, or returned None.  Were those actually Deferreds?

Yeah, I need to reword that. How about, "because Deferreds are a core
part of Twisted, a lot of functions return them"? No... that's not
good either.

> Why do I "not know where this Deferred has been"?  Do Deferreds get dirty or
> broken somehow when I add multiple callbacks?  Should I avoid that?

Again, I fail at humor. Removed.

> The Python examples in the current Deferred Reference are mostly runnable.
>  The ones that aren't, should be.  The documentation should stress that you
> can run these examples simply, and encourage the reader to download and
> experiment with them, and modify them to see what happens when they do
> things in a different order.
> Instead, the "fixup" changes the first example to rely on a fake library,
> which will raise exceptions if I try to run it, but doesn't actually explain
> that 'magiclib' isn't real.  This isn't a huge problem in and of itself (it
> is trying to demonstrate the "wrong" way to do things, after all) but it
> sets up the expectation that the rest of the examples are fake, too,

[Twisted-Python] Old-class-only support in manhole

[Facundo Batista]

Hello!

Creating a test case for a change in twisted/manhole/explorer.py, I
found these lines in CRUFT_WatchyThingie.watchObject:

if type(object) is not types.InstanceType:
raise TypeError, "Sorry, can only place a watch on Instances."

Always talking in Python 2, if you pass an instance of an old style
class as the "object", it will be ok; but if you pass a new style
class, it will raise TypeError.

So, I wanted just to ask if this is on purpose, should I open a bug
about it, or what.

Thank you!

-- 
.    Facundo

Blog: http://www.taniquetil.com.ar/plog/
PyAr: http://www.python.org/ar/

___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python