On Mon, Jan 31, 2011 at 10:58 PM, Jason Heeris <jason.heeris@gmail.com>wrote:

Hi,

I'd like to come to grips with Twisted, and so far I've been following and tweaking example after example. But I'm finding it incredibly hard to get a high level view of the Twisted "landscape" — and because I don't know what I don't know, it's hard to know what questions to even ask. I want to get to the point where I can just sit down and know where to start, and hopefully someone here can give me a bit of direction.

I understand many of the microscopic components. Deferred results, file descriptors and sockets, the reactor loop concept — I get those. I've read the tutorial[1], another Twisted Introduction[2], and about 50% of the API documentation (possibly not the right 50%, though).

But I just can't seem to wrap my head around the interfaces, factories and wiring it all together. Maybe some examples of the speedbumps I keep encountering will help:

1. The "finger" intro "Drop Connections" example[3] just straight out uses the self.transport member of a protocol. But how do I, a Twisted newbie, know that this even exists? After hours of digging around, I find it in the docs for a BaseProtocol method[4]. Later on, this same example uses the "self.factory" member. I still haven't found that one. Where do I look up these assumed-to-exist members? How do I know what other members exist?

Protocol objects typically (always) have a self.factory method, but you won't find it in the docs for a protocol. The factory has a method called buildProtocol ( http://twistedmatrix.com/documents/10.2.0/api/twisted.internet.protocol.Fact... ) which creates Protocol instances and sets the p.factory member to itself. So it does something like (in the Factory, so self is the Factory instance): p = self.protocol p.factory = self return p It's a pretty screwy API and is not particularly well documented anywhere. 2. What is a Factory, anyway? What are they *for*?

As Andrew said (or quoted) a Factory is an object which creates Protocol instances when a connection is made. Sometimes that's all there is to it, but they are often used to store state across connections. For example, if you want to know how many connections your IMAP (or whatever) server currently has open, putting a counter in the Factory which was incremented each time a connection starts (it creates a protocol) and decremented each time a connection closes would make sense. 3. The finger example goes over writing a server — what about an

asynchronous client that must follow a particular protocol? Where do I start with that? Is there an example?

You already found this one. :)

4. What if I'm not interested in networking? I primarily deal with serial lines, files and subprocesses... are there examples for those?

Not many, I don't think. I'm pretty sure there's a serial port example, though... (rummage, rummage) here it is! check out the mouse.py and gpsfix.py examples under /doc/core/examples ( http://twistedmatrix.com/trac/browser/trunk/doc/core/examples)

Points #3 and #4 are my motivation for using Twisted — I am currently mired in a pygtk program that uses threads and all sorts of locks and synchronisation mechanisms to send and receive data over a serial line, updating UI with progress, errors and success. I'd like to see if using Twisted simplifies things a bit, and I'll ask a more specific question about how to structure that when I can condense it to a reasonable level :)

I hope I'm not being too vague, but Twisted is rather large, conceptually, to absorb. I keep being pointed to the documentation for specific parts, but I have no idea how they fit together and that's what I'm really after.

Thanks, Jason

[1] http://twistedmatrix.com/documents/current/core/howto/tutorial/index.html [2] http://krondo.com/?page_id=1327 [3] http://twistedmatrix.com/documents/current/core/howto/tutorial/intro.html#au... [4] http://twistedmatrix.com/documents/current/api/twisted.internet.protocol.Bas...

A couple of us are getting fired up about cleaning up the documentation to make it easier for those new to Twisted to find what they're looking for, so please do speak up with any feedback you have. Kevin Horn