Twisted programs usually work with
twisted.application.service.Application.
This class usually holds all persistent configuration of
a running server -- ports to bind to, places where connections
to must be kept or attempted, periodic actions to do and almost
everything else. It is the root object in a tree of services implementing
IService.
Other HOWTOs describe how to write custom code for
Applications, but this one describes how to use already written
code (which can be part of Twisted or from a third-party Twisted
plugin developer). The Twisted distribution comes with an
assortment of tools to create and manipulate
Applications.
Applications are just Python objects, which can
be created and manipulated in the same ways as any other object.
In particular, they can be serialized to files. Twisted supports
several serialization formats.
twisted.persisted.marmalade, a module that
supports serializing and deserializing from a format which follows
the XML standard. This format is human readable and editable.twisted.persisted.aot, a module that
supports serializing into Python source. This has the advantage
of using Python's own parser and being able to later manually
add Python code to the file.The mktap(1) utility is the main way to create a TAP
(or TAX or TAS) file. It can be used to create an Application for all
of the major Twisted server types like web, ftp or IRC. It also
supports plugins, so when you install a Twisted plugin (that is,
unpack it into a directory on your PYTHONPATH) it will
automatically detect it and use any Twisted Application support in it.
It can create any of the above Application formats.
In order to see which server types are available, use
mktap --help. For a given server,
mktap --help <name> shows the possible configuration
options. mktap supports a number of generic options
to configure the application -- for full details, read the man page.
One important option is --append <filename>.
This is used when there is already a Twisted application serialized
to which a server should be added. For example, it can be used
to add a telnet server, which would let you probe and reconfigure
the application by telnetting into it.
Another useful utility is tapconvert(1), which converts
between all three Application formats.
Having an Application in a variety of formats, aesthetically
pleasing as it may be, does not actually cause anything to happen.
For that, we need a program which takes a dead
Application and brings
life to it. For UNIX systems (and, until there are are alternatives,
for other operating systems too), this program is twistd(1).
Strictly speaking, twistd is not necessary -- unserializing
the application, getting the IService component, calling
startService, scheduling stopService when
the reactor shuts down, and then calling reactor.run() could be
done manually. twistd(1), however, supplies many options
which are highly useful for program set up.
twistd supports choosing a reactor (for more on
reactors, see Choosing a Reactor), logging
to a logfile, daemonizing and more. twistd supports all
Applications mentioned above -- and an additional one. Sometimes
is is convenient to write the code for building a class in straight
Python. One big source of such Python files is the doc/examples
directory. When a straight Python file which defines an Application
object called application is used, use the -y
option.
When twistd runs, it records its process id in a
twistd.pid file (this can be configured via a command line
switch). In order to shutdown the twistd process, kill that
pid (usually you would do kill `cat twisted.pid`). When the
process is killed in an orderly fashion it will leave behind the shutdown
Application
which is named the same as the original file with a
-shutdown added to its base name. This contains the new
configuration information, as changed in the application. For example,
web.tap when shutdown will have an additional file,
web-shutdown.tap.
As always, the gory details are in the manual page.
For Twisted-based server application developers who want to deploy on
Debian, Twisted supplies the tap2deb program. This program
wraps a Twisted Application file (of any of the supported formats -- Python,
source, xml or pickle)
in a Debian package, including correct installation and removal scripts
and init.d scripts. This frees the installer from manually
stopping or starting the service, and will make sure it goes properly up
on startup and down on shutdown and that it obeys the init levels.
For the more savvy Debian users, the
tap2deb also generates the source package, allowing her
to modify and polish things which automated software cannot detect
(such as dependencies or relationships to virtual packages). In addition,
the Twisted team itself intends to produce Debian packages for some common
services, such as web servers and an inetd replacement. Those packages
will enjoy the best of all worlds -- both the consistency which comes
from being based on the tap2deb and the delicate manual
tweaking of a Debian maintainer, insuring perfect integration with
Debian.
Right now, there is a beta Debian archive of a web server available at Moshe's archive.
tap2rpm is similar to tap2deb, except that
it generates RPMs for Redhat and other related platforms.