Ticket #4576: web.xhtml.2.patch

File web.xhtml.2.patch, 20.0 KB (added by jdb, 6 years ago)

correction in the patch

  • doc/web/howto/resource-templates.xhtml

    diff --git a/doc/web/howto/resource-templates.xhtml b/doc/web/howto/resource-templates.xhtml
    index be7226a..b34d183 100644
    a b  
    1212
    1313<h2>Overview</h2>
    1414
    15 <p>While high-level templating systems can be used with Twisted (for example,
    16 <a href="http://divmod.org/trac/wiki/DivmodNevow">Divmod Nevow</a>, sometimes
    17 one needs a less file-heavy system which lets one directly write HTML. While
    18 ResourceScripts are available, they have a high overhead of coding, needing
    19 some boring string arithmetic. ResourceTemplates fill the space between Nevow
    20 and ResourceScript using Quixote's PTL (Python Templating Language).</p>
    21 
    22 <p>ResourceTemplates need Quixote installed. In
    23 <a href="http://www.debian.org">Debian</a>, that means using Python 2.2
    24 and installing the <code>quixote</code> package
    25 (<code>apt-get install quixote</code>). Other operating systems require
    26 other ways to install quixote, or it can be done manually.</p>
     15<p>While high-level templating systems can be used with Twisted (for
     16example, <a href="http://divmod.org/trac/wiki/DivmodNevow">Divmod
     17Nevow</a>, sometimes one needs a less file-heavy system which lets one
     18directly write HTML. While ResourceScripts are available, they have a
     19high overhead of coding, needing some boring string
     20arithmetic. ResourceTemplates fill the space between Nevow and
     21ResourceScript using Quixote's PTL (Python Templating Language).</p>
     22
     23<p>ResourceTemplates need Quixote
     24installed. In <a href="http://www.debian.org">Debian</a>, that means
     25using Python 2.2 and installing the <code>quixote</code> package
     26(<code>apt-get install quixote</code>). Other operating systems
     27require other ways to install quixote, or it can be done manually.</p>
    2728
    2829<h2>Configuring Twisted.Web</h2>
    2930
    more Python coding and are outside the scope of this HOWTO.</p> 
    4445
    4546<p>ResourceTemplates are coded in an extension of Python called the
    4647<q>Python Templating Language</q>. Complete documentation of the PTL
    47 is available at <a href="http://www.mems-exchange.org/software/quixote/doc/PTL.html">the quixote web site</a>. The web server
    48 will expect the PTL source file to define a variable named
    49 <code>resource</code>.
    50 This should be a <code class="API">twisted.web.server.Resource</code>,
     48is available
     49at <a href="http://www.mems-exchange.org/software/quixote/doc/PTL.html">the
     50quixote web site</a>. The web server will expect the PTL source file
     51to define a variable named <code>resource</code>.  This should be
     52a <code class="API">twisted.web.server.Resource</code>,
    5153whose <code>.render</code> method be called. Usually, you would want
    5254to define <code>render</code> using the keyword <code>template</code>
    5355rather than <code>def</code>.</p>
  • doc/web/howto/using-twistedweb.xhtml

    diff --git a/doc/web/howto/using-twistedweb.xhtml b/doc/web/howto/using-twistedweb.xhtml
    index 5c4c388..b681a2c 100644
    a b IResource.</p> 
    2121
    2222<ul>
    2323
    24 <li><a href="#sites">Site Objects</a> are responsible for creating
    25 <code>HTTPChannel</code> instances to parse the HTTP request, and begin the object lookup process. They contain the root Resource, the resource which represents the URL <code>/</code> on the site.</li>
     24<li><a href="#sites">Site Objects</a> are responsible for
     25creating <code>HTTPChannel</code> instances to parse the HTTP request,
     26and begin the object lookup process. They contain the root Resource,
     27the resource which represents the URL <code>/</code> on the site.</li>
    2628
    2729<li><a href="#resources">Resource</a> objects represent a single URL segment. The <code class="API" base="twisted.web.resource">IResource</code> interface describes the methods a Resource object must implement in order to participate in the object publishing process.</li>
    2830
    IResource.</p> 
    4951
    5052<p>When using <code>twistd -n web --path /foo/bar/baz</code>, a Site object is created with a root Resource that serves files out of the given path.</p>
    5153
    52 <p>You can also create a <code>Site</code> instance by hand, passing it a
    53 <code>Resource</code> object which will serve as the root of the site:</p>
     54<p>You can also create a <code>Site</code> instance by hand, passing
     55it a <code>Resource</code> object which will serve as the root of the
     56site:</p>
    5457
    5558<pre class="python">
    5659from twisted.web import server, resource
    resource = myresource.MyResource() 
    173176
    174177The <code class="API" base="twisted.web.resource">Resource</code>
    175178class, which is usually what one's Resource classes subclass, has a
    176 convenient default implementation of <code
    177 class="python">render</code>. It will call a method named <code
    178 class="python">self.render_METHOD</code> where <q>METHOD</q> is
    179 whatever HTTP method was used to request this resource. Examples:
    180 request_GET, request_POST, request_HEAD, and so on. It is recommended
    181 that you have your resource classes subclass <code class="API"
    182 base="twisted.web.resource">Resource</code> and implement <code
    183 class="python">render_METHOD</code> methods as opposed to <code
    184 class="python">render</code> itself. Note that for certain resources,
    185 <code class="python">request_POST = request_GET</code> may be
    186 desirable in case one wants to process arguments passed to the
    187 resource regardless of whether they used GET
     179convenient default implementation
     180of <code class="python">render</code>. It will call a method
     181named <code class="python">self.render_METHOD</code>
     182where <q>METHOD</q> is whatever HTTP method was used to request this
     183resource. Examples: request_GET, request_POST, request_HEAD, and so
     184on. It is recommended that you have your resource classes
     185subclass <code class="API" base="twisted.web.resource">Resource</code>
     186and implement <code class="python">render_METHOD</code> methods as
     187opposed to <code class="python">render</code> itself. Note that for
     188certain resources, <code class="python">request_POST =
     189request_GET</code> may be desirable in case one wants to process
     190arguments passed to the resource regardless of whether they used GET
    188191(<code>?foo=bar&amp;baz=quux</code>, and so forth) or POST.
    189192
    190193</p>
    resource regardless of whether they used GET 
    201204<h2>Advanced Configuration</h2>
    202205
    203206<p>Non-trivial configurations of Twisted Web are achieved with Python
    204 configuration files. This is a Python snippet which builds up a variable
    205 called application. Usually, a <code class="API">twisted.application.internet.TCPServer</code> instance will
    206 be used to make the application listen on a TCP port (80, in case direct
    207 web serving is desired), with the listener being a
    208 <code class="API">twisted.web.server.Site</code>. The resulting file can then
    209 be run with <code class="shell">twistd -y</code>. Alternatively a reactor
    210 object can be used directly to make a runnable script.</p>
     207configuration files. This is a Python snippet which builds up a
     208variable called application. Usually,
     209a <code class="API">twisted.application.internet.TCPServer</code>
     210instance will be used to make the application listen on a TCP port
     211(80, in case direct web serving is desired), with the listener being
     212a <code class="API">twisted.web.server.Site</code>. The resulting file
     213can then be run with <code class="shell">twistd
     214-y</code>. Alternatively a reactor object can be used directly to make
     215a runnable script.</p>
    211216
    212217<p>The <code>Site</code> will wrap a <code>Resource</code> object -- the
    213218root.</p>
    reactor.run() 
    259264
    260265<h3>Modifying File Resources</h3>
    261266
    262 <p><code>File</code> resources, be they root object or children thereof,
    263 have two important attributes that often need to be modified:
    264 <code>indexNames</code> and <code>processors</code>. <code>indexNames</code>
    265 determines which files are treated as <q>index files</q> -- served
    266 up when a directory is rendered. <code>processors</code> determine how
    267 certain file extensions are treated.</p>
     267<p><code>File</code> resources, be they root object or children
     268thereof, have two important attributes that often need to be
     269modified: <code>indexNames</code>
     270and <code>processors</code>. <code>indexNames</code> determines which
     271files are treated as <q>index files</q> -- served up when a directory
     272is rendered. <code>processors</code> determine how certain file
     273extensions are treated.</p>
    268274
    269275<p>Here is an example for both, creating a site where all <code>.rpy</code>
    270276extensions are Resource Scripts, and which renders directories by
    exists.</p> 
    308314
    309315<h3>Virtual Hosts</h3>
    310316
    311 <p>Virtual hosting is done via a special resource, that should be
    312 used as the root resource -- <code>NameVirtualHost</code>.
    313 <code>NameVirtualHost</code> has an attribute named <code>default</code>,
    314 which holds the default website. If a different root for some other
    315 name is desired, the <code>addHost</code> method should be called.</p>
     317<p>Virtual hosting is done via a special resource, that should be used
     318as the root resource
     319-- <code>NameVirtualHost</code>. <code>NameVirtualHost</code> has an
     320attribute named <code>default</code>, which holds the default
     321website. If a different root for some other name is desired,
     322the <code>addHost</code> method should be called.</p>
    316323
    317324<pre class="python">
    318325from twisted.application import internet, service
    it when it is not. 
    529536
    530537<h3>Serving PHP/Perl/CGI</h3>
    531538
    532 <p>Everything related to CGI is located in the
    533 <code>twisted.web.twcgi</code>, and it's here you'll find the classes that you
    534 need to subclass in order to support the language of your (or somebody elses)
    535 taste. You'll also need to create your own kind of resource if you are using a
    536 non-unix operating system (such as Windows), or if the default resources has
    537 wrong pathnames to the parsers.</p>
     539<p>Everything related to CGI is located in
     540the <code>twisted.web.twcgi</code>, and it's here you'll find the
     541classes that you need to subclass in order to support the language of
     542your (or somebody elses) taste. You'll also need to create your own
     543kind of resource if you are using a non-unix operating system (such as
     544Windows), or if the default resources has wrong pathnames to the
     545parsers.</p>
    538546
    539547<p>The following snippet is a .rpy that serves perl-files. Look at <code>twisted.web.twcgi</code>
    540548for more examples regarding twisted.web and CGI.</p>
    from twisted.web import vhost 
    643651resource = vhost.VHostMonsterResource()
    644652</pre>
    645653
    646 <p>Make sure the web server is configured with the correct processors for the
    647 <code>rpy</code> extensions (the web server
    648 <code>twistd web --path</code> generates by default is so configured).</p>
     654<p>Make sure the web server is configured with the correct processors
     655for the <code>rpy</code> extensions (the web server <code>twistd web
     656--path</code> generates by default is so configured).</p>
    649657
    650658<p>From the Apache side, instead of using the following ProxyPass directive:</p>
    651659
    i.setServiceParent(sc) 
    684692
    685693<h2>Rewriting URLs</h2>
    686694
    687 <p>Sometimes it is convenient to modify the content of the
    688 <code class="API" base="twisted.web.server">Request</code> object
     695<p>Sometimes it is convenient to modify the content of
     696the <code class="API" base="twisted.web.server">Request</code> object
    689697before passing it on. Because this is most often used to rewrite
    690 either the URL, the similarity to Apache's <code>mod_rewrite</code> has
    691 inspired the <code class="API">twisted.web.rewrite</code> module. Using
    692 this module is done via wrapping a resource with a
    693 <code class="API">twisted.web.rewrite.RewriterResource</code> which
    694 then has rewrite rules. Rewrite rules are functions which accept a request
    695 object, and possible modify it. After all rewrite rules run, the child
    696 resolution chain continues as if the wrapped resource, rather than
    697 the <code class="API" base="twisted.web.rewrite">RewriterResource</code>,
    698 was the child.</p>
     698either the URL, the similarity to Apache's <code>mod_rewrite</code>
     699has inspired the <code class="API">twisted.web.rewrite</code>
     700module. Using this module is done via wrapping a resource with
     701a <code class="API">twisted.web.rewrite.RewriterResource</code> which
     702then has rewrite rules. Rewrite rules are functions which accept a
     703request object, and possible modify it. After all rewrite rules run,
     704the child resolution chain continues as if the wrapped resource,
     705rather than the <code class="API"
     706base="twisted.web.rewrite">RewriterResource</code>, was the child.</p>
    699707
    700708<p>Here is an example, using the only rule currently supplied by Twisted
    701709itself:</p>
    itself:</p> 
    704712default_root = rewrite.RewriterResource(default, rewrite.tildeToUsers)
    705713</pre>
    706714
    707 <p>This causes the URL <code>/~foo/bar.html</code> to be treated like
    708 <code>/users/foo/bar.html</code>. If done after setting default's
    709 <code>users</code> child to a
    710 <code class="API" base="twisted.web">distrib.UserDirectory</code>,
    711 it gives a configuration similar to the classical configuration of
    712 web server, common since the first NCSA servers.</p>
     715<p>This causes the URL <code>/~foo/bar.html</code> to be treated
     716like <code>/users/foo/bar.html</code>. If done after setting
     717default's <code>users</code> child to a <code class="API"
     718base="twisted.web">distrib.UserDirectory</code>, it gives a
     719configuration similar to the classical configuration of web server,
     720common since the first NCSA servers.</p>
    713721
    714722<h2>Knowing When We're Not Wanted</h2>
    715723
    are frustrated after merely 10 seconds.</p> 
    741749
    742750<h2>As-Is Serving</h2>
    743751
    744 <p>Sometimes, you want to be able to send headers and status directly. While
    745 you can do this with a
    746 <code base="twisted.web.script" class="API">ResourceScript</code>, an easier
    747 way is to use <code base="twisted.web.static" class="API">ASISProcessor</code>.
    748 Use it by, for example, adding it as a processor for the <code>.asis</code>
    749 extension. Here is a sample file:</p>
     752<p>Sometimes, you want to be able to send headers and status
     753directly. While you can do this with a <code base="twisted.web.script"
     754class="API">ResourceScript</code>, an easier way is to
     755use <code base="twisted.web.static" class="API">ASISProcessor</code>.
     756Use it by, for example, adding it as a processor for
     757the <code>.asis</code> extension. Here is a sample file:</p>
    750758
    751759<pre>
    752760HTTP/1.0 200 OK
  • doc/web/howto/web-development.xhtml

    diff --git a/doc/web/howto/web-development.xhtml b/doc/web/howto/web-development.xhtml
    index 0a987d1..562cccf 100644
    a b all importing some Python module. This is a <em>bad idea</em> -- it mashes 
    8282deployment with development, and makes sure your users will be <em>tied</em> to
    8383the file-system.</p>
    8484
    85 <p>We have <code>.rpy</code>s because they are useful and necessary.  But using
    86 them incorrectly leads to horribly unmaintainable applications.  The best way to
    87 ensure you are using them correctly is to not use them at all, until you are on
    88 your <em>final</em> deployment stages.  You should then find your
    89 <code>.rpy</code> files will be less than 10 lines, because you will not
    90 <em>have</em> more than 10 lines to write.</p>
     85<p>We have <code>.rpy</code>s because they are useful and necessary.
     86But using them incorrectly leads to horribly unmaintainable
     87applications.  The best way to ensure you are using them correctly is
     88to not use them at all, until you are on your <em>final</em>
     89deployment stages.  You should then find your <code>.rpy</code> files
     90will be less than 10 lines, because you will not <em>have</em> more
     91than 10 lines to write.</p>
    9192
    9293</body>
    9394
  • doc/web/howto/xmlrpc.xhtml

    diff --git a/doc/web/howto/xmlrpc.xhtml b/doc/web/howto/xmlrpc.xhtml
    index 38001e4..b0bb5cc 100644
    a b resource scripts. The following is an example of such a resource script:</p> 
    9999<h3>Using XML-RPC sub-handlers</h3>
    100100
    101101<p>XML-RPC resource can be nested so that one handler calls another if
    102 a method with a given prefix is called. For example, to add support for
    103 an XML-RPC method <code>date.time()</code> to the
    104 <code class="python">Example</code> class, you could do the following:</p>
     102a method with a given prefix is called. For example, to add support
     103for an XML-RPC method <code>date.time()</code> to
     104the <code class="python">Example</code> class, you could do the
     105following:</p>
    105106
    106107<pre class="python">
    107108import time
    using this method.</p> 
    142143
    143144<h3>Adding XML-RPC Introspection support</h3>
    144145
    145 <p>XML-RPC has an informal <a href="http://ldp.kernelnotes.de/HOWTO/XML-RPC-HOWTO/xmlrpc-howto-interfaces.html">Introspection API</a> that specifies three
    146 methods in a <code>system</code> sub-handler which allow a client to query
    147 a server about the server's API. Adding Introspection support to the
    148 <code class="python">Example</code> class is easy using the
    149 <code base="twisted.web.xmlrpc" class="API">XMLRPCIntrospection</code>
    150 class:</p>
     146<p>XML-RPC has an
     147informal <a href="http://ldp.kernelnotes.de/HOWTO/XML-RPC-HOWTO/xmlrpc-howto-interfaces.html">Introspection
     148API</a> that specifies three methods in a <code>system</code>
     149sub-handler which allow a client to query a server about the server's
     150API. Adding Introspection support to
     151the <code class="python">Example</code> class is easy using
     152the <code base="twisted.web.xmlrpc"
     153class="API">XMLRPCIntrospection</code> class:</p>
    151154
    152155<pre class="python">
    153156from twisted.web import xmlrpc, server
    if __name__ == '__main__': 
    181184    reactor.run()
    182185</pre>
    183186
    184 <p>Note the method attributes <code class="python">help</code> and
    185 <code class="python">signature</code> which are used by the Introspection
    186 API methods <code>system.methodHelp</code> and
    187 <code>system.methodSignature</code> respectively. If no
    188 <code class="python">help</code> attribute is specified,
    189 the method's documentation string is used instead.</p>
     187<p>Note the method attributes <code class="python">help</code>
     188and <code class="python">signature</code> which are used by the
     189Introspection API methods <code>system.methodHelp</code>
     190and <code>system.methodSignature</code> respectively. If
     191no <code class="python">help</code> attribute is specified, the
     192method's documentation string is used instead.</p>
    190193
    191194<h2>SOAP Support</h2>
    192195
    from the <code>xmlrpclib</code> way which should be noted:</p> 
    210213    <code>callRemote</code>.</li>
    211214</ol>
    212215
    213 <p>The interface Twisted presents to XML-RPC client is that of a proxy object:
    214 <code class="API">twisted.web.xmlrpc.Proxy</code>. The constructor for the
    215 object receives a URL: it must be an HTTP or HTTPS URL. When an XML-RPC service
    216 is described, the URL to that service will be given there.</p>
     216<p>The interface Twisted presents to XML-RPC client is that of a proxy
     217object: <code class="API">twisted.web.xmlrpc.Proxy</code>. The
     218constructor for the object receives a URL: it must be an HTTP or HTTPS
     219URL. When an XML-RPC service is described, the URL to that service
     220will be given there.</p>
    217221
    218222<p>Having a proxy object, one can just call the <code>callRemote</code> method,
    219223which accepts a method name and a variable argument list (but no named
    def printError(error): 
    237241    print 'error', error
    238242    reactor.stop()
    239243
    240 proxy = Proxy('http://advogato.org/XMLRPC')
     244proxy = Proxy('http://advogato.oubunturg/XMLRPC')
    241245proxy.callRemote('test.sumprod', 3, 5).addCallbacks(printValue, printError)
    242246reactor.run()
    243247</pre>
    SOAP in the one web server, you can use the <code class="API" 
    257261base="twisted.web.resource.IResource">putChild</code> method of Resources.</p>
    258262
    259263<p>The following example uses an empty <code class="API"
    260 base="twisted.web">resource.Resource</code> as the root resource for a <code
    261 class="API" base="twisted.web.server">Site</code>, and then adds
    262 <code>/RPC2</code> and <code>/SOAP</code> paths to it.</p>
     264base="twisted.web">resource.Resource</code> as the root resource for
     265a <code class="API" base="twisted.web.server">Site</code>, and then
     266adds <code>/RPC2</code> and <code>/SOAP</code> paths to it.</p>
    263267
    264268<a href="listings/xmlAndSoapQuote.py" class="py-listing">xmlAndSoapQuote.py</a>
    265269
    266 <p>Refer to <a href="using-twistedweb.xhtml#development">Twisted Web
     270<p>Refer to <a href="using-twistedweb.xhtml#development">Twisted Web
    267271Development</a> for more details about Resources.</p>
    268272
    269273  </body>