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.

Acroread on Unix

Adobe's acroread is another non-GPL piece of software that I find useful for software development, since many specifications are now distributed in pdf format. Unfortunately, too many spec sheets are still tied to the proprietary Microsoft Word format, for which the only remedy is OpenOffice.org or some of the various lightweight MS-Word readers.

Acroread is a bit heavyweight for most viewing tasks, which is why xpdf is still my default pdf viewer. But for certain kinds of documentation, such as 700+ page HIPAA implementation guides, having acroread is indispensible with it's window tiles to aid navigation.

Having acroread installed is useful for software development with *
ReportLab. It's handy to view the output of generated pdf files with two different renderers, though I also check the results on Windows as well.

Acroread on Unix is much improved. For a while it appeared that the Linux/Solaris versions were languishing behind the Windows versions. Unix acroread has one feature not available on the Windows version. It can emit the Postscript to a file or stdout - useful for batch print jobs.

Something new I just learned: Compressed pdf files can be viewed with the zxpdf command.

remote backups with Strongspace.com

I've been wanting to use an off-site backup process that was simple to administer, yet easy for non-techies to use. Strongspace.com appears to fit the bill. You basically sign up for a particular plan that gives you a specific amount of disk space and a number of users. There's no signup fee and you can discontinue the service at any time.

Strongspace works with sftp/scp and rsync+ssh. For windows users, it can be accessed via WinScp or Filezilla. But for making convenient backups from Windows machines nothing beats an rsync batch file linked to a desktop icon. Even better, would be to schedule automatic backups. The advantage with rsync is that after the initial backup, updates are generally very quick.

The disadvantage with rsync is that it's not an easy program for Windows users to install. Fortunately, David Barrett has written an excellent How-To.

A typical rsync batch file entry will look like this:

rsync -avz "/Documents and Settings/user/My Documents" myaccount@mydomain.strongspace.com:Documents

Backups are only half the story, however. Eventually, there will come a day when the user needs to retrieve lost data. This is where having a browseable backup site is handy. For the user, retrieving a lost document is as simple as accessing her account on Strongspace.com. No intervention from me is necessary. Furthermore, the data can be retrieved from any other location, e.g. modifying a contract or spreadsheet while off-site. It would certainly be possible to configure something like this internally, but it would be a hassle to maintain with limited advantages.