WebStack

docs/resources.html

733:26865b172666
2007-11-12 paulb [project @ 2007-11-12 00:51:34 by paulb] Added a StringResource class for simple static resources. Introduced base classes for common authentication activities. Merged "app", "path" and "qs" fields into a single "app" field for login and redirection. Added support for OpenID authentication.
     1 <?xml version="1.0" encoding="iso-8859-1"?>     2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">     3 <html xmlns="http://www.w3.org/1999/xhtml"><head>     4   <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />     5   <title>Applications and Resources</title>     6   <link href="styles.css" rel="stylesheet" type="text/css" /></head>     7 <body>     8 <h1>Applications and Resources</h1>     9 At its simplest a WebStack application is just a single Python    10 class that we call a "resource". This class can be defined inside a    11 normal Python module or package, so let us start by doing the following:<br />    12 <ol>    13   <li>Create a new directory for    14 our application; choose any name since we just want an empty space in    15 which to put new files.</li>    16   <li>Create a file called <code>MyApplication.py</code>    17 - this is our module.</li>    18 </ol>    19 We are going to call our resource <code>MyResource</code>    20 and in principle it will have a structure that looks like this:    21 <pre>class MyResource:<br />    def respond(self, trans):<br />        [Examine the transaction, decide what the user wants to do.]<br />        [Perform some kind of action with the information supplied.]<br />        [Produce some kind of response which tells the user what happened.]</pre>    22 <p>It is in this kind of resource    23 class that we write the    24 actual application code or at least the beginnings of it. When a user    25 of the application sends us a request,    26 the <code>respond</code> method    27 will be called and the code    28 within it executed. The parts of the pseudo-code in    29 the above text which aren't valid Python    30 (ie. the bits in square brackets) will, when we have written them, use    31 the <code>trans</code>    32 object to find out what any given user of the application has sent us,    33 and to send information back    34 to the    35 user in response.</p>    36 <h2>Starting Simple</h2>    37 <p>The simplest way to turn this    38 into a working application is to    39 ignore the first two activities mentioned in the pseudo-code and just    40 to produce some kind of    41 response. Here is how we can make our application do something:</p>    42 <ol>    43   <li>Edit the module    44 file <code>MyApplication.py</code>.</li>    45   <li>Write into it the following    46 code which defines <code>MyResource</code>:</li>    47 </ol>    48 <pre>class MyResource:<br />    def respond(self, trans):<br />        out = trans.get_response_stream()<br />        print &gt;&gt;out, "Hello world."</pre>    49 <h2>Testing the Resource</h2>    50 <p>To test this resource we need to deploy it, and to do that we need    51 an    52 adapter to connect it to the outside world. Here is a quick way of writing an adapter and testing this    53 code:</p>    54 <ol>    55   <li> Create a file called <code>MyAdapter.py</code> - you    56 can choose another name if you want - this will be where the adapter    57 code lives.</li>    58   <li>Write into it the following code:</li></ol><pre>from WebStack.Adapters.BaseHTTPRequestHandler import deploy    # import the support for the server environment<br />from MyApplication import MyResource                           # import the main resource class<br />print "Serving..."                                             # just for testing - we might want to remove this later<br />deploy(MyResource())                                           # connect a resource object to the server environment</pre><p>Now, with two files in your directory, <code>MyApplication.py</code>    59 and <code>MyAdapter.py</code>, you may run <code>MyAdapter.py</code>    60 as follows:</p><ol>    61       62 </ol>    63 <pre>python MyAdapter.py</pre>    64 <p>This should start the adapter program and print the following    65 message:</p>    66 <pre>Serving...</pre>    67 <p>You should now be able to visit <code>http://localhost:8080</code>    68 in your    69 browser and see the message printed by your application:</p><pre>Hello world.</pre><h2>Related Examples</h2><p>The code presented in this document is very similar to that found in the following files:</p><ul><li><code>examples/Common/VerySimple/__init__.py</code> (where a package, <code>VerySimple</code>, is used to hold a <code>VerySimpleResource</code> class)</li><li><code>examples/BaseHTTPRequestHandler/VerySimpleApp.py</code> (where the resource is deployed)</li></ul><p>Note that a number of different adapters are provided in the <code>examples</code> directory hierarchy; for example:</p><ul><li><code>examples/CGI/VerySimpleHandler.py</code> (deploys the example as a CGI script)</li><li><code>examples/Twisted/VerySimpleApp.py</code> (deploys the example as a Twisted application)</li></ul><p>See <a href="deploying.html">"Deploying a WebStack Application"</a> for more information about adapters.</p></body></html>