doc/core/howto/basics.html

   1 <?xml version="1.0" encoding="utf-8"?><!DOCTYPE html  PUBLIC '-//W3C//DTD XHTML 1.0 Transitional//EN'  'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'><html lang="en" xmlns="http://www.w3.org/1999/xhtml">
   2   <head>
   3 <title>Twisted Documentation: The Basics</title>
   4 <link href="stylesheet.css" rel="stylesheet" type="text/css"/>
   5   </head>
   6
   7   <body bgcolor="white">
   8     <h1 class="title">The Basics</h1>
   9     <div class="toc"><ol><li><a href="#auto0">Application</a></li><li><a href="#auto1">twistd</a></li><li><a href="#auto2">OS Integration</a></li></ol></div>
  10     <div class="content">
  11 <span/>
  12
  13 <h2>Application<a name="auto0"/></h2>
  14
  15 <p>Twisted programs usually work
  16 with <code class="API"><a href="http://twistedmatrix.com/documents/12.1.0/api/twisted.application.service.Application.html" title="twisted.application.service.Application">twisted.application.service.Application</a></code>.
  17 This class usually holds all persistent configuration of a running
  18 server -- ports to bind to, places where connections to must be kept
  19 or attempted, periodic actions to do and almost everything else. It is
  20 the root object in a tree of services implementing <code class="API"><a href="http://twistedmatrix.com/documents/12.1.0/api/twisted.application.service.IService.html" title="twisted.application.service.IService">IService</a></code>.</p>
  21
  22 <p>Other HOWTOs describe how to write custom code for Applications,
  23 but this one describes how to use already written code (which can be
  24 part of Twisted or from a third-party Twisted plugin developer).  The
  25 Twisted distribution comes with an important tool to deal with
  26 Applications, <code>twistd</code>.</p>
  27
  28 <p><code>Application</code>s are just Python objects, which can
  29 be created and manipulated in the same ways as any other object.
  30 </p>
  31
  32 <h2>twistd<a name="auto1"/></h2><a name="twistd" shape="rect"/>
  33
  34 <p>The Twisted Daemon is a program that knows how to run Applications.
  35 This program
  36 is <code class="shell">twistd(1)</code>.  Strictly
  37 speaking, <code class="shell">twistd</code> is not necessary --
  38 fetching the application, getting the <code>IService</code> component,
  39 calling <code>startService</code>, scheduling <code>stopService</code> when
  40 the reactor shuts down, and then calling <code>reactor.run()</code> could be
  41 done manually. <code class="shell">twistd(1)</code>, however, supplies
  42 many options which are highly useful for program set up.</p>
  43
  44 <p><code class="shell">twistd</code> supports choosing a reactor (for more on
  45 reactors, see <a href="choosing-reactor.html" shape="rect">Choosing a Reactor</a>), logging
  46 to a logfile, daemonizing and more. <code class="shell">twistd</code> supports all
  47 Applications mentioned above -- and an additional one. Sometimes
  48 it is convenient to write the code for building a class in straight
  49 Python. One big source of such Python files is the <code>doc/examples</code>
  50 directory. When a straight Python file which defines an <code>Application</code>
  51 object called <code>application</code> is used, use the <code class="shell">-y</code>
  52 option.</p>
  53
  54 <p>When <code class="shell">twistd</code> runs, it records its process
  55 id in a <code>twistd.pid</code> file (this can be configured via a
  56 command line switch). In order to shutdown
  57 the <code class="shell">twistd</code> process, kill that pid (usually
  58 you would do <code class="shell">kill `cat twistd.pid`</code>).
  59 </p>
  60
  61 <p>As always, the gory details are in the manual page.</p>
  62
  63 <h2>OS Integration<a name="auto2"/></h2>
  64
  65 <p>
  66 If you have an Application that runs
  67 with <code class="shell">twistd</code>, you can easily deploy it on
  68 RedHat Linux or Debian GNU/Linux based systems using
  69 the <code class="shell">tap2deb</code>
  70 or <code class="shell">tap2rpm</code> tools. These take a Twisted
  71 Application file (of any of the supported formats — Python source, XML
  72 or pickle), and build a Debian or RPM package (respectively) that
  73 installs the Application as a system service. The package includes the
  74 Application file, a default <code>/etc/init.d/</code> script that
  75 starts and stops the process with twistd, and post-installation
  76 scripts that configure the Application to be run in the appropriate
  77 init levels.
  78 </p>
  79
  80
  81 <div class="note"><strong>Note: </strong> <code class="shell">tap2rpm</code>
  82 and <code class="shell">tap2deb</code> do not package your entire
  83 application and dependent code, just the Twisted Application file. You
  84 will need to find some other way to package your Python code, such
  85 as <a href="http://docs.python.org/library/distutils.html" shape="rect">distutils</a>'
  86 <code>bdist_rpm</code> command.
  87 </div>
  88
  89 <p>
  90 For more savvy users, these tools also generate the source package, allowing
  91 you to modify and polish things which automated software cannot detect (such as
  92 dependencies or relationships to virtual packages).
  93 </p>
  94
  95 </div>
  96
  97     <p><a href="index.html">Index</a></p>
  98     <span class="version">Version: 12.1.0</span>
  99   </body>
 100 </html>