[Twisted-Python] Re: Teach Me Twisted Redux

[Maarten ter Huurne]

On Thursday 20 March 2008, John Wells wrote:

> So, I bought the Oreilly book and Python in a Nutshell. I've made it
> through the Nutshell book (I spent 3 months doing python back in 2003,
> so it's not completely new to me). My next steps include the book
> first and online docs second...but now am I to understand that both
> are useless? Should I just dive into the code instead?

Although they are not perfect, they are certainly not useless.

The snake ball book gives a lot of examples of things you can do with 
Twisted. It doesn't go very deep into the fundamentals: deferreds, 
transports, protocols and Zope interfaces are all important building blocks 
in Twisteed and of these, only deferreds are explained in some detail. It 
doesn't go very deep into web servers either, but that's not really the 
book's fault (page 54 explains the problem). The book is from 2005, so 
recent developments like inlineCallbacks and AMP are not in it.

All in all, the book is quite useful in my opinion if you want to get a 
quick start implementing some kind of server or client using Twisted. Just 
don't expect that this book is all you'll need.

As for the online docs, the "finger" tutorial was very effective for me in 
demonstrating the power of Twisted: how you can get a lot of functionality 
in only a few lines of code. And it also shows that this power comes from 
modular design with good interfaces, not from having "skinnable" 
implementations that become useless as soon as you want to do something 
slightly different.

The explanation of deferreds is also decent in my opinion. It took me a 
while to really grasp it, but that's probably more of a lack of experience 
in asynchronous programming than a deficiency of the documentation.

The API docs are better than many other open source projects have them. 
However, because Twisted is a large collection of small modules and highly 
abstract in places, the API docs are only useful if you know what you are 
looking for.

As for reading the source code, for most projects that translates to "you're 
out of luck", but the Twisted source code is actually surprisingly easy to 
read. It has the same problem as the API docs though: if you don't know 
what you are looking for exactly, it's unlikely you'll find it.


Some documentation I would like to read:

- what is the point of the Zope interfaces? is it mainly for documentation 
purposes? I read some things about being able to automatically adapt from 
one interface to another, but where is that used in practice? the only 
thing I used it for so far is to attach information to an HTTP session 
object

- the design behind "cred", especially the authorization part: what exactly 
is an avatar, how do you implement one and how do you use one?

- the design behind taps: what is a tap exactly? why all the different 
types? does it require serialization or could I write one by hand? how 
should my program be written to be "tappable"?

- what is AMP and in what way is it different from PB, foolscap, xmlrpc?

If this already exists, please point me to it. Otherwise, if you know 
something about the subject and would like to write about it, I would 
really appreciate it.


If there is any documentation I can proof read or edit, please let me know. 
I've been using Twisted for a couple of years, but I have only seen very 
small parts of its API, so writing a document from scratch would take too 
much time, but I'm willing to take on smaller tasks.

Bye,
		Maarten
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 194 bytes
Desc: This is a digitally signed message part.
Url : http://twistedmatrix.com/pipermail/twisted-python/attachments/20080321/e027ac3d/attachment.pgp