Serpent Addiction

Saturday, December 10, 2005

Twisted online API documentation is hopeless

There's an outstanding book on Twisted by Abe Fettig. I've been meaning to get down into the details of Twisted rather than devote all my time with Nevow. The examples are clear and well-written, e.g.:

from twisted.internet import reactor
import time

def printTime():
print "current time is", time.strftime("%H:%M:%S")

def stopReactor():
print "stopping reactor"
reactor.stop()

if __name__ == '__main__':
reactor.callLater(1, printTime)
reactor.callLater(2, printTime)
reactor.callLater(3, printTime)
reactor.callLater(4, printTime)
reactor.callLater(5, stopReactor)
print "running the reactor ..."
reactor.run()
print "reactor stopped"

However, I next go to the twisted website to review the reference API. Guess what? There's no entry tor twisted.internet.reactor. Reading the source reveals that selectreactor is the default implementation of reactor. It's pretty obvious that the parameter to the callLater method are time (in seconds) and and argument-less function, but I'd like to review that in the API documentation.

The twisted.internet.selectreactor section lists no callLater method. Grepping through the source reveals that it's implemented in four places, but the one I'm probably using is twisted.internet.base. There's a reference in the docstring: "See twisted.internet.interfaces.IReactorTime.callLater."

Okay, I can live with this, but it means the online API is a waste of time. I'll simply have to read through the source code to learn anything useful about twisted. The online API actually slows down the discovery process.

Update: Here's a line of Nevow code:
request = inevow.IRequest(ctx)

Want know to what IRequest returns? Check out the API docs.

1 Comments:

  • I realize I'm a bit late to the game here, but I ran across this article in a web search for some Twisted documentation examples, and I think you've identified an important and long-standing weakness in our documentation.

    The situation has improved quite a bit since you made this observation. This is what the entry for twisted.internet.reactor looks like today, in July 2010. Is this clear enough? If you had seen today's documentation when you wrote this post, would you have felt the same way? If not, please feel free to file a doc bug.

    It's hard to get a static API documentation generator to understand a somewhat dynamic API like the reactor (or super dynamic APIs like adaptation, which is what IRequest(ctx) does), but it's worth trying, since this is such a core API.

    By Blogger glyph, at 7:49 PM  

Post a Comment

<< Home