Question

I’ve been looking at twisted for a while now. It looks interesting – it seems like a good way to leverage a lot of power when writing servers. Unfortunately, in spite of writing a few web servers using twisted.web (from reading other people’s source and an extremely dated O’Reilly book) I’ve never really felt like I had reached an affinity with twisted… a level of understanding that actually gave me some of the power it seems like it has.

I think I need some good documentation to arrive at a better level of understanding – I simply don’t have time to pore over the source, and other threads on SO have mentioned twisted’s official documentation, which is patchy at best, absent at worst, and occasionally very out of date.

Is there anything else out there that is more thorough, more forgiving, and more useful, or am I stuck with another classic, boring STFU and RTFM even though TFM is not helpful?

---

Update

In response to JP Calderone’s comment that I’m just having a bitch, to some extent I guess I am, but I think the breadth of the question is valid considering the breadth and value of Twisted and the lack of obvious, thorough documentation. I have a few things in mind that I wanted to investigate, but I’ve been getting OK results just hacking things together and asking for specifics when a deeper, broader understanding is what I’m looking for is, in my mind, not helpful.

The contrast that immediately springs to mind is Django… I can read over the (very thorough) Django documentation and not necessarily know how to do everything it can do immediately, but I can get a really good overview of how I might do everything I needed to do, and know exactly where to look when the time comes.

Answer 1

I’m going to repeat what some of the answerers here have said (they’re all good answers) in the hopes of providing an answer that is somewhat comprehensive.

1. While the included documentation is spotty in places, the core documentation contains several helpful and brief introductions to the basic concepts in Twisted. Especially, see Using Deferreds, Writing Clients and Writing Servers.
2. Also, the API documentation – especially the documentation in interface modules – is increasingly thorough and coherent with each subsequent release.
3. If you’re interested in a higher-level description of Twisted’s goals and design so you know how to approach some of this other documentation, I co-authored a paper presented at USENIX 2003 with Itamar Turner-Trauring.
4. Twisted’s FAQ is also a bit meandering, but may help you with many stumbling blocks that people hit when working their way through introductory material.
5. The O’Reilly book about Twisted has some great examples which may further elucidate core concepts like Deferreds and the Reactor.
6. Jean-Paul Calderone’s “Twisted Web In 60 Seconds” tutorials are a good introduction to the somewhat higher-level twisted.web, of course, but you will also see lots of useful patterns repeated throughout which may be useful to you in whatever application you’re writing.
7. I have written a pair of articles on building-blocks used within Twisted, to deal with the filesystem and to load plugins.
8. Last but certainly not least, Dave Peticolas’s modestly titled “Twisted Intro” is a very comprehensive description, with diagrams and anecdotes, on the introductory material that so many people have difficulty with.

Please also note that all new functionality comes with new API (i.e. reference) documentation; we hope that this will make it more reasonable for people with technical writing skills to write documentation without having to struggle through even understanding what the method names mean.