<?xml version="1.0"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>The Basics</title> </head> <body> <h1>The Basics</h1> <h2>Application</h2> <p>Twisted programs usually work with <code class="API">twisted.application.service.Application</code>. 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 <code class="API" base="twisted.application.service">IService</code>.</p> <p>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 <code>Application</code>s.</p> <p><code>Application</code>s 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.</p> <h2>Serialization</h2> <dl> <dt>TAP</dt> <dd>A Twisted Application Pickle. This format is supported by the native Python pickle support. While not being human readable, this format is the fastest to load and save.</dd> <dt>TAX</dt> <dd>Twisted contains <code class="API">twisted.persisted.marmalade</code>, a module that supports serializing and deserializing from a format which follows the XML standard. This format is human readable and editable.</dd> <dt>TAS</dt> <dd>Twisted contains <code class="API">twisted.persisted.aot</code>, 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.</dd> </dl> <h2>mktap and tapconvert</h2> <p>The <code class="shell">mktap(1)</code> 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 <code>PYTHONPATH</code>) it will automatically detect it and use any Twisted Application support in it. It can create any of the above Application formats.</p> <p>In order to see which server types are available, use <code class="shell">mktap --help</code>. For a given server, <code class="shell">mktap --help <name></code> shows the possible configuration options. <code class="shell">mktap</code> supports a number of generic options to configure the application -- for full details, read the man page.</p> <p>One important option is <code class="shell">--append <filename></code>. 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.</p> <p>Another useful utility is <code class="shell">tapconvert(1)</code>, which converts between all three Application formats.</p> <h2>twistd</h2> <p>Having an <code>Application</code> 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 <q>dead</q> Application and brings life to it. For UNIX systems (and, until there are are alternatives, for other operating systems too), this program is <code class="shell">twistd(1)</code>. Strictly speaking, <code class="shell">twistd</code> is not necessary -- unserializing the application, getting the <code>IService</code> component, calling <code>startService</code>, scheduling <code>stopService</code> when the reactor shuts down, and then calling <code>reactor.run()</code> could be done manually. <code class="shell">twistd(1)</code>, however, supplies many options which are highly useful for program set up.</p> <p><code class="shell">twistd</code> supports choosing a reactor (for more on reactors, see <a href="choosing-reactor.xhtml">Choosing a Reactor</a>), logging to a logfile, daemonizing and more. <code class="shell">twistd</code> 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 <code>doc/examples</code> directory. When a straight Python file which defines an <code>Application</code> object called <code>application</code> is used, use the <code class="shell">-y</code> option.</p> <p>When <code class="shell">twistd</code> runs, it records its process id in a <code>twistd.pid</code> file (this can be configured via a command line switch). In order to shutdown the <code class="shell">twistd</code> process, kill that pid (usually you would do <code class="shell">kill `cat twisted.pid`</code>). When the process is killed in an orderly fashion it will leave behind the <q>shutdown Application</q> which is named the same as the original file with a <code>-shutdown</code> added to its base name. This contains the new configuration information, as changed in the application. For example, <code>web.tap</code> when shutdown will have an additional file, <code>web-shutdown.tap</code>.</p> <p>As always, the gory details are in the manual page.</p> <h2>tap2deb</h2> <p> For Twisted-based server application developers who want to deploy on Debian, Twisted supplies the <code class="shell">tap2deb</code> 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 <code>init.d</code> 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. </p> <p> For the more savvy Debian users, the <code class="shell">tap2deb</code> 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 <code class="shell">tap2deb</code> and the delicate manual tweaking of a Debian maintainer, insuring perfect integration with Debian. </p> <p> Right now, there is a beta Debian archive of a web server available at <a href="http://twistedmatrix.com/users/moshez/apt">Moshe's archive</a>. </p> <h2>tap2rpm</h2> <p><code class="shell">tap2rpm</code> is similar to <code class="shell">tap2deb</code>, except that it generates RPMs for Redhat and other related platforms.</p> </body></html>