doc/web/howto/web-development.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: Web Application Development</title>
   4 <link href="stylesheet.css" rel="stylesheet" type="text/css"/>
   5   </head>
   6
   7   <body bgcolor="white">
   8     <h1 class="title">Web Application Development</h1>
   9     <div class="toc"><ol><li><a href="#auto0">Code layout</a></li><li><a href="#auto1">Web application deployment</a></li><li><a href="#auto2">Understanding resource scripts (.rpy files)</a></li></ol></div>
  10     <div class="content">
  11 <span/>
  12
  13 <h2>Code layout<a name="auto0"/></h2>
  14
  15 <p>The development of a Twisted Web application should be orthogonal to its
  16 deployment.  This means is that if you are developing a web application, it
  17 should be a resource with children, and internal links.  Some of the children
  18 might use <a href="http://www.divmod.org/projects/nevow" shape="rect">Nevow</a>, some
  19 might be resources manually using <code>.write</code>, and so on.  Regardless,
  20 the code should be in a Python module, or package, <em>outside</em> the web
  21 tree.</p>
  22
  23 <p>You will probably want to test your application as you develop it.  There are
  24 many ways to test, including dropping an <code>.rpy</code> which looks
  25 like:</p>
  26
  27 <pre class="python"><p class="py-linenumber">1
  28 2
  29 </p><span class="py-src-keyword">from</span> <span class="py-src-variable">mypackage</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">toplevel</span>
  30 <span class="py-src-variable">resource</span> = <span class="py-src-variable">toplevel</span>.<span class="py-src-variable">Resource</span>(<span class="py-src-variable">file</span>=<span class="py-src-string">&quot;foo/bar&quot;</span>, <span class="py-src-variable">color</span>=<span class="py-src-string">&quot;blue&quot;</span>)
  31 </pre>
  32
  33 <p>into a directory, and then running:</p>
  34
  35 <pre class="shell" xml:space="preserve">
  36 % twistd web --path=/directory
  37 </pre>
  38
  39 <p>You can also write a Python script like:</p>
  40
  41 <pre class="python"><p class="py-linenumber">1
  42 2
  43 3
  44 4
  45 5
  46 6
  47 7
  48 8
  49 9
  50 </p><span class="py-src-comment">#!/usr/bin/env python</span>
  51
  52 <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">server</span>
  53 <span class="py-src-keyword">from</span> <span class="py-src-variable">twisted</span>.<span class="py-src-variable">internet</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">reactor</span>
  54 <span class="py-src-keyword">from</span> <span class="py-src-variable">mypackage</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">toplevel</span>
  55
  56 <span class="py-src-variable">reactor</span>.<span class="py-src-variable">listenTCP</span>(<span class="py-src-number">8080</span>,
  57     <span class="py-src-variable">server</span>.<span class="py-src-variable">Site</span>(<span class="py-src-variable">toplevel</span>.<span class="py-src-variable">Resource</span>(<span class="py-src-variable">file</span>=<span class="py-src-string">&quot;foo/bar&quot;</span>, <span class="py-src-variable">color</span>=<span class="py-src-string">&quot;blue&quot;</span>)))
  58 <span class="py-src-variable">reactor</span>.<span class="py-src-variable">run</span>()
  59 </pre>
  60
  61 <h2>Web application deployment<a name="auto1"/></h2>
  62
  63 <p>Which one of these development strategies you use is not terribly important,
  64 since (and this is the important part) deployment is <em>orthogonal</em>.
  65 Later, when you want users to actually <em>use</em> your code, you should worry
  66 about what to do -- or rather, don't.  Users may have widely different needs.
  67 Some may want to run your code in a different process, so they'll use
  68 distributed web (<code class="API"><a href="http://twistedmatrix.com/documents/12.1.0/api/twisted.web.distrib.html" title="twisted.web.distrib">twisted.web.distrib</a></code>).  Some may be
  69 using the <code>twisted-web</code> Debian package, and will drop in:</p>
  70
  71 <pre class="shell" xml:space="preserve">
  72 % cat &gt; /etc/local.d/99addmypackage.py
  73 from mypackage import toplevel
  74 default.putChild(&quot;mypackage&quot;, toplevel.Resource(file=&quot;foo/bar&quot;, color=&quot;blue&quot;))
  75 ^D
  76 </pre>
  77
  78 <p>If you want to be friendly to your users, you can supply many examples in
  79 your package, like the above <code>.rpy</code> and the Debian-package drop-in.
  80 But the <em>ultimate</em> friendliness is to write a useful resource which does
  81 not have deployment assumptions built in.</p>
  82
  83 <h2>Understanding resource scripts (<code>.rpy</code> files)<a name="auto2"/></h2>
  84
  85 <p>Twisted Web is not PHP -- it has better tools for organizing code Python
  86 modules and packages, so use them.  In PHP, the only tool for organizing code is
  87 a web page, which leads to silly things like PHP pages full of functions that
  88 other pages import, and so on.  If you were to write your code this way with
  89 Twisted Web, you would do web development using many <code>.rpy</code> files,
  90 all importing some Python module. This is a <em>bad idea</em> -- it mashes
  91 deployment with development, and makes sure your users will be <em>tied</em> to
  92 the file-system.</p>
  93
  94 <p>We have <code>.rpy</code>s because they are useful and necessary.
  95 But using them incorrectly leads to horribly unmaintainable
  96 applications.  The best way to ensure you are using them correctly is
  97 to not use them at all, until you are on your <em>final</em>
  98 deployment stages.  You should then find your <code>.rpy</code> files
  99 will be less than 10 lines, because you will not <em>have</em> more
 100 than 10 lines to write.</p>
 101
 102 </div>
 103
 104     <p><a href="index.html">Index</a></p>
 105     <span class="version">Version: 12.1.0</span>
 106   </body>
 107 </html>