1
1
<?xml version="1.0"?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml" lang="en"><head><title>Twisted Documentation: The Basics</title><link href="../howto/stylesheet.css" type="text/css" rel="stylesheet" /></head><body bgcolor="white"><h1 class="title">The Basics</h1><div class="toc"><ol><li><a href="#auto0">Application</a></li><li><a href="#auto1">Serialization</a></li><li><a href="#auto2">mktap and tapconvert</a></li><li><a href="#auto3">twistd</a></li><li><a href="#auto4">tap2deb</a></li><li><a href="#auto5">tap2rpm</a></li></ol></div><div class="content"><span></span><h2>Application<a name="auto0"></a></h2><p>Twisted programs usually work with
2
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml" lang="en"><head><title>Twisted Documentation: The Basics</title><link href="../howto/stylesheet.css" type="text/css" rel="stylesheet" /></head><body bgcolor="white"><h1 class="title">The Basics</h1><div class="toc"><ol><li><a href="#auto0">Application</a></li><li><a href="#auto1">twistd</a></li><li><a href="#auto2">tap2deb</a></li><li><a href="#auto3">tap2rpm</a></li></ol></div><div class="content"><span></span><h2>Application<a name="auto0"></a></h2><p>Twisted programs usually work with
3
3
<code class="API">twisted.application.service.Application</code>.
4
4
This class usually holds all persistent configuration of
5
5
a running server -- ports to bind to, places where connections
6
6
to must be kept or attempted, periodic actions to do and almost
7
7
everything else. It is the root object in a tree of services implementing
8
<code base="twisted.application.service" class="API">IService</code>.</p><p>Other HOWTOs describe how to write custom code for
9
Applications, but this one describes how to use already written
10
code (which can be part of Twisted or from a third-party Twisted
11
plugin developer). The Twisted distribution comes with an
12
assortment of tools to create and manipulate
13
<code>Application</code>s.</p><p><code>Application</code>s are just Python objects, which can
8
<code base="twisted.application.service" class="API">IService</code>.</p><p>Other HOWTOs describe how to write custom code for Applications,
9
but this one describes how to use already written code (which can be
10
part of Twisted or from a third-party Twisted plugin developer). The
11
Twisted distribution comes with an important tool to deal with
12
Applications, <code>twistd</code>.</p><p><code>Application</code>s are just Python objects, which can
14
13
be created and manipulated in the same ways as any other object.
15
In particular, they can be serialized to files. Twisted supports
16
several serialization formats.</p><h2>Serialization<a name="auto1"></a></h2><dl><dt>TAP</dt><dd>A Twisted Application Pickle. This format is supported by the
17
native Python pickle support. While not being human readable,
18
this format is the fastest to load and save.</dd><dt>TAX</dt><dd>Twisted contains
19
<code class="API">twisted.persisted.marmalade</code>, a module that
20
supports serializing and deserializing from a format which follows
21
the XML standard. This format is human readable and editable.</dd><dt>TAS</dt><dd>Twisted contains
22
<code class="API">twisted.persisted.aot</code>, a module that
23
supports serializing into Python source. This has the advantage
24
of using Python's own parser and being able to later manually
25
add Python code to the file.</dd></dl><h2>mktap and tapconvert<a name="auto2"></a></h2><p>The <code class="shell">mktap(1)</code> utility is the main way to create a TAP
26
(or TAX or TAS) file. It can be used to create an Application for all
27
of the major Twisted server types like web, ftp or IRC. It also
28
supports plugins, so when you install a Twisted plugin (that is,
29
unpack it into a directory on your <code>PYTHONPATH</code>) it will
30
automatically detect it and use any Twisted Application support in it.
31
It can create any of the above Application formats.</p><p>In order to see which server types are available, use
32
<code class="shell">mktap --help</code>. For a given server,
33
<code class="shell">mktap --help <name></code> shows the possible configuration
34
options. <code class="shell">mktap</code> supports a number of generic options
35
to configure the application -- for full details, read the man page.</p><p>One important option is <code class="shell">--append <filename></code>.
36
This is used when there is already a Twisted application serialized
37
to which a server should be added. For example, it can be used
38
to add a telnet server, which would let you probe and reconfigure
39
the application by telnetting into it.</p><p>Another useful utility is <code class="shell">tapconvert(1)</code>, which converts
40
between all three Application formats.</p><h2>twistd<a name="auto3"></a></h2><a name="twistd"></a><p>Having an <code>Application</code> in a variety of formats, aesthetically
41
pleasing as it may be, does not actually cause anything to happen.
42
For that, we need a program which takes a <q>dead</q> Application and brings
43
life to it. For UNIX systems (and, until there are are alternatives,
44
for other operating systems too), this program is <code class="shell">twistd(1)</code>.
45
Strictly speaking, <code class="shell">twistd</code> is not necessary -- unserializing
46
the application, getting the <code>IService</code> component, calling
47
<code>startService</code>, scheduling <code>stopService</code> when
14
</p><h2>twistd<a name="auto1"></a></h2><a name="twistd"></a><p>The Twisted Daemon is a program that knows how to run Applications.
16
is <code class="shell">twistd(1)</code>. Strictly
17
speaking, <code class="shell">twistd</code> is not necessary --
18
fetching the application, getting the <code>IService</code> component,
19
calling <code>startService</code>, scheduling <code>stopService</code> when
48
20
the reactor shuts down, and then calling <code>reactor.run()</code> could be
49
done manually. <code class="shell">twistd(1)</code>, however, supplies many options
50
which are highly useful for program set up.</p><p><code class="shell">twistd</code> supports choosing a reactor (for more on
21
done manually. <code class="shell">twistd(1)</code>, however, supplies
22
many options which are highly useful for program set up.</p><p><code class="shell">twistd</code> supports choosing a reactor (for more on
51
23
reactors, see <a href="choosing-reactor.html">Choosing a Reactor</a>), logging
52
24
to a logfile, daemonizing and more. <code class="shell">twistd</code> supports all
53
25
Applications mentioned above -- and an additional one. Sometimes
54
is is convenient to write the code for building a class in straight
26
it is convenient to write the code for building a class in straight
55
27
Python. One big source of such Python files is the <code>doc/examples</code>
56
28
directory. When a straight Python file which defines an <code>Application</code>
57
29
object called <code>application</code> is used, use the <code class="shell">-y</code>
58
30
option.</p><p>When <code class="shell">twistd</code> runs, it records its process id in a
59
31
<code>twistd.pid</code> file (this can be configured via a command line
60
32
switch). In order to shutdown the <code class="shell">twistd</code> process, kill that
61
pid (usually you would do <code class="shell">kill `cat twisted.pid`</code>). When the
62
process is killed in an orderly fashion it will leave behind the <q>shutdown
63
Application</q> which is named the same as the original file with a
64
<code>-shutdown</code> added to its base name. This contains the new
65
configuration information, as changed in the application. For example,
66
<code>web.tap</code> when shutdown will have an additional file,
67
<code>web-shutdown.tap</code>.</p><p>As always, the gory details are in the manual page.</p><h2>tap2deb<a name="auto4"></a></h2><p>
33
pid (usually you would do <code class="shell">kill `cat twistd.pid`</code>).
34
</p><p>As always, the gory details are in the manual page.</p><h2>tap2deb<a name="auto2"></a></h2><p>
68
35
For Twisted-based server application developers who want to deploy on
69
36
Debian, Twisted supplies the <code class="shell">tap2deb</code> program. This program
70
37
wraps a Twisted Application file (of any of the supported formats -- Python,
added
removed
doc/howto/basics.html
