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.