Sophie

Sophie

distrib > Mandriva > 2008.1 > x86_64 > media > main-release > by-pkgid > db93d7191b12a3d5ce887da46fc79bf1 > files > 95

python-twisted-core-doc-2.5.0-3mdv2008.1.x86_64.rpm

<?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" lang="en"><head><title>Twisted Documentation: Using the Twisted Application Framework</title><link href="../howto/stylesheet.css" type="text/css" rel="stylesheet" /></head><body bgcolor="white"><h1 class="title">Using the Twisted Application Framework</h1><div class="toc"><ol><li><a href="#auto0">Introduction</a></li><ul><li><a href="#auto1">Audience</a></li><li><a href="#auto2">Goals</a></li></ul><li><a href="#auto3">Overview</a></li><li><a href="#auto4">Using application</a></li><ul><li><a href="#auto5">twistd and tac</a></li><li><a href="#auto6">Services provided by Twisted</a></li><li><a href="#auto7">Service Collection</a></li></ul></ol></div><div class="content"><span></span><h2>Introduction<a name="auto0"></a></h2><h3>Audience<a name="auto1"></a></h3>

The target audience of this document is a Twisted user who wants to deploy a
significant amount of Twisted code in a re-usable, standard and easily
configurable fashion.  A Twisted user who wishes to use the Application
framework needs to be familiar with developing Twisted <a href="servers.html">servers</a> and/or <a href="clients.html">clients</a>.

<h3>Goals<a name="auto2"></a></h3><ul><li>To introduce the Twisted Application infrastructure.</li><li>To explain how to deploy your Twisted application using <code>.tac</code>
  files and <code>twistd</code></li><li>To outline the existing Twisted services.</li></ul><h2>Overview<a name="auto3"></a></h2><p>The Twisted Application infrastructure takes care of running and stopping
your application.  Using this infrastructure frees you from from having to
write a large amount of boilerplate code by hooking your application into
existing tools that manage daemonization, logging, <a href="choosing-reactor.html">choosing a reactor</a> and more.</p><p>The major tool that manages Twisted applications is a command-line utility
called <code>twistd</code>.  <code>twistd</code> is cross platform, and is the
recommended tool for running Twisted applications.  </p><p>The core component of the Twisted Application infrastructure is the <code class="API">twisted.application.service.Application</code> object &mdash; an
object which represents your application.  However, Application doesn't provide
anything that you'd want to manipulate directly.  Instead, Application acts as
a container of any <q>Services</q> (objects implementing <code base="twisted.application.service" class="API">IService</code>) that your application
provides.  Most of your interaction with the Application infrastructure will be
done through Services.</p><p>By <q>Service</q>, we mean anything in your application that can be started
and stopped.  Typical services include web servers, FTP servers and SSH
clients.  Your Application object can contain many services, and can even
contain structured heirarchies of Services using <code base="twisted.application.service" class="API">IServiceCollection</code>s.</p><p>Here's a simple example of constructing an Application object which
represents an echo server that runs on TCP port 7001.</p><pre class="python">
<span class="py-src-keyword">from</span> <span class="py-src-variable">twisted</span>.<span class="py-src-variable">application</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">internet</span>, <span class="py-src-variable">service</span>
<span class="py-src-keyword">from</span> <span class="py-src-variable">somemodule</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">EchoFactory</span>

<span class="py-src-variable">port</span> = <span class="py-src-number">7001</span>
<span class="py-src-variable">factory</span> = <span class="py-src-variable">EchoFactory</span>()

