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. ;-)
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.
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.