The basics

What is a TAP?

A TAP is a pickle file that stores an instance of twisted.internet.app.Application. An Application is basically a set of Twisted servers. The reason we have these is for persistence -- when a Twisted process shuts down, it stores it's Application in a TAP named *-shutdown.tap. That way you can start up again without worrying about reconfiguring anything. This is the analogue of a configuration file for other applications, only we go a step further and store the server itself in the configuration file. ;-)

Creating TAP files

TAP files are generally created using the mktap script, which is located in the bin/ directory of your Twisted installation. There are a number of options for it, for creating various types of servers -- Reality, Telnet, Web, IRC -- you name it, we've either got it, or we're working on it.

Creating and working with a telnet server

Run mktap telnet -p 4040 -u admin -w woohoo at your shell prompt. If you list the contents of your current directory, you'll notice a new file -- telnet.tap. Congratulations! You just made your first TAP. After you do this, run 'twistd -f telnet.tap'. This command loads up your TAP file and starts the Twisted Application. Since the Application has a telnet server that you specified to be on port 4040, it will start listening for connections on this port. Try connecting with your favorite telnet utility to 127.0.0.1 port 4040.

$ telnet localhost 4040
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.

twisted.protocols.telnet.ShellFactory
Twisted 0.15.5
username: admin
password: ******
>>>

Now, you should see a Python prompt -- >>>. You can type any valid Python code here. Let's try looking around.

>>> dir()
['__builtins__']

Ok, not much. let's play a little more:

>>> import __main__
>>> dir(__main__)
['EverythingEphemeral', 'ServerOptions', '__builtins__', '__doc__', '__name__',
 'application', 'config', 'copyright', 'imp', 'initRun', 'load', 'log', 
'logFile', 'logPath', 'logfile', 'main', 'mainMod', 'oldstderr', 'oldstdin', 
'oldstdout', 'os', 'platformType', 'rotateLog', 'runtime', 'signal', 'string',
 'styles', 'sys', 'traceback', 'usage', 'util']

>>> __main__.application
<telnet app>
>>> dir(__main__.application)
['authorizer', 'connectors', 'delayeds', 'gid', 'name', 'persistenceVersion',
 'ports', 'resolver', 'running', 'services', 'uid', 'written']

From this session we learned that there is an application object stored in __main__ that's a telnet app, and it has some scary attributes that we're not going to worry about for now.

Alright, so now you've decided that you hate Twisted and want to shut it down. Or you just want to go to bed. Either way, I'll tell you what to do. First, disconnect from your telnet server. Then, back at your system's shell prompt, type kill `cat twistd.pid` (the quotes around cat twistd.pid are backticks, not single-quotes). If you list the contents of your current directory again, you'll notice that there will be a file named telnet-shutdown.tap. If you wanted to restart the server with exactly the same state as you left it, you could just run twistd -f telnet-shutdown.tap. This is why Twisted doesn't need any sort of configuration files -- all the configuration data is stored right in the objects!

Now that you've learned how to create a telnet server with 'mktap telnet', we'll delve a little deeper and learn how one is created behind the scenes. Start up a python interpreter and make sure that the 'twisted' directory is in your module search path.

Python 1.5.2 (#0, Dec 27 2000, 13:59:38)  [GCC 2.95.2 20000220 (Debian
GNU/Linux)] on linux2
Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
>>> import sys
>>> sys.path.append('/twisted/Twisted')

I installed Twisted in /twisted, so the place where my 'twisted' package directory is at is /twisted/Twisted/twisted (confusing, I know). For Python to find the 'twisted' package, it must have the directory *containing* the package in sys.path -- which is why I added /twisted/Twisted.

>>> from twisted.internet import app, tcp
>>> from twisted.protocols import telnet
>>> application = app.Application('telnet')
>>> ts = telnet.ShellFactory()
>>> application.listenTCP(4040, ts)

The above is basically what mktap telnet does. First we create a new Twisted Application, we create a new telnet Shell Factory, and we tell the application to listen on TCP port 4040 with the ShellFactory we've created.

Now let's start the application. This causes all ports on the application to start listening for incoming connections. This step is basically what the 'twistd' utility does.

>>> application.run()
twisted.protocols.telnet.ShellFactory starting on 4040

You now have a functioning telnet server! You can connect with your telnet program and work with it just the same as you did before. When you're done using the telnet server, you can switch back to your python console and hit ctrl-C. The following should appear:

Starting Shutdown Sequence.
Stopping main loop.
Main loop terminated.
Saving telnet application to telnet-shutdown.tap...
Saved.
>>>

Your server was pickled up again and saved to the telnet-shutdown.tap file, just like when you did kill `cat twistd.pid`.

Ok, now that we've scratched the surface with Twisted, you can go have fun and explore.


Chris Armstrong
Last modified: Tue Mar 12 22:04:10 EST 2002