1.1 --- a/docs/anatomy.html Sat Apr 09 23:50:49 2005 +0000
1.2 +++ b/docs/anatomy.html Sun Apr 10 21:11:25 2005 +0000
1.3 @@ -1,6 +1,6 @@
1.4 <?xml version="1.0" encoding="iso-8859-1"?>
1.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
1.6 - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1.7 + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1.8 <html xmlns="http://www.w3.org/1999/xhtml">
1.9 <head>
1.10 <title>Anatomy of a WebStack Application</title>
1.11 @@ -59,6 +59,8 @@
1.12 <li><a href="methods.html">Request Methods</a></li>
1.13 <li><a href="parameters.html">Request Parameters and Uploads</a></li>
1.14 <li><a href="responses.html">Responses and Presentation</a></li>
1.15 + <li><a href="state.html">Cookies, Sessions and Persistent
1.16 + Information</a></li>
1.17 </ul>
1.18 </body>
1.19 </html>
2.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
2.2 +++ b/docs/encodings.html Sun Apr 10 21:11:25 2005 +0000
2.3 @@ -0,0 +1,48 @@
2.4 +<?xml version="1.0" encoding="iso-8859-1"?>
2.5 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2.6 + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2.7 +<html xmlns="http://www.w3.org/1999/xhtml">
2.8 +<head>
2.9 + <title>Character Encodings</title>
2.10 + <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
2.11 + <link href="styles.css" rel="stylesheet" type="text/css" />
2.12 +</head>
2.13 +
2.14 +<body>
2.15 +<h1>Character Encodings</h1>
2.16 +
2.17 +<p>WebStack tries to let applications work with Unicode as much as possible,
2.18 +but there are two places where plain Python strings can be involved:</p>
2.19 +<ul>
2.20 + <li>When <a href="responses.html">output is prepared</a> - for example, Web
2.21 + pages.</li>
2.22 + <li>When <a href="parameters.html">inspecting request parameters</a>.</li>
2.23 +</ul>
2.24 +
2.25 +<h2>Recommendations</h2>
2.26 +
2.27 +<p>Although WebStack has some support for detecting character encodings used
2.28 +in requests, it is often best for your application to exercise control over
2.29 +which encoding is used when <a href="parameters.html">inspecting request
2.30 +parameters</a> and when <a href="responses.html">producing responses</a>. The
2.31 +best way to do this is to decide which encoding is most suitable for the data
2.32 +presented and received in your application and then to use it throughout.
2.33 +Here is an outline of code which does this:</p>
2.34 +<pre>from WebStack.Generic import ContentType
2.35 +
2.36 +class MyResource:
2.37 +
2.38 + encoding = "utf-8" # We decide on "utf-8" as our chosen
2.39 + # encoding.
2.40 + def respond(self, trans):
2.41 + [Do various things.]
2.42 +
2.43 + fields = trans.get_fields_from_body(encoding=self.encoding) # Explicitly use the encoding.
2.44 +
2.45 + [Do other things with the Unicode values from the fields.]
2.46 +
2.47 + trans.set_content_type(ContentType("text/html", self.encoding)) # The output Web page uses the encoding.
2.48 +
2.49 + [Produce the response, making sure that self.encoding is used to convert Unicode to raw strings.] </pre>
2.50 +</body>
2.51 +</html>
3.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
3.2 +++ b/docs/methods.html Sun Apr 10 21:11:25 2005 +0000
3.3 @@ -0,0 +1,91 @@
3.4 +<?xml version="1.0" encoding="iso-8859-1"?>
3.5 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
3.6 + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3.7 +<html xmlns="http://www.w3.org/1999/xhtml">
3.8 +<head>
3.9 + <title>Request Methods</title>
3.10 + <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
3.11 + <link href="styles.css" rel="stylesheet" type="text/css" />
3.12 +</head>
3.13 +
3.14 +<body>
3.15 +<h1>Request Methods</h1>
3.16 +
3.17 +<p>In order for an application to behave in the right way when someone sends
3.18 +a request into it, the application must take into consideration the type of
3.19 +request being sent. The type of request is typically referred to as the
3.20 +"request method" and indicates the kind of operation the user is attempting
3.21 +to perform.</p>
3.22 +
3.23 +<h2>Common Request Methods</h2>
3.24 +
3.25 +<p>The following table summarises the most common methods defined for Web
3.26 +applications in the HTTP and WebDAV specifications:</p>
3.27 +
3.28 +<table border="1" cellspacing="0" cellpadding="5">
3.29 + <tbody>
3.30 + <tr>
3.31 + <th>Method</th>
3.32 + <th>Type of Operation</th>
3.33 + </tr>
3.34 + <tr>
3.35 + <td>GET</td>
3.36 + <td>Retrieve a Web page or resource</td>
3.37 + </tr>
3.38 + <tr>
3.39 + <td>POST</td>
3.40 + <td>Present information to an application - for example, submission of
3.41 + fields in a form</td>
3.42 + </tr>
3.43 + <tr>
3.44 + <td>PUT</td>
3.45 + <td>Upload a new Web page or resource</td>
3.46 + </tr>
3.47 + <tr>
3.48 + <td>DELETE</td>
3.49 + <td>Delete a Web page or resource</td>
3.50 + </tr>
3.51 + <tr>
3.52 + <td>PROPFIND</td>
3.53 + <td>List resources on a server or in an application</td>
3.54 + </tr>
3.55 + </tbody>
3.56 +</table>
3.57 +
3.58 +<p>Most applications will at least need to support the GET request method in
3.59 +order to support some kind of user experience, and those which employ forms
3.60 +in Web pages will most probably want to support the POST request method,
3.61 +too.</p>
3.62 +
3.63 +<div class="WebStack">
3.64 +<h3>WebStack API - Discovering the Request Method</h3>
3.65 +
3.66 +<p>Transaction objects provide the following method for discovering the
3.67 +request method:</p>
3.68 +<dl>
3.69 + <dt><code>get_request_method</code></dt>
3.70 + <dd>This returns the request method being used in the request being
3.71 + handled.</dd>
3.72 +</dl>
3.73 +</div>
3.74 +
3.75 +<h2>Rejecting Certain Request Methods</h2>
3.76 +
3.77 +<p>Not all request methods are appropriate to every application. Should a
3.78 +request be received which uses a method not supported by an application, the
3.79 +most appropriate way of responding is to signal this condition to the sender
3.80 +of the request. HTTP provides a response code to communicate just this kind
3.81 +of condition - "405 Method Not Allowed".</p>
3.82 +
3.83 +<div class="WebStack">
3.84 +<h3>WebStack API - Signalling Unsupported Methods</h3>
3.85 +
3.86 +<p>Transaction objects provide the <code>set_response_code</code> method (as
3.87 +described in <a href="responses.html">"Responses and Presentation"</a>) to
3.88 +communicate critical information on the success or failure of a request. In
3.89 +this case, we would use this method on a transaction object
3.90 +<code>trans</code> as follows:</p>
3.91 +<pre>trans.set_response_code(405)</pre>
3.92 +</div>
3.93 +</body>
3.94 +</html>
4.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
4.2 +++ b/docs/parameters-body.html Sun Apr 10 21:11:25 2005 +0000
4.3 @@ -0,0 +1,70 @@
4.4 +<?xml version="1.0" encoding="iso-8859-1"?>
4.5 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
4.6 + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
4.7 +<html xmlns="http://www.w3.org/1999/xhtml">
4.8 +<head>
4.9 + <title>Request Body Parameters</title>
4.10 + <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
4.11 + <link href="styles.css" rel="stylesheet" type="text/css" />
4.12 +</head>
4.13 +
4.14 +<body>
4.15 +<h1>Request Body Parameters</h1>
4.16 +
4.17 +<p>Request parameters are typically added to the request body when forms are
4.18 +submitted by a browser which is instructed to use the <code>POST</code> <a
4.19 +href="methods.html">request method</a>. A Web form (in HTML) can be used to
4.20 +achieve this; for example:</p>
4.21 +<pre><form method="POST" action="http://www.boddie.org.uk/application">
4.22 + <input name="param1" type="text" />
4.23 + <input name="param2" type="text" />
4.24 +</form></pre>
4.25 +
4.26 +<p>As a consequence of this form being submitted, the following parameters
4.27 +will become available in the application:</p>
4.28 +<ul>
4.29 + <li><code>param1</code> with the value <code><code>value1</code></code></li>
4.30 + <li><code><code>param2</code></code> with the value <code>value2</code></li>
4.31 +</ul>
4.32 +
4.33 +<p>Parameters encoded in this way are not transferred in URLs and are mostly
4.34 +hidden in user interfaces, although viewing a Web page's source can often
4.35 +reveal default values of such parameters.</p>
4.36 +
4.37 +<div class="WebStack">
4.38 +<h3>WebStack API - Accessing Body Parameters</h3>
4.39 +
4.40 +<p>Transaction objects provide the following methods to access parameters
4.41 +specified in request headers. The terminology used in the API describes such
4.42 +parameters as body fields, since such parameters are often provided by form
4.43 +fields.</p>
4.44 +<dl>
4.45 + <dt><code>get_fields_from_body</code></dt>
4.46 + <dd>This returns the request parameters (fields) found in the request
4.47 + body (as defined in Web forms). The fields are provided in a dictionary
4.48 + mapping field names to lists of values. Each value will be a Unicode
4.49 + object unless the value represents uploaded file content (see
4.50 + below).<br />
4.51 + An optional <code>encoding</code> parameter may be used to assist the
4.52 + process of converting parameter values to Unicode objects - see below
4.53 + for a discussion of the issues with this parameter.</dd>
4.54 +</dl>
4.55 +</div>
4.56 +
4.57 +<p>Some limitations exist with request body parameters:</p>
4.58 +<ul>
4.59 + <li>For the conversion of such parameters to Unicode to function correctly,
4.60 + care must be taken with character encodings - this is discussed in <a
4.61 + href="responses.html">"Responses and Presentation"</a> and also in <a
4.62 + href="encodings.html">"Character Encodings"</a>.</li>
4.63 +</ul>
4.64 +
4.65 +<h2>File Uploads</h2>
4.66 +
4.67 +<p>One way request body parameters may be used is to provide a mechanism for
4.68 +the uploading of entire files from browsers and other Web clients to
4.69 +applications. Unlike other parameters, those which carry file upload data
4.70 +expose the contents of such uploaded files as plain Python string values
4.71 +instead of Unicode objects.</p>
4.72 +</body>
4.73 +</html>
5.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
5.2 +++ b/docs/parameters-headers.html Sun Apr 10 21:11:25 2005 +0000
5.3 @@ -0,0 +1,67 @@
5.4 +<?xml version="1.0" encoding="iso-8859-1"?>
5.5 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
5.6 + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
5.7 +<html xmlns="http://www.w3.org/1999/xhtml">
5.8 +<head>
5.9 + <title>Request Header Parameters</title>
5.10 + <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
5.11 + <link href="styles.css" rel="stylesheet" type="text/css" />
5.12 +</head>
5.13 +
5.14 +<body>
5.15 +<h2>Request Header Parameters</h2>
5.16 +
5.17 +<p>Header parameters are typically specified in the URL like this:</p>
5.18 +<pre>http://www.boddie.org.uk/application?param1=value1&param2=value2</pre>
5.19 +
5.20 +<p>Following the rules set out in <a href="paths.html">"URLs and Paths"</a>,
5.21 +we can say that the "query string" employed is this:</p>
5.22 +<pre>param1=value1&param2=value2</pre>
5.23 +
5.24 +<p>From this string, we may extract the parameters and state that they are
5.25 +the following:</p>
5.26 +<ul>
5.27 + <li><code>param1</code> with the value <code>value1</code></li>
5.28 + <li><code>param2</code> with the value <code>value2</code></li>
5.29 +</ul>
5.30 +
5.31 +<p>Parameters encoded in this way can be written into hyperlinks and may be
5.32 +used to remember things as users navigate their way around an application.
5.33 +Alternatively, a Web form (in HTML) written to use the <code>GET</code> <a
5.34 +href="methods.html">request method</a> may be used to achieve the same
5.35 +effect:</p>
5.36 +<pre><form method="GET" action="http://www.boddie.org.uk/application">
5.37 + <input name="param1" type="text" />
5.38 + <input name="param2" type="text" />
5.39 +</form></pre>
5.40 +
5.41 +<div class="WebStack">
5.42 +<h3>WebStack API - Accessing Header Parameters</h3>
5.43 +
5.44 +<p>Transaction objects provide the following methods to access parameters
5.45 +specified in request headers. The terminology used in the API describes such
5.46 +parameters as path fields, since such parameters are often provided by form
5.47 +fields.</p>
5.48 +<dl>
5.49 + <dt><code>get_fields_from_path</code></dt>
5.50 + <dd>This returns the request parameters (fields) from the request headers
5.51 + (as defined in the path or URL). The fields are provided in a
5.52 + dictionary mapping field names to lists of values</dd>
5.53 + <dt><code>get_query_string</code></dt>
5.54 + <dd>This returns the query string - ie. the part of the path or URL which
5.55 + contains the parameters. Typically, it is easier to use the above
5.56 + method instead.</dd>
5.57 +</dl>
5.58 +</div>
5.59 +
5.60 +<p>There are some limitations with header parameters:</p>
5.61 +<ul>
5.62 + <li>Since URLs are used to carry such parameters, any such parameter which
5.63 + should remain hidden will appear in the URL and probably be shown in
5.64 + browsers and other user interfaces.</li>
5.65 + <li>There isn't widespread agreement about how non-ASCII characters should
5.66 + be encoded in URLs. Therefore, care must be taken to encode and decode
5.67 + values transferred in request headers.</li>
5.68 +</ul>
5.69 +</body>
5.70 +</html>
6.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
6.2 +++ b/docs/parameters.html Sun Apr 10 21:11:25 2005 +0000
6.3 @@ -0,0 +1,65 @@
6.4 +<?xml version="1.0" encoding="iso-8859-1"?>
6.5 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
6.6 + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
6.7 +<html xmlns="http://www.w3.org/1999/xhtml">
6.8 +<head>
6.9 + <title>Request Parameters and Uploads</title>
6.10 + <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
6.11 + <link href="styles.css" rel="stylesheet" type="text/css" />
6.12 +</head>
6.13 +
6.14 +<body>
6.15 +<h1>Request Parameters and Uploads</h1>
6.16 +
6.17 +<p>Even though it is possible to expose different parts of an application
6.18 +using different <a href="paths.html">URLs and paths</a>, this usually is only
6.19 +enough for applications which model some kind of <a
6.20 +href="paths-filesystem.html">filesystem</a> or repository. Applications which
6.21 +involve user input through forms, for example, need to be able to receive
6.22 +such input by other means, and this is where request parameters come in. For
6.23 +example, when a user fills out a form in a Web browser, the following
6.24 +happens:</p>
6.25 +<ol>
6.26 + <li>The browser collects the values in the form fields and puts them in a
6.27 + request as request parameters.</li>
6.28 + <li>The request is sent to the server environment and into the
6.29 + application.</li>
6.30 + <li>The application reads the field values using the WebStack API.</li>
6.31 +</ol>
6.32 +
6.33 +<h2>Parameter Origins</h2>
6.34 +
6.35 +<p>Request parameters can originate from two sources:</p>
6.36 +<ul>
6.37 + <li><a href="parameters-headers.html">Request headers</a> - parameters are
6.38 + found here when they are specified in the URL as a "query string".</li>
6.39 + <li><a href="parameters-body.html">Request bodies</a> - parameters are
6.40 + found here when the POST <a href="methods.html">request method</a> is
6.41 + used.</li>
6.42 +</ul>
6.43 +
6.44 +<div class="WebStack">
6.45 +<h3>WebStack API - Getting All Parameters</h3>
6.46 +
6.47 +<p>If the origin of the different parameters received in a request is not
6.48 +particularly interesting or important, WebStack provides a convenience method
6.49 +in transaction objects to get all known parameters from a request:</p>
6.50 +<dl>
6.51 + <dt><code>get_fields</code></dt>
6.52 + <dd>This method returns a dictionary mapping field names to lists of
6.53 + values for all known parameters. Each value will be a Unicode
6.54 + object.<br />
6.55 + An optional <code>encoding</code> parameter may be used to assist the
6.56 + process of converting parameter values to Unicode objects - see <a
6.57 + href="parameters-body.html">"Request Body Parameters"</a> and <a
6.58 + href="encodings.html">"Character Encodings"</a> for more discussion of
6.59 + this parameter.</dd>
6.60 +</dl>
6.61 +</div>
6.62 +
6.63 +<p>Generally, it is not recommended to just get all parameters since there
6.64 +may be some parameters from the request headers which have the same names as
6.65 +some other parameters from the request body. Consequently, confusion could
6.66 +arise about the significance of various parameter values.</p>
6.67 +</body>
6.68 +</html>
7.1 --- a/docs/paths.html Sat Apr 09 23:50:49 2005 +0000
7.2 +++ b/docs/paths.html Sun Apr 10 21:11:25 2005 +0000
7.3 @@ -1,6 +1,6 @@
7.4 <?xml version="1.0" encoding="iso-8859-1"?>
7.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
7.6 - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
7.7 + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
7.8 <html xmlns="http://www.w3.org/1999/xhtml">
7.9 <head>
7.10 <title>URLs and Paths</title>
7.11 @@ -38,8 +38,7 @@
7.12 concentrate on the path because the address doesn't usually tell you anything
7.13 you don't already know. What you need to do is to interpret the path
7.14 specified in the request in order to work out which resource or service the
7.15 -request is destined for.<br />
7.16 -</p>
7.17 +request is destined for.</p>
7.18
7.19 <div class="WebStack">
7.20 <h3>WebStack API - Path Methods in Transaction Objects</h3>
7.21 @@ -49,14 +48,23 @@
7.22 <dl>
7.23 <dt><code>get_path</code></dt>
7.24 <dd>This gets the entire path of a resource including parameter
7.25 - information - see <a href="parameters.html">"Request Parameters and
7.26 - Uploads"</a>.</dd>
7.27 + information (as described in <a href="parameters.html">"Request
7.28 + Parameters and Uploads"</a>).</dd>
7.29 <dt><code>get_path_without_query</code></dt>
7.30 <dd>This gets the entire path of a resource but without any parameter
7.31 information.</dd>
7.32 </dl>
7.33 </div>
7.34
7.35 +<p>Sometimes, a "query string" will be provided as part of a URL; for
7.36 +example:</p>
7.37 +<pre>http://www.boddie.org.uk/application?param1=value1</pre>
7.38 +
7.39 +<p>The question mark character marks the beginning of the query string which
7.40 +contains encoded parameter information; such information and its inspection
7.41 +is discussed in <a href="parameters.html">"Request Parameters and
7.42 +Uploads"</a>.</p>
7.43 +
7.44 <h2>Paths To and Within an Application</h2>
7.45 One thing to be aware of in the code of an application is which part of a
7.46 path refers to the location of the application in a server environment and