<span class="py-src-comment"># this is the important bit
</span><span class="py-src-variable">application</span> = <span class="py-src-variable">service</span>.<span class="py-src-variable">Application</span>(<span class="py-src-string">&quot;echo&quot;</span>)  <span class="py-src-comment"># create the Application</span>
<span class="py-src-variable">echoService</span> = <span class="py-src-variable">internet</span>.<span class="py-src-variable">TCPServer</span>(<span class="py-src-variable">port</span>, <span class="py-src-variable">factory</span>) <span class="py-src-comment"># create the service</span>
<span class="py-src-comment"># add the service to the application
</span><span class="py-src-variable">echoService</span>.<span class="py-src-variable">setServiceParent</span>(<span class="py-src-variable">application</span>)
</pre><p>See <a href="servers.html">Writing Servers</a> for an explanation of
EchoFactory.</p><p>This example creates a simple heirarchy:
<pre>
   application
   |
   `- echoService
</pre> More complicated heirarchies of services can be created using
IServiceCollection.  You will most likely want to do this to manage Services
which are dependent on other Services.  For example, a proxying Twisted
application might want its server Service to only start up after the associated
Client service. </p><h2>Using application<a name="auto4"></a></h2><h3>twistd and tac<a name="auto5"></a></h3><a name="twistd"></a><p>To handle start-up and configuration of your Twisted application, the
Twisted Application infrastructure uses <code>.tac</code> files.
<code>.tac</code> are Python files which configure an <code base="twisted.application.service" class="API">Application</code> object and assign this
object to the top-level variable <q><code>application</code></q>.</p><p>The following is a simple example of a <code>.tac</code> file:</p><div class="py-listing"><pre>
<span class="py-src-string">&quot;&quot;&quot;
This is an example .tac file which starts a webserver on port 8080 and
serves files from the current working directory.

The important part of this, the part that makes it a .tac file, is
the final root-level section, which sets up the object called 'application'
which twistd will look for
&quot;&quot;&quot;</span>

<span class="py-src-keyword">import</span> <span class="py-src-variable">os</span>
<span class="py-src-keyword">from</span> <span class="py-src-variable">twisted</span>.<span class="py-src-variable">application</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">service</span>, <span class="py-src-variable">internet</span>
<span class="py-src-keyword">from</span> <span class="py-src-variable">twisted</span>.<span class="py-src-variable">web</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">static</span>, <span class="py-src-variable">server</span>

<span class="py-src-keyword">def</span> <span class="py-src-identifier">getWebService</span>():
    <span class="py-src-string">&quot;&quot;&quot;
    Return a service suitable for creating an application object.

    This service is a simple web server that serves files on port 8080 from
    underneath the current working directory.
    &quot;&quot;&quot;</span>
    <span class="py-src-comment"># create a resource to serve static files
</span>    <span class="py-src-variable">fileServer</span> = <span class="py-src-variable">server</span>.<span class="py-src-variable">Site</span>(<span class="py-src-variable">static</span>.<span class="py-src-variable">File</span>(<span class="py-src-variable">os</span>.<span class="py-src-variable">getcwd</span>()))
    <span class="py-src-keyword">return</span> <span class="py-src-variable">internet</span>.<span class="py-src-variable">TCPServer</span>(<span class="py-src-number">8080</span>, <span class="py-src-variable">fileServer</span>)

<span class="py-src-comment"># this is the core part of any tac file, the creation of the root-level
</span><span class="py-src-comment"># application object
</span><span class="py-src-variable">application</span> = <span class="py-src-variable">service</span>.<span class="py-src-variable">Application</span>(<span class="py-src-string">&quot;Demo application&quot;</span>)

<span class="py-src-comment"># attach the service to its parent application
</span><span class="py-src-variable">service</span> = <span class="py-src-variable">getWebService</span>()
<span class="py-src-variable">service</span>.<span class="py-src-variable">setServiceParent</span>(<span class="py-src-variable">application</span>)
</pre><div class="caption">Source listing - <a href="listings/application/service.tac"><span class="filename">listings/application/service.tac</span></a></div></div><p><code>twistd</code> is a program that runs Twisted applications using a
<code>.tac</code> file. In its most simple form, it takes a single argument
<code>-y</code> and a tac file name. For example, you can run the above server
with the command <code class="shell">twistd -y service.tac</code>.</p><p>By default, <code>twistd</code> daemonizes and logs to a file called
<code>twistd.log</code>. More usually, when debugging, you will want your
application to run in the foreground and log to the command line. To run the
above file like this, use the command <code class="shell">twistd -noy
service.tac</code></p><p>For more information, see the <code>twistd</code> man page.</p><h3>Services provided by Twisted<a name="auto6"></a></h3><p>Twisted provides several services that you want to know about.</p><p>Each of these services (except TimerService) has a corresponding
<q>connect</q> or <q>listen</q> method on the reactor, and the constructors for
the services take the same arguments as the reactor methods.  The
<q>connect</q> methods are for clients and the <q>listen</q> methods are for
servers.  For example, TCPServer corresponds to reactor.listenTCP and TCPClient
corresponds to reactor.connectTCP.  </p><dl><dt><code base="twisted.application.internet" class="API">TCPServer</code></dt><dt><code base="twisted.application.internet" class="API">TCPClient</code></dt><dd>
    Services which allow you to make connections and listen for connections
    on TCP ports.
    <ul><li><code base="twisted.internet.interfaces.IReactorTCP" class="API">listenTCP</code></li><li><code base="twisted.internet.interfaces.IReactorTCP" class="API">connectTCP</code></li></ul></dd><dt><code base="twisted.application.internet" class="API">UNIXServer</code></dt><dt><code base="twisted.application.internet" class="API">UNIXClient</code></dt><dd>
    Services which listen and make connections over UNIX sockets.
    <ul><li><code base="twisted.internet.interfaces.IReactorUNIX" class="API">listenUNIX</code></li><li><code base="twisted.internet.interfaces.IReactorUNIX" class="API">connectUNIX</code></li></ul></dd><dt><code base="twisted.application.internet" class="API">SSLServer</code></dt><dt><code base="twisted.application.internet" class="API">SSLClient</code></dt><dd>Services which allow you to make SSL connections and run SSL servers.
    <ul><li><code base="twisted.internet.interfaces.IReactorSSL" class="API">listenSSL</code></li><li><code base="twisted.internet.interfaces.IReactorSSL" class="API">connectSSL</code></li></ul></dd><dt><code base="twisted.application.internet" class="API">UDPServer</code></dt><dt><code base="twisted.application.internet" class="API">UDPClient</code></dt><dd>Services which allow you to send and receive data over UDP
    <ul><li><code base="twisted.internet.interfaces.IReactorUDP" class="API">listenUDP</code></li><li><code base="twisted.internet.interfaces.IReactorUDP" class="API">connectUDP</code></li></ul><p>See also the <a href="udp.html">UDP documentation</a>.</p></dd><dt><code base="twisted.application.internet" class="API">UNIXDatagramServer</code></dt><dt><code base="twisted.application.internet" class="API">UNIXDatagramClient</code></dt><dd>Services which send and receive data over UNIX datagram sockets.
    <ul><li><code base="twisted.internet.interfaces.IReactorUDP" class="API">listenUNIXDatagram</code></li><li><code base="twisted.internet.interfaces.IReactorUDP" class="API">connectUNIXDatagram</code></li></ul></dd><dt><code base="twisted.application.internet" class="API">MulticastServer</code></dt><dd>
    A server for UDP socket methods that support multicast.
    <ul><li><code base="twisted.internet.interfaces.IReactorUDP" class="API">listenMulticast</code></li></ul></dd><dt><code base="twisted.application.internet" class="API">TimerService</code></dt><dd>
    A service to periodically call a function.
  </dd></dl><h3>Service Collection<a name="auto7"></a></h3><p><code base="twisted.application.service" class="API">IServiceCollection</code> objects contain
<code base="twisted.application.service" class="API">IService</code> objects.
IService objects can be added to IServiceCollection by calling <code base="twisted.application.service.IService" class="API">setServiceParent</code> and detached
by using <code base="twisted.application.service.IService" class="API">disownServiceParent</code>.</p><p>The standard implementation of IServiceCollection is <code base="twisted.application.service" class="API">MultiService</code>, which also implements
IService.  MultiService is useful for creating a new Service which combines two
or more existing Services.  For example, you could create a DNS Service as a
MultiService which has a TCP and a UDP Service as children.</p><pre class="python">
<span class="py-src-keyword">from</span> <span class="py-src-variable">twisted</span>.<span class="py-src-variable">application</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">internet</span>, <span class="py-src-variable">service</span>
<span class="py-src-keyword">from</span> <span class="py-src-variable">twisted</span>.<span class="py-src-variable">names</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">server</span>, <span class="py-src-variable">dns</span>, <span class="py-src-variable">hosts</span>

<span class="py-src-variable">port</span> = <span class="py-src-number">53</span>

<span class="py-src-comment"># Create a MultiService, and hook up a TCPServer and a UDPServer to it as
</span><span class="py-src-comment"># children.
</span><span class="py-src-variable">dnsService</span> = <span class="py-src-variable">service</span>.<span class="py-src-variable">MultiService</span>()
<span class="py-src-variable">hostsResolver</span> = <span class="py-src-variable">hosts</span>.<span class="py-src-variable">Resolver</span>(<span class="py-src-string">'/etc/hosts'</span>)
<span class="py-src-variable">tcpFactory</span> = <span class="py-src-variable">server</span>.<span class="py-src-variable">DNSServerFactory</span>([<span class="py-src-variable">hostsResolver</span>])
<span class="py-src-variable">internet</span>.<span class="py-src-variable">TCPServer</span>(<span class="py-src-variable">port</span>, <span class="py-src-variable">tcpFactory</span>).<span class="py-src-variable">setServiceParent</span>(<span class="py-src-variable">dnsService</span>)
<span class="py-src-variable">udpFactory</span> = <span class="py-src-variable">dns</span>.<span class="py-src-variable">DNSDatagramProtocol</span>(<span class="py-src-variable">tcpFactory</span>)
<span class="py-src-variable">internet</span>.<span class="py-src-variable">UDPServer</span>(<span class="py-src-variable">port</span>, <span class="py-src-variable">udpFactory</span>).<span class="py-src-variable">setServiceParent</span>(<span class="py-src-variable">dnsService</span>)

<span class="py-src-comment"># Create an application as normal
</span><span class="py-src-variable">application</span> = <span class="py-src-variable">service</span>.<span class="py-src-variable">Application</span>(<span class="py-src-string">&quot;DNSExample&quot;</span>)

<span class="py-src-comment"># Connect our MultiService to the application, just like a normal service.
</span><span class="py-src-variable">dnsService</span>.<span class="py-src-variable">setServiceParent</span>(<span class="py-src-variable">application</span>)
</pre></div><p><a href="../howto/index.html">Index</a></p><span class="version">Version: 2.5.0</span></body></html>

Perl :: Catalyst :: PostgreSQL :: RPM Valid HTML 4.01 Transitional