[Twisted-Python] documentation / kqueue / feedback

[J. Cliff Dyer]

On Wed, 2008-04-16 at 15:15 +0200, Dr aio wrote:
> Hi out there
> 
> Let me tell you about my experience with TM so far ...
> 
> Seeing there is doc. available, I digged through it. After all TM
> seems worth the effort. From what I see, I love TM.
> 
> Links are often broken, though. Often seemingly useful doc. is old,
> very old. Even current doc. isn't up to date.
> 
> Anyway, I try and I mean I try hard to get on my feet following some
> examples and snippets. The problem isn't the
> deferreds. I understand them pretty quickly and like them. The problem
> is that the docs are like a maze, irritating, frustrating and
> misleading rather than helping.
> 
> Trying to write a rpy. Of course, it doesn't
> work. Looking at all those different docs, I'm bewildered. Somehow hacking my way through it.
> They talk about "resource trees", yet I don't find them in the doc. I
> find putchild() but all examples and docs indicate, that you can do it
> only within the root resource.
> Again browsing, again looking desperately for some docs, that don't
> mislead and make things even more fuzzy. Falling over an article with
> some halfway useful tap doc.
> OK, a little later, I
> have my first web server running an my first rpy works, spitting out "test". Wow.
> 
> I'm wondering, why of all things "rpy" ? python won't generate sth.
> like "rpyc" for that, which translates in lost speed, I assume. No
> explanation. 
> 
> I'm on FreeBSD. Of course, I want to use kqueue. Now, another "funny"
> journey begins ...
> the py-kqueue in FreeBSD 6.3 and 7.0 is version 1.4. I remember,
> however, having read something by Isthmar Trauring Shtull (forgive me,
> if I didn't spell that correctly) that I need version 1.3 in order to
> apply his patch, which, of course (sorry, that's my disappointment
> carrying me away ...), doesn't work. No prob, I do it by
> hand. To no avail. That code is old, very old and it doesn't work.
> I remember havin seen some version 2 of pykqueue. Setup works nicely
> but Python/twisted coughs. The module has another name now. "(%"%§
> $( !!!
> So I fall back to the version 1.4 that comes with FreeBSD ports. It
> works. But in no-deamon mode only. As soon as I tell twistd to run
> web.tap deamonized it vomitts and breaks.
> 
> Intense googleing, and I mean "intense". Reading through years of this
> mailing list. No positive result.
> 
> What I say is said, because I love python an I consider twisted
> brilliant and immensely useful - theoretically. So, don't get me wrong
> and accept it as constructive, albeit somewhat pissed off remarks,
> OK :)
> 
> I have the clear impression that twisted is something in between a toy
> and a brilliant product. It's hackers, however, leave much to be
> desired in terms of usefulness. As it is, it's a great and promising
> hobby but not a useful product.
> 
> Sorry, but doc strings don't replcae a halfway decent documentation
> and a reasonable tutorial, considering the highly complex matter.
> Sorry, but documentation that is often enough outdated and sometimes
> offers broken links is next to useless.
> Sorry, but the most brilliant code is a lot less attractive and
> useful, if even "stable versions" are broken, in flux, etc ...
> 
> Kqueue seems to be vital to an event driven approach like TM, yet
> there are multiple versions of pykqueue floating
> around, none of them properly working (and I didn't fumble around. I plain simply used the FreeBSD port), some of 
> them with some mor and some with some less "annotations" (I refuse to call that doc.)
> 
> - How about getting 1 version of pykqueue properly running and into
> TM ?
> - How about freezing some TM version (like 8.0) and updating/matching
> docs? (Of course, experiments are funny and intriguing, but quite some
> of us out here need sth. stable for everydays work)
> - How about writing some complete docs and tutorials? Sth. along the
> lines of "My first web server wit TM" (instead all those - sometimes
> seeming to contradict each other - snippets)
> 
> I'm still fascinated by TM and still willingto invest time, efforts
> and
> brains. But I'd love to have some properly working base and docs that expßlain rather than confuse.
> 
> Looking forward to learn and enjoy.
> 
> (Yes, Should someone need sth. tested on FreeBSD, I'll gladly be of
> service)

Dr. Aio,

Have you tried the finger tutorial.
http://twistedmatrix.com/projects/core/documentation/howto/tutorial/index.html

It's certainly well more than a snippet, and goes through getting a
finger server up and running quickly, and then refactoring it for
greater robustness.

It doesn't answer all your concerns, but it's worth spending some time
on.  

Cheers,
Cliff