1.1 --- a/docs/anatomy.html Sat Sep 08 16:01:41 2007 +0000 1.2 +++ b/docs/anatomy.html Sat Sep 08 16:02:18 2007 +0000 1.3 @@ -1,8 +1,8 @@ 1.4 +<?xml version="1.0" encoding="iso-8859-1"?> 1.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 1.6 <html xmlns="http://www.w3.org/1999/xhtml"><head> 1.7 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> 1.8 - 1.9 - <title>Anatomy of a WebStack Application</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 1.10 + <title>Anatomy of a WebStack Application</title> 1.11 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 1.12 1.13 <body> 1.14 @@ -58,4 +58,4 @@ 1.15 </tr> 1.16 </tbody> 1.17 </table> 1.18 -</body></html> 1.19 \ No newline at end of file 1.20 +</body></html>
2.1 --- a/docs/attributes.html Sat Sep 08 16:01:41 2007 +0000 2.2 +++ b/docs/attributes.html Sat Sep 08 16:02:18 2007 +0000 2.3 @@ -1,8 +1,8 @@ 2.4 +<?xml version="1.0" encoding="iso-8859-1"?> 2.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 2.6 <html xmlns="http://www.w3.org/1999/xhtml"><head> 2.7 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> 2.8 - 2.9 - <title>Transaction Attributes</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 2.10 + <title>Transaction Attributes</title> 2.11 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 2.12 <body> 2.13 <h1>Transaction Attributes</h1> 2.14 @@ -54,4 +54,4 @@ 2.15 customer departments. This resource would do the following:</p><ol><li>Ask for the path without info, along with the processed virtual path info (as described in <a href="path-info.html">"Paths To and Within Applications"</a>).</li><li>Join the paths together.</li><li>Store the result on an attribute (called "root", perhaps).</li><li>Invoke another resource.</li></ol><p>The advantage of doing this dynamically is that should we decide to change the location of the application or the path to <code>services</code> within it, we will not need to track down hard-coded path values and change them in lots of different places.</p><p>Fortunately, WebStack provides a class to do this work for us - <code>PathSelector</code> - and we can use it in the following way:</p><pre>from WebStack.Resources.Selectors import PathSelector<br /><br />resource = MapResource({<br /> "services" : PathSelector(<br /> MapResource({<br /> "finance" : finance_department,<br /> "customer" : customer_department<br /> })<br /> )<br /> })</pre><p>Now, once the <code>services</code> part of the path has been detected, the <code>PathSelector</code> resource will discover the path details, store them on an attribute, and then invoke the <code>MapResource</code> which chooses between departments, which in turn invokes other resources, and so on. However, all of the resources "below" the <code>PathSelector</code> resource 2.16 will have an attribute called "root" which contains the selected "root 2.17 path" of the application (or at least the interesting part of the 2.18 -application).</p><p>See the <a href="selectors.html">"Selectors"</a> document for more details of the <code>PathSelector</code> class.</p></body></html> 2.19 \ No newline at end of file 2.20 +application).</p><p>See the <a href="selectors.html">"Selectors"</a> document for more details of the <code>PathSelector</code> class.</p></body></html>
3.1 --- a/docs/authenticators.html Sat Sep 08 16:01:41 2007 +0000 3.2 +++ b/docs/authenticators.html Sat Sep 08 16:02:18 2007 +0000 3.3 @@ -1,9 +1,8 @@ 3.4 +<?xml version="1.0" encoding="iso-8859-1"?> 3.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3.6 <html xmlns="http://www.w3.org/1999/xhtml"> 3.7 <head> 3.8 <title>Application-Wide Authenticators</title> 3.9 - <meta name="generator" 3.10 - 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 <body>
4.1 --- a/docs/cookies.html Sat Sep 08 16:01:41 2007 +0000 4.2 +++ b/docs/cookies.html Sat Sep 08 16:02:18 2007 +0000 4.3 @@ -1,10 +1,9 @@ 4.4 +<?xml version="1.0" encoding="iso-8859-1"?> 4.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 4.6 <html xmlns="http://www.w3.org/1999/xhtml"> 4.7 <head> 4.8 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> 4.9 <title>Cookies</title> 4.10 - <meta name="generator" 4.11 - content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 4.12 <link href="styles.css" rel="stylesheet" type="text/css" /> 4.13 </head> 4.14 <body>
5.1 --- a/docs/deploying-applications.html Sat Sep 08 16:01:41 2007 +0000 5.2 +++ b/docs/deploying-applications.html Sat Sep 08 16:02:18 2007 +0000 5.3 @@ -1,7 +1,7 @@ 5.4 +<?xml version="1.0" encoding="iso-8859-1"?> 5.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 5.6 <html xmlns="http://www.w3.org/1999/xhtml"><head> 5.7 - 5.8 - <title>Deploying an Application</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 5.9 + <title>Deploying an Application</title> 5.10 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 5.11 <body> 5.12 <h1>Deploying an Application</h1> 5.13 @@ -77,4 +77,4 @@ 5.14 <li><a href="WSGI/NOTES.txt">WSGI</a></li> 5.15 <li><a href="Zope/NOTES.txt">Zope 2</a></li> 5.16 </ul> 5.17 -</body></html> 5.18 \ No newline at end of file 5.19 +</body></html>
6.1 --- a/docs/deploying.html Sat Sep 08 16:01:41 2007 +0000 6.2 +++ b/docs/deploying.html Sat Sep 08 16:02:18 2007 +0000 6.3 @@ -1,9 +1,8 @@ 6.4 +<?xml version="1.0" encoding="iso-8859-1"?> 6.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 6.6 <html xmlns="http://www.w3.org/1999/xhtml"><head> 6.7 - 6.8 - <title>Deploying a WebStack Application</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 6.9 + <title>Deploying a WebStack Application</title> 6.10 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 6.11 - 6.12 <body> 6.13 <h1>Deploying a WebStack Application</h1> 6.14 <p>The process of deploying a WebStack application should be as 6.15 @@ -47,4 +46,4 @@ 6.16 <li><a href="pythonpath.html">Getting PYTHONPATH Right</a></li> 6.17 <li><a href="deploying-applications.html">Deploying an Application</a></li> 6.18 </ul> 6.19 -</body></html> 6.20 \ No newline at end of file 6.21 +</body></html>
7.1 --- a/docs/design.html Sat Sep 08 16:01:41 2007 +0000 7.2 +++ b/docs/design.html Sat Sep 08 16:02:18 2007 +0000 7.3 @@ -1,8 +1,8 @@ 7.4 +<?xml version="1.0" encoding="iso-8859-1"?> 7.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 7.6 <html xmlns="http://www.w3.org/1999/xhtml"><head> 7.7 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> 7.8 - 7.9 - <title>Application Design Considerations</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 7.10 + <title>Application Design Considerations</title> 7.11 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 7.12 <body> 7.13 <h1>Application Design Considerations</h1> 7.14 @@ -59,4 +59,4 @@ 7.15 <li><a href="state.html">Cookies, Sessions, Users and Persistent 7.16 Information</a></li> 7.17 </ul> 7.18 -</body></html> 7.19 \ No newline at end of file 7.20 +</body></html>
8.1 --- a/docs/developing.html Sat Sep 08 16:01:41 2007 +0000 8.2 +++ b/docs/developing.html Sat Sep 08 16:02:18 2007 +0000 8.3 @@ -1,85 +1,48 @@ 8.4 +<?xml version="1.0" encoding="iso-8859-1"?> 8.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 8.6 <html xmlns="http://www.w3.org/1999/xhtml"><head> 8.7 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> 8.8 - 8.9 - 8.10 - <title>Developing a WebStack Application</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 8.11 + <title>Developing a WebStack Application</title> 8.12 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 8.13 <body> 8.14 <h1>Developing a WebStack Application</h1> 8.15 <p>Many different topics are involved in the development of WebStack 8.16 applications; below is a map of each of the topics covered in this 8.17 -documentation (with related example material found in the <code>examples/Common</code> directory given beside certain topics):</p> 8.18 +documentation (with related example material found in the <code>examples/Common</code> directory given beside certain topics):</p> 8.19 <ul> 8.20 <li><a href="resources.html">Applications and Resources</a> (<code>VerySimple</code> example)</li> 8.21 <li><a href="resource-creation.html">How Resources are Created</a></li> 8.22 <li><a href="design.html">Application Design Considerations</a></li> 8.23 <ul> 8.24 - 8.25 - 8.26 <li><a href="paths.html">URLs and Paths</a></li><li><a href="path-strategies.html">Path Processing Strategies</a></li> 8.27 <li><a href="path-info.html">Paths To and Within Applications</a></li><li><a href="path-design.html">Path Design and Interpretation</a></li><ul> 8.28 - 8.29 - 8.30 - 8.31 - 8.32 - 8.33 - 8.34 - 8.35 <li><a href="paths-filesystem.html">Treating the Path Like a Filesystem</a> (<code>DemoApp</code> example, <code>Calendar</code> example)</li><li><a href="paths-services.html">Treating the Path Mostly Like a Filesystem</a></li><li><a href="paths-opaque.html">Using the Path as an Opaque Reference into an Application</a></li><ul> 8.36 - 8.37 - 8.38 - 8.39 - 8.40 - 8.41 </ul><li><a href="path-value-encoding.html">Encoding and Decoding Path Values</a></li><li><a href="path-manipulation.html">Manipulating Paths</a></li> 8.42 - 8.43 <li><a href="path-info-support.html">Path Info Support in Server Environments</a></li> 8.44 - 8.45 - 8.46 </ul><li><a href="methods.html">Request Methods</a></li> 8.47 <li><a href="parameters.html">Request Parameters and Uploads</a> (<code>Form</code> example)</li> 8.48 <ul> 8.49 - 8.50 - 8.51 - 8.52 <li><a href="parameters-headers.html">Request Header Parameters</a></li> 8.53 - 8.54 <li><a href="parameters-body.html">Request Body Parameters</a></li> 8.55 - 8.56 - 8.57 - 8.58 </ul><li><a href="headers.html">Request Headers</a></li> 8.59 - 8.60 <li><a href="responses.html">Responses and Presentation</a> (<code>Unicode</code> example)</li><ul><li><a href="redirection.html">Redirection</a></li></ul> 8.61 <li><a href="state.html">Cookies, Sessions, Users and Persistent Information</a></li> 8.62 <ul> 8.63 - 8.64 - 8.65 <li><a href="cookies.html">Cookies</a> (<code>Cookies</code> example)</li> 8.66 <li><a href="sessions.html">Sessions and Persistent Information</a></li> 8.67 <ul> 8.68 - 8.69 - 8.70 - 8.71 <li><a href="sessions-usage.html">Using Sessions</a> (<code>Sessions</code> example)</li> 8.72 - 8.73 <li><a href="sessions-servers.html">Server Environment Support for Sessions</a></li><li>(<a href="directory-repository.html">DirectoryRepository - Simple Access to Files in a Directory</a>)</li> 8.74 - 8.75 - 8.76 - 8.77 </ul><li><a href="users.html">Users and Authentication</a> (<code>Auth</code> example)</li> 8.78 - 8.79 - 8.80 </ul><li><a href="attributes.html">Transaction Attributes</a></li> 8.81 - 8.82 - </ul><li><a href="securing.html">Securing a WebStack Application</a></li><ul><li><a href="authenticators.html">Application-Wide Authenticators</a></li><li><a href="login-redirect.html">LoginRedirect and Login Modules</a> (<code>SimpleWithLogin</code> example, <code>Login</code> example)</li></ul><li><a href="integrating.html">Integrating with Other Systems</a></li> 8.83 -</ul><p>The following topic is referenced in many locations and should 8.84 + </ul><li><a href="securing.html">Securing a WebStack Application</a></li><ul><li><a href="authenticators.html">Application-Wide Authenticators</a></li><li><a href="login-redirect.html">LoginRedirect and Login Modules</a> (<code>SimpleWithLogin</code> example, <code>Login</code> example)</li></ul><li><a href="integrating.html">Integrating with Other Systems</a></li> 8.85 +</ul><p>The following topic is referenced in many locations and should 8.86 be reviewed when encountering problems with input and output text:</p> 8.87 <ul><li><a href="encodings.html">Character Encodings</a></li></ul> 8.88 <h2>Deployment</h2><p>The following topics (illustrated by the programs found in the other subdirectories of the <code>examples</code> directory) describe how WebStack applications may be deployed in server environments:</p><ul><li><a href="supported-frameworks.html">Supported Frameworks</a></li><li><a href="deploying.html">Deploying a WebStack Application</a></li><ul><li><a href="writing-adapters.html">Writing Adapters</a></li><li><a href="pythonpath.html">Getting PYTHONPATH Right</a></li><li><a href="deploying-applications.html">Deploying an Application</a></li><ul><li><a href="BaseHTTPRequestHandler/NOTES.txt">BaseHTTPRequestHandler</a> (see <code>examples/BaseHTTPRequestHandler</code>)</li><li><a href="CGI/NOTES.txt">CGI</a> (see <code>examples/CGI</code>)</li><li><a href="Django/NOTES.txt">Django</a> (see <code>examples/Django</code>)</li><li><a href="JavaServlet/NOTES.txt">Java Servlet</a> (see <code>examples/JavaServlet</code>)</li><li><a href="ModPython/NOTES.txt">mod_python</a> (see <code>examples/ModPython</code>)</li><li><a href="Twisted/NOTES.txt">Twisted</a> (see <code>examples/Twisted</code>)</li><li><a href="Webware/NOTES.txt">Webware</a> (see <code>examples/Webware</code>)</li><li><a href="WSGI/NOTES.txt">WSGI</a> (see <code>examples/WSGI</code>)</li><li><a href="Zope/NOTES.txt">Zope</a> (see <code>examples/Zope</code>)</li></ul></ul><li>Technical note: <a href="features.html">Support for WebStack 8.89 -Features in Server Environments</a></li></ul><h2>Useful Additions</h2><p>WebStack 8.90 +Features in Server Environments</a></li></ul> 8.91 +<h2>Useful Additions</h2><p>WebStack 8.92 provides a number of potentially useful modules either providing 8.93 resource classes for direct use in applications, or providing other 8.94 kinds of classes and functions which may be used to perform particular 8.95 -activities.</p><p>The following resources are provided for direct use in applications:</p><ul><li><a href="login-redirect.html">LoginRedirect and Login Modules</a></li><li><a href="resource-map.html">ResourceMap - Simple Mappings from Names to Resources</a></li><li><a href="directory-resource.html">DirectoryResource - Serving Static Content</a></li><li><a href="file-resource.html">FileResource - Serving Individual Files</a></li><li><a href="selectors.html">Selectors - Components for Dispatching to Resources</a></li></ul><p>WebStack also provides modules which provide session-like access to different kinds of repositories:</p><ul><li><a href="directory-repository.html">DirectoryRepository - Simple Access to Files in a Directory</a></li></ul></body></html> 8.96 \ No newline at end of file 8.97 +activities.</p><p>The following resources are provided for direct use in applications:</p><ul><li><a href="login-redirect.html">LoginRedirect and Login Modules</a></li><li><a href="resource-map.html">ResourceMap - Simple Mappings from Names to Resources</a></li><li><a href="directory-resource.html">DirectoryResource - Serving Static Content</a></li><li><a href="file-resource.html">FileResource - Serving Individual Files</a></li><li><a href="selectors.html">Selectors - Components for Dispatching to Resources</a></li></ul><p>WebStack also provides modules which provide session-like access to different kinds of repositories:</p><ul><li><a href="directory-repository.html">DirectoryRepository - Simple Access to Files in a Directory</a></li></ul></body></html>
9.1 --- a/docs/directory-repository.html Sat Sep 08 16:01:41 2007 +0000 9.2 +++ b/docs/directory-repository.html Sat Sep 08 16:02:18 2007 +0000 9.3 @@ -1,32 +1,32 @@ 9.4 +<?xml version="1.0" encoding="iso-8859-1"?> 9.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 9.6 <html xmlns="http://www.w3.org/1999/xhtml"><head><meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> 9.7 - 9.8 - <title>DirectoryRepository - Simple Access to Files in a Directory</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 9.9 + <title>DirectoryRepository - Simple Access to Files in a Directory</title> 9.10 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 9.11 <body> 9.12 <h1>DirectoryRepository - Simple Access to Files in a Directory</h1> 9.13 -<p>In applications it is often convenient to be able to save or remember information provided or edited by a user. Whilst <a href="sessions.html">sessions</a> 9.14 +<p>In applications it is often convenient to be able to save or remember information provided or edited by a user. Whilst <a href="sessions.html">sessions</a> 9.15 often provide a convenient means of remembering such information, they 9.16 have certain limitations, notably that they are only available to a 9.17 particular user and cannot be shared with other users, and that their 9.18 data is stored in a form that is not necessarily convenient to access 9.19 -by other tools or systems.</p><p>The principle behind the <code>DirectoryRepository</code> 9.20 +by other tools or systems.</p><p>The principle behind the <code>DirectoryRepository</code> 9.21 class is that it stores information as files in a designated directory, 9.22 that such files can be accessed by any resource with access to that 9.23 directory, and that a certain degree of locking is provided to avoid 9.24 -contention between resources. Once created, instances of <code>DirectoryRepository</code> 9.25 +contention between resources. Once created, instances of <code>DirectoryRepository</code> 9.26 can be accessed almost like sessions, although it is possible to obtain 9.27 the full paths to files in the repository and to use file objects and 9.28 -methods to obtain and deposit content in such files.</p><div class="WebStack"><h3>WebStack API - DirectoryRepository Initialisation</h3><p>The <code>DirectoryRepository</code> class (found in the <code>WebStack.Repositories.Directory</code> module) accepts the following parameters when being initialised:</p><dl><dt><code>path</code></dt><dd>This parameter specifies the path to the directory in the filesystem where repository files are to be stored.</dd><dt><code>fsencoding</code></dt><dd>This 9.29 +methods to obtain and deposit content in such files.</p><div class="WebStack"><h3>WebStack API - DirectoryRepository Initialisation</h3><p>The <code>DirectoryRepository</code> class (found in the <code>WebStack.Repositories.Directory</code> module) accepts the following parameters when being initialised:</p><dl><dt><code>path</code></dt><dd>This parameter specifies the path to the directory in the filesystem where repository files are to be stored.</dd><dt><code>fsencoding</code></dt><dd>This 9.30 optional parameter specifies the character encoding employed by the 9.31 filesystem to represent filenames. If left unspecified, the 9.32 implementation will attempt to guess the correct encoding or, where 9.33 supported, to use Unicode filenames.</dd><dt><code>delay</code></dt><dd>This 9.34 optional parameter specifies a delay period for which a program will be 9.35 made to wait if a repository file is found to be locked by another 9.36 -process.</dd></dl></div><h2>Initialisation Strategies</h2><p>One might choose to initialise a repository in the initialisation method of a resource:</p><pre># Inside a module defining a resource...<br /><br />class MyResource:<br /> def __init__(self):<br /> repository_dir = os.path.join(os.path.split(__file__)[0], "repository")<br /> self.repository = DirectoryRepository(repository_dir, "iso-8859-1")</pre><p>Here, the repository will reside alongside the resource's module in the filesystem.</p><h2>Session-like Access</h2><p>One might use a repository with a session-like API as follows:</p><pre># Given a name and some data, possibly provided in user input, store the data in the repository.<br /><br />repository[name] = data </pre><p>Note that <code>DirectoryRepository</code> 9.37 +process.</dd></dl></div><h2>Initialisation Strategies</h2><p>One might choose to initialise a repository in the initialisation method of a resource:</p><pre># Inside a module defining a resource...<br /><br />class MyResource:<br /> def __init__(self):<br /> repository_dir = os.path.join(os.path.split(__file__)[0], "repository")<br /> self.repository = DirectoryRepository(repository_dir, "iso-8859-1")</pre><p>Here, the repository will reside alongside the resource's module in the filesystem.</p><h2>Session-like Access</h2><p>One might use a repository with a session-like API as follows:</p><pre># Given a name and some data, possibly provided in user input, store the data in the repository.<br /><br />repository[name] = data </pre><p>Note that <code>DirectoryRepository</code> 9.38 places some restrictions on the values that can be used as keys in the 9.39 session-like API since each key must correspond to a filename within 9.40 -the designated directory.</p><h2>Advanced Access</h2><p>The <code>DirectoryRepository</code> class also provides various methods to support access to files in the repository using standard file objects and methods:</p><pre># Given a name and some data...<br /><br />edit_path = repository.lock(name)<br />f = open(edit_path, "wb")<br />try:<br /> f.write(data)<br />finally:<br /> f.close()<br /> repository.unlock(name)</pre><p>The usage of <code>try</code> and <code>finally</code> 9.41 +the designated directory.</p><h2>Advanced Access</h2><p>The <code>DirectoryRepository</code> class also provides various methods to support access to files in the repository using standard file objects and methods:</p><pre># Given a name and some data...<br /><br />edit_path = repository.lock(name)<br />f = open(edit_path, "wb")<br />try:<br /> f.write(data)<br />finally:<br /> f.close()<br /> repository.unlock(name)</pre><p>The usage of <code>try</code> and <code>finally</code> 9.42 clauses is important to ensure that files are not left locked and 9.43 -inaccessible due to unhandled exceptions being raised. See the <a href="../apidocs/public/WebStack.Repositories.Directory.DirectoryRepository-class.html">API documentation</a> for the <code>DirectoryRepository</code> class for more information about the available methods and their behaviour.</p></body></html> 9.44 +inaccessible due to unhandled exceptions being raised. See the <a href="../apidocs/public/WebStack.Repositories.Directory.DirectoryRepository-class.html">API documentation</a> for the <code>DirectoryRepository</code> class for more information about the available methods and their behaviour.</p></body></html>
10.1 --- a/docs/directory-resource.html Sat Sep 08 16:01:41 2007 +0000 10.2 +++ b/docs/directory-resource.html Sat Sep 08 16:02:18 2007 +0000 10.3 @@ -1,16 +1,16 @@ 10.4 +<?xml version="1.0" encoding="iso-8859-1"?> 10.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 10.6 <html xmlns="http://www.w3.org/1999/xhtml"><head><meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> 10.7 - 10.8 - <title>DirectoryResource - Serving Static Content</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 10.9 + <title>DirectoryResource - Serving Static Content</title> 10.10 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 10.11 <body> 10.12 <h1>DirectoryResource - Serving Static Content</h1> 10.13 -<p>The <code>DirectoryResource</code> class provides a means to 10.14 +<p>The <code>DirectoryResource</code> class provides a means to 10.15 serve static files from within a particular directory in the 10.16 filesystem. By inspecting the remainder of the path information 10.17 -supplied in an incoming request, instances of <code>DirectoryResource</code> may identify files and serve their contents as a response to such a request.</p><p>There are various situations where providing static content is virtually essential:</p><ul><li>Providing 10.18 +supplied in an incoming request, instances of <code>DirectoryResource</code> may identify files and serve their contents as a response to such a request.</p><p>There are various situations where providing static content is virtually essential:</p><ul><li>Providing 10.19 stylesheets, script files and images employed by Web pages which may 10.20 -themselves have been produced by WebStack resources.</li><li>Providing static documents for Web pages which are not "dynamic".</li></ul><p>By instantiating <code>DirectoryResource</code> classes and deploying them in conjunction with <code>MapResource</code> objects (see the <a href="resource-map.html">"ResourceMap - Simple Mappings from Names to Resources"</a> 10.21 +themselves have been produced by WebStack resources.</li><li>Providing static documents for Web pages which are not "dynamic".</li></ul><p>By instantiating <code>DirectoryResource</code> classes and deploying them in conjunction with <code>MapResource</code> objects (see the <a href="resource-map.html">"ResourceMap - Simple Mappings from Names to Resources"</a> 10.22 document), it should be possible to retain control of the serving of 10.23 static content within a WebStack application. Note, however, that the 10.24 performance of a system can be improved if the job of serving static 10.25 @@ -18,10 +18,10 @@ 10.26 for example, set up an Apache Web server to serve things like 10.27 stylesheets, script files and images, and then link to the locations of 10.28 such things in the Web pages generated by the WebStack application.</p><div class="WebStack"><h3>WebStack API - The DirectoryResource Class</h3> 10.29 -<p>Given a directory from which files shall be served, <code>DirectoryResource</code> uses a simple method to identify files to serve. First, it examines the <a href="path-info.html">virtual "path info"</a> and takes the first component of that information. For example, consider the following path information:</p><pre>/styles.css</pre><p>Here, <code>DirectoryResource</code> identifies the file to be served as having the name <code>styles.css</code>. Note that any trailing path information would be ignored; for example:</p><pre>/styles/abc</pre><p>Here, the file to be served would be identified as having the name <code>styles</code>.</p><h4>Handling Missing Files</h4><p>Where 10.30 -no file exists in the specified directory with the identified 10.31 +<p>Given a directory from which files shall be served, <code>DirectoryResource</code> uses a simple method to identify files to serve. First, it examines the <a href="path-info.html">virtual "path info"</a> and takes the first component of that information. For example, consider the following path information:</p><pre>/styles.css</pre><p>Here, <code>DirectoryResource</code> identifies the file to be served as having the name <code>styles.css</code>. Note that any trailing path information would be ignored; for example:</p><pre>/styles/abc</pre><p>Here, the file to be served would be identified as having the name <code>styles</code>.</p><h4>Handling Missing Files</h4><p>Where 10.32 +no file exists in the specified directory with the identified 10.33 name, a "file not found" response code is set by the resource and a 10.34 -message is emitted. To modify the simple behaviour of <code>DirectoryResource</code> in this regard, it is recommended that a subclass of <code>DirectoryResource</code> is defined with its own implementation of the <code>not_found</code> method.</p><h4>Types of Served Files</h4><p>Given 10.35 +message is emitted. To modify the simple behaviour of <code>DirectoryResource</code> in this regard, it is recommended that a subclass of <code>DirectoryResource</code> is defined with its own implementation of the <code>not_found</code> method.</p><h4>Types of Served Files</h4><p>Given 10.36 that a file exists in the specified directory, it is usually critical 10.37 that the file is served along with special file type information so 10.38 that a user's Web browser may understand the nature of the file's 10.39 @@ -29,11 +29,11 @@ 10.40 a file type indicating that the contents of the file are HTML (or some 10.41 variant thereof). Instances of <code>DirectoryResource</code> employ 10.42 a special registry mapping filename extensions to file types in order 10.43 -to automate the process of deciding what type a file might be.</p><p>Using the <code>content_types</code> parameter (see below), one might choose to serve all files whose names have the <code>.html</code> extension with the HTML file (or content) type. This would be expressed with the following dictionary:</p><pre>{"html" : WebStack.Generic.ContentType("text/html", "utf-8")}</pre><p>Note that the <code>.</code> 10.44 +to automate the process of deciding what type a file might be.</p><p>Using the <code>content_types</code> parameter (see below), one might choose to serve all files whose names have the <code>.html</code> extension with the HTML file (or content) type. This would be expressed with the following dictionary:</p><pre>{"html" : WebStack.Generic.ContentType("text/html", "utf-8")}</pre><p>Note that the <code>.</code> 10.45 character is omitted from the filename extension. Where it is tedious 10.46 to create content type objects and where the same character encoding 10.47 -applies for all types of files, it is possible to use the <code>media_types</code> and <code>default_encoding</code> parameters instead.<br /></p><h4>Further Reading</h4><p>The <a href="../apidocs/public/WebStack.Resources.Static.DirectoryResource-class.html">API documentation</a> for the <code>DirectoryResource</code> class provides more information on the usage of the class.</p><h4>Initialisation</h4><p>The <span style="font-family: monospace;">Directory</span><code>Resource</code> class (found in the <code>WebStack.Resources.Static</code> module) accepts the following parameters when being initialised:</p> 10.48 -<dl><dt><code>directory</code></dt><dd>The directory from which static files shall be served.</dd><dt><code>media_types</code></dt><dd>A dictionary or dictionary-like object mapping filename extensions to media types.</dd><dt><code>unrecognised_media_type</code></dt><dd>An optional parameter setting the media type for files whose extensions do not map to any media type according to the <code>media_types</code> parameter.</dd><dt><code>content_types</code></dt><dd>A dictionary or dictionary-like object mapping filename extensions to content type objects (such as <code>WebStack.Generic.ContentType</code>).</dd><dt><code>unrecognised_content_type</code></dt><dd>An optional parameter setting the content type for files whose extensions do not map to any content type according to the <code>content_types</code> parameter.</dd><dt><code>default_encoding</code></dt><dd>An optional parameter setting the character encoding for all media types defined in the <code>media_types</code> and <code>unrecognised_media_type</code> parameters. If not specified, no character encoding will be stated for content associated with such media types.</dd><dt><code>urlencoding</code></dt><dd>When 10.49 +applies for all types of files, it is possible to use the <code>media_types</code> and <code>default_encoding</code> parameters instead.<br /></p><h4>Further Reading</h4><p>The <a href="../apidocs/public/WebStack.Resources.Static.DirectoryResource-class.html">API documentation</a> for the <code>DirectoryResource</code> class provides more information on the usage of the class.</p><h4>Initialisation</h4><p>The <span style="font-family: monospace;">Directory</span><code>Resource</code> class (found in the <code>WebStack.Resources.Static</code> module) accepts the following parameters when being initialised:</p> 10.50 +<dl><dt><code>directory</code></dt><dd>The directory from which static files shall be served.</dd><dt><code>media_types</code></dt><dd>A dictionary or dictionary-like object mapping filename extensions to media types.</dd><dt><code>unrecognised_media_type</code></dt><dd>An optional parameter setting the media type for files whose extensions do not map to any media type according to the <code>media_types</code> parameter.</dd><dt><code>content_types</code></dt><dd>A dictionary or dictionary-like object mapping filename extensions to content type objects (such as <code>WebStack.Generic.ContentType</code>).</dd><dt><code>unrecognised_content_type</code></dt><dd>An optional parameter setting the content type for files whose extensions do not map to any content type according to the <code>content_types</code> parameter.</dd><dt><code>default_encoding</code></dt><dd>An optional parameter setting the character encoding for all media types defined in the <code>media_types</code> and <code>unrecognised_media_type</code> parameters. If not specified, no character encoding will be stated for content associated with such media types.</dd><dt><code>urlencoding</code></dt><dd>When 10.51 specified, this parameter forces a particular interpretation of "URL 10.52 encoded" character values in the path. Otherwise, the default encoding 10.53 -is employed to interpret such values. (See <a href="paths.html">"URLs and Paths"</a> for an explanation of "URL encoded" values.)</dd></dl></div><h2>Combining MapResource with DirectoryResource</h2><p>One might combine <code>MapResource</code> with <code>DirectoryResource</code> to provide stylesheet and script file directories for an application as follows:</p><pre>from WebStack.Resources.ResourceMap import MapResource<br />from WebStack.Resources.Static import DirectoryResource<br /><br /># This is where the application's resources would be obtained.<br /><br />app_resource = ...<br /><br /># Here is where we combine MapResource and DirectoryResource.<br /># Note that one would not necessarily hard-code directory paths into the application.<br /><br />top_resource = MapResource({<br /> "styles" : DirectoryResource("/usr/share/apps/MyApp/styles", media_types={"css" : "text/css"}),<br /> "scripts" : DirectoryResource("/usr/share/apps/MyApp/scripts", media_types={"js" : "text/javascript"}),<br /> "" : app_resource<br /> })</pre><p>In the above example, any file in the <code>styles</code> directory whose name ends with <code>.css</code> is served as <code>text/css</code>. Similarly, any file in the <code>scripts</code> directory whose name ends with <code>.js</code> is served as <code>text/javascript</code>.</p></body></html> 10.54 \ No newline at end of file 10.55 +is employed to interpret such values. (See <a href="paths.html">"URLs and Paths"</a> for an explanation of "URL encoded" values.)</dd></dl></div><h2>Combining MapResource with DirectoryResource</h2><p>One might combine <code>MapResource</code> with <code>DirectoryResource</code> to provide stylesheet and script file directories for an application as follows:</p><pre>from WebStack.Resources.ResourceMap import MapResource<br />from WebStack.Resources.Static import DirectoryResource<br /><br /># This is where the application's resources would be obtained.<br /><br />app_resource = ...<br /><br /># Here is where we combine MapResource and DirectoryResource.<br /># Note that one would not necessarily hard-code directory paths into the application.<br /><br />top_resource = MapResource({<br /> "styles" : DirectoryResource("/usr/share/apps/MyApp/styles", media_types={"css" : "text/css"}),<br /> "scripts" : DirectoryResource("/usr/share/apps/MyApp/scripts", media_types={"js" : "text/javascript"}),<br /> "" : app_resource<br /> })</pre><p>In the above example, any file in the <code>styles</code> directory whose name ends with <code>.css</code> is served as <code>text/css</code>. Similarly, any file in the <code>scripts</code> directory whose name ends with <code>.js</code> is served as <code>text/javascript</code>.</p></body></html>
11.1 --- a/docs/encodings.html Sat Sep 08 16:01:41 2007 +0000 11.2 +++ b/docs/encodings.html Sat Sep 08 16:02:18 2007 +0000 11.3 @@ -1,7 +1,7 @@ 11.4 +<?xml version="1.0" encoding="iso-8859-1"?> 11.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 11.6 <html xmlns="http://www.w3.org/1999/xhtml"><head> 11.7 - 11.8 - <title>Character Encodings</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 11.9 + <title>Character Encodings</title> 11.10 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 11.11 <body> 11.12 <h1>Character Encodings</h1> 11.13 @@ -19,16 +19,16 @@ 11.14 users of your application, the text will be in some kind of character 11.15 encoding. For example, in English-speaking environments, the US-ASCII 11.16 encoding is common and contains the basic letters, numbers and symbols 11.17 -used in English, whereas in Western Europe encodings like 11.18 -ISO-8859-1 and ISO-8859-15 are typically used, since they contain 11.19 +used in English, whereas in Western Europe encodings like 11.20 +ISO-8859-1 and ISO-8859-15 are typically used, since they contain 11.21 additional letters and symbols in order to support other languages. 11.22 Often, UTF-8 is used to encode text because it covers most languages 11.23 simultaneously and is therefore flexible enough for many applications.</p> 11.24 <p>When URLs are received in applications, in order for some of the 11.25 request parameters to be interpreted, the situation is a bit more 11.26 awkward. The original text is encoded in US-ASCII but will contain 11.27 -special numeric codes that indicate character values in the 11.28 -original text encoding - see the <a href="parameters.html">description 11.29 +special numeric codes that indicate character values in the 11.30 +original text encoding - see the <a href="parameters.html">description 11.31 of query strings</a> for more information.</p> 11.32 <h2>Recommendations</h2> 11.33 <dl> 11.34 @@ -47,7 +47,7 @@ 11.35 <li>If you must include hard-coded messages in your application code, 11.36 make sure to specify the encoding using the <a href="http://www.python.org/peps/pep-0263.html">standard declaration</a> 11.37 at the top of your source file.</li> 11.38 - <li>Remember that the standard library <code>codecs</code> 11.39 + <li>Remember that the standard library <code>codecs</code> 11.40 module contains useful functions to access streams as if Unicode 11.41 objects were being transmitted; for example:</li> 11.42 </ul> 11.43 @@ -73,14 +73,14 @@ 11.44 can be used directly with various transaction methods. Here is an 11.45 outline of code which does this:</p> 11.46 <pre>from WebStack.Generic import ContentType<br /><br />class MyResource:<br /><br /> encoding = "utf-8" # We decide on "utf-8" as our chosen<br /> # encoding.<br /> def respond(self, trans):<br /> [Do various things.]<br /><br /> fields = trans.get_fields_from_body(encoding=self.encoding) # Explicitly use the encoding.<br /><br /> [Do other things with the Unicode values from the fields.]<br /><br /> trans.set_content_type(ContentType("text/html", self.encoding)) # The output Web page uses the encoding.<br /><br /> [Produce the response, making sure that self.encoding is used to convert Unicode to raw strings.]</pre> 11.47 -<h3>Use EncodingSelector to Set the Default Encoding</h3><p>An arguably better approach is to use selectors (as described in <a href="selectors.html">"Selectors - Components for Dispatching to Resources"</a>), typically in a "site map" arrangement (as described in <a href="deploying.html">"Deploying a WebStack Application"</a>), specifically using the <code>EncodingSelector</code>:</p><pre>from WebStack.Generic import ContentType<br /><br />class MyResource:<br /><br /> def respond(self, trans):<br /> [Do various things.]<br /><br /> fields = trans.get_fields_from_body() # Encoding set by EncodingSelector.<br /><br /> [Do other things with the Unicode values from the fields.]<br /><br /> trans.set_content_type(ContentType("text/html")) # The output Web page uses the default encoding.<br /><br /> [Produce the response, making sure that self.encoding is used to convert Unicode to raw strings.]<br /><br />def get_site_map():<br /><br /> return EncodingSelector(MyResource(), "utf-8")</pre><h3>Tell Encodings to Other Components</h3> 11.48 +<h3>Use EncodingSelector to Set the Default Encoding</h3><p>An arguably better approach is to use selectors (as described in <a href="selectors.html">"Selectors - Components for Dispatching to Resources"</a>), typically in a "site map" arrangement (as described in <a href="deploying.html">"Deploying a WebStack Application"</a>), specifically using the <code>EncodingSelector</code>:</p><pre>from WebStack.Generic import ContentType<br /><br />class MyResource:<br /><br /> def respond(self, trans):<br /> [Do various things.]<br /><br /> fields = trans.get_fields_from_body() # Encoding set by EncodingSelector.<br /><br /> [Do other things with the Unicode values from the fields.]<br /><br /> trans.set_content_type(ContentType("text/html")) # The output Web page uses the default encoding.<br /><br /> [Produce the response, making sure that self.encoding is used to convert Unicode to raw strings.]<br /><br />def get_site_map():<br /><br /> return EncodingSelector(MyResource(), "utf-8")</pre><h3>Tell Encodings to Other Components</h3> 11.49 <p>When using other components to generate content (see <a href="integrating.html">"Integrating with Other Systems"</a>), it may 11.50 be the case that such components will just write the generated content 11.51 -straight to a normal stream (rather than one wrapped by a <code>codecs</code> 11.52 +straight to a normal stream (rather than one wrapped by a <code>codecs</code> 11.53 module function). In such cases, it is likely that for textual content 11.54 such as XML or related formats (XHTML, SVG, HTML) you will need to 11.55 instruct the component to use your chosen encoding; for example:</p> 11.56 <pre> # In the respond method, xml_document is an xml.dom.minidom.Document object...<br /> xml_document.toxml(self.encoding)</pre> 11.57 <p>This will then generate the appropriate characters in the output <span style="font-style: italic;">and</span> specify the correct encoding 11.58 for the XML document.</p> 11.59 -</body></html> 11.60 \ No newline at end of file 11.61 +</body></html>
12.1 --- a/docs/features.html Sat Sep 08 16:01:41 2007 +0000 12.2 +++ b/docs/features.html Sat Sep 08 16:02:18 2007 +0000 12.3 @@ -1,12 +1,11 @@ 12.4 +<?xml version="1.0" encoding="iso-8859-1"?> 12.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 12.6 <html xmlns="http://www.w3.org/1999/xhtml"><head> 12.7 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> 12.8 - 12.9 - <title>Support for WebStack Features in Server Environments</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 12.10 + <title>Support for WebStack Features in Server Environments</title> 12.11 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 12.12 - 12.13 <body> 12.14 -<h1>Support for WebStack Features in Server Environments</h1> 12.15 +<h1>Support for WebStack Features in Server Environments</h1> 12.16 <p>Some basic features of Web applications are not supported by all 12.17 server environments or frameworks. The table below summarises the 12.18 implementation details of such features when applications are deployed 12.19 @@ -68,4 +67,4 @@ 12.20 on certain frameworks.</li> 12.21 <li>Some mod_python releases do not provide session support directly.</li> 12.22 </ol> 12.23 -</body></html> 12.24 \ No newline at end of file 12.25 +</body></html>
13.1 --- a/docs/file-resource.html Sat Sep 08 16:01:41 2007 +0000 13.2 +++ b/docs/file-resource.html Sat Sep 08 16:02:18 2007 +0000 13.3 @@ -1,15 +1,16 @@ 13.4 +<?xml version="1.0" encoding="iso-8859-1"?> 13.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 13.6 -<html xmlns="http://www.w3.org/1999/xhtml"><head><meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> 13.7 - 13.8 - <title>DirectoryResource - Serving Static Content</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 13.9 +<html xmlns="http://www.w3.org/1999/xhtml"><head> 13.10 + <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> 13.11 + <title>DirectoryResource - Serving Static Content</title> 13.12 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 13.13 <body> 13.14 <h1>FileResource - Serving Individual Files</h1> 13.15 -<p>The <code>FileResource</code> class provides a means to 13.16 -serve individual static files from the 13.17 +<p>The <code>FileResource</code> class provides a means to 13.18 +serve individual static files from the 13.19 filesystem. Although a <a href="directory-resource.html"><code>DirectoryResource</code></a> 13.20 object may serve files having specific filename extensions as 13.21 particular types from a filesystem directory, we sometimes need to 13.22 -select individual files from special locations and serve their 13.23 -contents as part of a response.</p><div class="WebStack"><h3>WebStack API - FileResource Initialisation</h3><p>The <span style="font-family: monospace;">File</span><code>Resource</code> class (found in the <code>WebStack.Resources.Static</code> module) accepts the following parameters when being initialised:</p> 13.24 -<dl><dt><code>filename</code></dt><dd>The full path to the particular static file being served.</dd><dt><code>content_type</code></dt><dd>A content type object (such as <code>WebStack.Generic.ContentType</code>) providing sufficient information for user agents to interpret the file's contents.</dd></dl></div><h2>Combining MapResource with FileResource</h2><p>One might combine <code>MapResource</code> with <code>FileResource</code> to provide a <code>favicon.ico</code> image for an application as follows:</p><pre>from WebStack.Resources.ResourceMap import MapResource<br />from WebStack.Resources.Static import FileResource<br /><br /># This is where the application's resources would be obtained.<br /><br />app_resource = ...<br /><br /># Here is where we combine MapResource and FileResource.<br /># Note that one would not necessarily hard-code directory paths into the application.<br /><br />top_resource = MapResource({<br /> "favicon.ico" : FileResource("/usr/share/apps/MyApp/images/py.ico"), ContentType("image/x-icon")),<br /> "" : app_resource<br /> })</pre><p>In the above example, the <code>favicon.ico</code> file in the <code>images</code> directory is served as <code>image/x-icon</code>.</p></body></html> 13.25 \ No newline at end of file 13.26 +select individual files from special locations and serve their 13.27 +contents as part of a response.</p><div class="WebStack"><h3>WebStack API - FileResource Initialisation</h3><p>The <span style="font-family: monospace;">File</span><code>Resource</code> class (found in the <code>WebStack.Resources.Static</code> module) accepts the following parameters when being initialised:</p> 13.28 +<dl><dt><code>filename</code></dt><dd>The full path to the particular static file being served.</dd><dt><code>content_type</code></dt><dd>A content type object (such as <code>WebStack.Generic.ContentType</code>) providing sufficient information for user agents to interpret the file's contents.</dd></dl></div><h2>Combining MapResource with FileResource</h2><p>One might combine <code>MapResource</code> with <code>FileResource</code> to provide a <code>favicon.ico</code> image for an application as follows:</p><pre>from WebStack.Resources.ResourceMap import MapResource<br />from WebStack.Resources.Static import FileResource<br /><br /># This is where the application's resources would be obtained.<br /><br />app_resource = ...<br /><br /># Here is where we combine MapResource and FileResource.<br /># Note that one would not necessarily hard-code directory paths into the application.<br /><br />top_resource = MapResource({<br /> "favicon.ico" : FileResource("/usr/share/apps/MyApp/images/py.ico"), ContentType("image/x-icon")),<br /> "" : app_resource<br /> })</pre><p>In the above example, the <code>favicon.ico</code> file in the <code>images</code> directory is served as <code>image/x-icon</code>.</p></body></html>
14.1 --- a/docs/headers.html Sat Sep 08 16:01:41 2007 +0000 14.2 +++ b/docs/headers.html Sat Sep 08 16:02:18 2007 +0000 14.3 @@ -1,21 +1,19 @@ 14.4 +<?xml version="1.0" encoding="iso-8859-1"?> 14.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 14.6 <html xmlns="http://www.w3.org/1999/xhtml"><head> 14.7 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> 14.8 - 14.9 - 14.10 - <title>Request Headers</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 14.11 + <title>Request Headers</title> 14.12 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 14.13 <body> 14.14 <h1>Request Headers</h1> 14.15 14.16 - 14.17 <p>Request headers are pieces of information that describe certain aspects of a request, such as:</p> 14.18 <ul> 14.19 <li>The location to which the request is being sent.</li> 14.20 <li>The type of information in the request body.</li> 14.21 <li>Preferences about which kinds of information the sender would like to receive in return.</li> 14.22 </ul> 14.23 -<p>The location and related query information is conveniently accessible through <a href="paths.html">path</a> information and <a href="parameters-headers.html">request header parameter</a> information. Other types of header information are made available through other WebStack API methods.</p> 14.24 +<p>The location and related query information is conveniently accessible through <a href="paths.html">path</a> information and <a href="parameters-headers.html">request header parameter</a> information. Other types of header information are made available through other WebStack API methods.</p> 14.25 <h2>Content Types</h2> 14.26 <p>When a Web application sends some information in a response, it 14.27 describes the content type of that information, and this is described 14.28 @@ -28,7 +26,7 @@ 14.29 14.30 <p>Unfortunately, such information is not always provided by Web browsers.</p> 14.31 <h2>Content Preferences</h2> 14.32 -<p>Sometimes, Web browsers describe the kinds of information that 14.33 +<p>Sometimes, Web browsers describe the kinds of information that 14.34 they are willing to receive, and WebStack provides various means to 14.35 query such preferences:</p> 14.36 14.37 @@ -52,7 +50,7 @@ 14.38 </dd> 14.39 <dt><code>get_header_values</code></dt> 14.40 <dd>Given a header name as parameter, this method returns a list of string values associated with that name.</dd><dt><code>get_content_type</code></dt> 14.41 - <dd>This returns a content type object (typically <code>WebStack.Generic.ContentType</code>) describing the incoming request body content.</dd> 14.42 + <dd>This returns a content type object (typically <code>WebStack.Generic.ContentType</code>) describing the incoming request body content.</dd> 14.43 <dt><code>get_content_languages</code></dt> 14.44 <dd>This returns a list of language identifiers, in descending order 14.45 of preference, indicating in which languages the sender of the request 14.46 @@ -63,8 +61,8 @@ 14.47 the request would prefer to receive information.</dd> 14.48 14.49 </dl> 14.50 -<p>It should be noted that the <code>get_headers</code> and <code>get_header_values</code> methods 14.51 +<p>It should be noted that the <code>get_headers</code> and <code>get_header_values</code> methods 14.52 present a slightly different view of the available header information, 14.53 -in that only a single header value is made available through the <code>get_headers</code> method for each header name, whereas <code>get_header_values</code> provides potentially many values for the same header name. </p> 14.54 +in that only a single header value is made available through the <code>get_headers</code> method for each header name, whereas <code>get_header_values</code> provides potentially many values for the same header name. </p> 14.55 14.56 -</div></body></html> 14.57 \ No newline at end of file 14.58 +</div></body></html>
15.1 --- a/docs/index.html Sat Sep 08 16:01:41 2007 +0000 15.2 +++ b/docs/index.html Sat Sep 08 16:02:18 2007 +0000 15.3 @@ -1,7 +1,7 @@ 15.4 +<?xml version="1.0" encoding="iso-8859-1"?> 15.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 15.6 <html xmlns="http://www.w3.org/1999/xhtml"><head> 15.7 - 15.8 - <title>Creating Web Applications with WebStack</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 15.9 + <title>Creating Web Applications with WebStack</title> 15.10 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 15.11 <body> 15.12 <h1>Creating Web Applications with WebStack</h1> 15.13 @@ -29,11 +29,11 @@ 15.14 you may wish to investigate the other supported frameworks in order to 15.15 run WebStack applications in other environments.</p><ul><li><a href="supported-frameworks.html">Supported Frameworks</a></li></ul><h2>Viewing the API Documentation</h2> 15.16 <p>The API documentation for use in conjunction with this 15.17 -guide can be found inside the <a href="../apidocs/index.html"><code>apidocs</code></a> 15.18 +guide can be found inside the <a href="../apidocs/index.html"><code>apidocs</code></a> 15.19 directory within the <code>WebStack-1.2.5</code> directory. Of course, 15.20 it is always possible to view WebStack's API documentation 15.21 -within Python by importing modules (such as <a href="../apidocs/public/WebStack.Generic-module.html"><code>WebStack.Generic</code></a>) 15.22 -and using Python's built-in <code>help</code> function.</p> 15.23 +within Python by importing modules (such as <a href="../apidocs/public/WebStack.Generic-module.html"><code>WebStack.Generic</code></a>) 15.24 +and using Python's built-in <code>help</code> function.</p> 15.25 <h2>About WebStack Applications</h2> 15.26 <ul> 15.27 <li><a href="anatomy.html">Anatomy of a WebStack Application</a></li><li><a href="developing.html">Developing a WebStack Application</a></li></ul>
16.1 --- a/docs/integrating.html Sat Sep 08 16:01:41 2007 +0000 16.2 +++ b/docs/integrating.html Sat Sep 08 16:02:18 2007 +0000 16.3 @@ -1,19 +1,18 @@ 16.4 +<?xml version="1.0" encoding="iso-8859-1"?> 16.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 16.6 <html xmlns="http://www.w3.org/1999/xhtml"> 16.7 <head> 16.8 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> 16.9 <title>Integrating with Other Systems</title> 16.10 - <meta name="generator" 16.11 - content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 16.12 <link href="styles.css" rel="stylesheet" type="text/css" /> 16.13 </head> 16.14 <body> 16.15 <h1>Integrating with Other Systems</h1> 16.16 <p>Most Web applications are not self-contained - instead of 16.17 -providing information which is written into the application 16.18 -code itself, they may often access data from other places or even 16.19 +providing information which is written into the application 16.20 +code itself, they may often access data from other places or even 16.21 communicate with other systems. Since applications may be very 16.22 -different in the way that they access external systems or the way 16.23 +different in the way that they access external systems or the way 16.24 in which they obtain external information, WebStack does not mandate 16.25 rigid mechanisms for hooking into such systems or loading such 16.26 information. Instead, it is recommended that applications import 16.27 @@ -51,7 +50,7 @@ 16.28 the above code is itself imported into Python.</td> 16.29 </tr> 16.30 <tr> 16.31 - <td align="undefined" valign="undefined">Use the <code>urlopen</code> 16.32 + <td align="undefined" valign="undefined">Use the <code>urlopen</code> 16.33 function of <code>urllib</code> to actually access a remote service.</td> 16.34 <td align="undefined" valign="undefined">This happens in the 16.35 resource code each time the resource decides to access the service.</td> 16.36 @@ -100,20 +99,20 @@ 16.37 control of the application - some database systems limit the number of 16.38 connections, for example, and if a large number of resources suddenly 16.39 became active, some of them would fail to obtain connections if the 16.40 -connection initialisation code were in the <code>respond</code> 16.41 +connection initialisation code were in the <code>respond</code> 16.42 method of the resource.</p> 16.43 <h2>Configuring Packages Globally</h2> 16.44 <p>Of course, the above resource might not be the only resource to use 16.45 database connections. It might then be tempting to initialise a 16.46 connection for each module whose resource needs (or, since as normal 16.47 Python classes we can put many resources in a single module, whose 16.48 -resources need) to access a database. But it would surely be more 16.49 +resources need) to access a database. But it would surely be more 16.50 convenient to define a single, central place to hold such global 16.51 resources.</p> 16.52 <p>One approach is to define a module which can be accessed by all 16.53 modules, and thus by all resources. Let us create such a module in the 16.54 file <code>Properties.py</code> which will reside alongside <code>MyApplication.py</code> 16.55 -(or whatever the application module is called). Inside the <code>Properties</code> 16.56 +(or whatever the application module is called). Inside the <code>Properties</code> 16.57 module we can write the following code:</p> 16.58 <pre>import mydb<br /><br />connection = mydb.connect("me", "myPassword")</pre> 16.59 <p>Now, in each module containing resources which need to access the
17.1 --- a/docs/login-redirect.html Sat Sep 08 16:01:41 2007 +0000 17.2 +++ b/docs/login-redirect.html Sat Sep 08 16:02:18 2007 +0000 17.3 @@ -1,7 +1,7 @@ 17.4 +<?xml version="1.0" encoding="iso-8859-1"?> 17.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 17.6 <html xmlns="http://www.w3.org/1999/xhtml"><head> 17.7 - 17.8 - <title>LoginRedirect and Login Modules</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 17.9 + <title>LoginRedirect and Login Modules</title> 17.10 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 17.11 <body> 17.12 <h1>LoginRedirect and Login Modules</h1> 17.13 @@ -104,7 +104,7 @@ 17.14 optional parameter indicating the character encoding used to generate 17.15 (and, in other places, to interpret) URL-encoded character values in 17.16 URLs and paths.</dd> 17.17 -</dl><p>See the <a href="../apidocs/public/WebStack.Resources.LoginRedirect.LoginRedirectResource-class.html">API documentation</a> for the <code>LoginRedirectResource</code> class for more details.</p> 17.18 +</dl><p>See the <a href="../apidocs/public/WebStack.Resources.LoginRedirect.LoginRedirectResource-class.html">API documentation</a> for the <code>LoginRedirectResource</code> class for more details.</p> 17.19 </div> 17.20 <h3>Redirection from/to the Application</h3> 17.21 <p>Some server/framework environments do not permit automatic 17.22 @@ -126,11 +126,11 @@ 17.23 support the "single sign-on" aspects of this mechanism - mixing in such 17.24 classes with <code>LoginAuthenticator</code> may provide a solution to 17.25 this 17.26 -issue, however.</p><h2>Extending LoginRedirectResource</h2><p>Sometimes, using <code>LoginRedirectResource</code> directly is not appropriate in an application. For example, specifying the <code>app_url</code> and <code>login_url</code> as absolute URLs (so that <code>LoginRedirectResource</code> can 17.27 +issue, however.</p><h2>Extending LoginRedirectResource</h2><p>Sometimes, using <code>LoginRedirectResource</code> directly is not appropriate in an application. For example, specifying the <code>app_url</code> and <code>login_url</code> as absolute URLs (so that <code>LoginRedirectResource</code> can 17.28 redirect users into the application and over to the login screen) may 17.29 seem like excessive detail which will need to be changed if the 17.30 application is deployed even in a slightly different location. We might 17.31 -therefore wish to use a <code>PathSelector</code> resource (see <a href="attributes.html">"Transaction Attributes"</a> and <a href="selectors.html">"Selectors"</a>) to record the "root path" into an application and then to employ a login URL which is relative to the "root path".</p><p>To achieve this, <code>LoginRedirectResource</code> provides methods which can be overridden - <code>get_app_url</code> and <code>get_login_url</code> - and we might define a subclass of <code>LoginRedirectResource</code> as follows:</p><pre>class MyLoginRedirectResource(LoginRedirectResource):<br /><br /> "An example of customising LoginRedirectResource."<br /><br /> def get_login_url(self, trans):<br /><br /> "Use a different login URL, using 'trans' to find out what it might be."<br /><br /> # Find out what the PathSelector stored for the root of the application.<br /><br /> root_path = trans.get_attributes()["root"]<br /><br /> # Return the value of the login_url attribute appended to the root path.<br /><br /> return root_path + self.login_url</pre><p>Since <code>LoginRedirectResource</code> calls the <code>get_login_url</code> method when forming the URL to redirect to the login resource, by overriding the original method from the <code>LoginRedirectResource</code> class we can define different behaviour. Of course, to take advantage of this new behaviour, we must instantiate <code>MyLoginRedirectResource</code> instead of <code>LoginRedirectResource</code> when setting up the application.</p> 17.32 +therefore wish to use a <code>PathSelector</code> resource (see <a href="attributes.html">"Transaction Attributes"</a> and <a href="selectors.html">"Selectors"</a>) to record the "root path" into an application and then to employ a login URL which is relative to the "root path".</p><p>To achieve this, <code>LoginRedirectResource</code> provides methods which can be overridden - <code>get_app_url</code> and <code>get_login_url</code> - and we might define a subclass of <code>LoginRedirectResource</code> as follows:</p><pre>class MyLoginRedirectResource(LoginRedirectResource):<br /><br /> "An example of customising LoginRedirectResource."<br /><br /> def get_login_url(self, trans):<br /><br /> "Use a different login URL, using 'trans' to find out what it might be."<br /><br /> # Find out what the PathSelector stored for the root of the application.<br /><br /> root_path = trans.get_attributes()["root"]<br /><br /> # Return the value of the login_url attribute appended to the root path.<br /><br /> return root_path + self.login_url</pre><p>Since <code>LoginRedirectResource</code> calls the <code>get_login_url</code> method when forming the URL to redirect to the login resource, by overriding the original method from the <code>LoginRedirectResource</code> class we can define different behaviour. Of course, to take advantage of this new behaviour, we must instantiate <code>MyLoginRedirectResource</code> instead of <code>LoginRedirectResource</code> when setting up the application.</p> 17.33 <h2>Deploying a Login Application</h2> 17.34 <p>In order for this authentication mechanism to function in its 17.35 entirety, a 17.36 @@ -198,4 +198,4 @@ 17.37 out. A 17.38 special logout confirmation URL may also be configured (see 17.39 <code>logout_url</code> and <code>use_logout_redirect</code> above).</p> 17.40 -</body></html> 17.41 \ No newline at end of file 17.42 +</body></html>
18.1 --- a/docs/methods.html Sat Sep 08 16:01:41 2007 +0000 18.2 +++ b/docs/methods.html Sat Sep 08 16:02:18 2007 +0000 18.3 @@ -1,10 +1,8 @@ 18.4 +<?xml version="1.0" encoding="iso-8859-1"?> 18.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 18.6 <html xmlns="http://www.w3.org/1999/xhtml"><head> 18.7 - 18.8 - <title>Request Methods</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 18.9 + <title>Request Methods</title> 18.10 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 18.11 - 18.12 - 18.13 <body> 18.14 <h1>Request Methods</h1> 18.15 18.16 @@ -84,4 +82,4 @@ 18.17 <code>trans</code> as follows:</p> 18.18 <pre>trans.set_response_code(405)</pre> 18.19 </div> 18.20 -</body></html> 18.21 \ No newline at end of file 18.22 +</body></html>
19.1 --- a/docs/parameters-body.html Sat Sep 08 16:01:41 2007 +0000 19.2 +++ b/docs/parameters-body.html Sat Sep 08 16:02:18 2007 +0000 19.3 @@ -1,7 +1,7 @@ 19.4 +<?xml version="1.0" encoding="iso-8859-1"?> 19.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 19.6 <html xmlns="http://www.w3.org/1999/xhtml"><head> 19.7 - 19.8 - <title>Request Body Parameters</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 19.9 + <title>Request Body Parameters</title> 19.10 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 19.11 <body> 19.12 <h1>Request Body Parameters</h1> 19.13 @@ -53,14 +53,14 @@ 19.14 <p>One way request body parameters may be used is to provide a mechanism for 19.15 the uploading of entire files from browsers and other Web clients to 19.16 applications. Unlike other parameters, those which carry file upload data 19.17 -expose the contents of such uploaded files as <a href="../apidocs/public/WebStack.Helpers.Request.FileContent-class.html"><code>FileContent</code></a> objects 19.18 +expose the contents of such uploaded files as <a href="../apidocs/public/WebStack.Helpers.Request.FileContent-class.html"><code>FileContent</code></a> objects 19.19 instead of Unicode objects.</p> 19.20 <h3>Unsupported Environments and Framework Issues</h3> 19.21 <ul> 19.22 - <li>Twisted does not provide file upload data as <a href="../apidocs/public/WebStack.Helpers.Request.FileContent-class.html"><code>FileContent</code></a> objects; 19.23 + <li>Twisted does not provide file upload data as <a href="../apidocs/public/WebStack.Helpers.Request.FileContent-class.html"><code>FileContent</code></a> objects; 19.24 instead, file upload data will be decoded and returned as Unicode from 19.25 WebStack. This behaviour is due to the way Twisted processes the 19.26 incoming request and may be fixed in a future release.</li> 19.27 </ul> 19.28 19.29 -</body></html> 19.30 \ No newline at end of file 19.31 +</body></html>
20.1 --- a/docs/parameters-headers.html Sat Sep 08 16:01:41 2007 +0000 20.2 +++ b/docs/parameters-headers.html Sat Sep 08 16:02:18 2007 +0000 20.3 @@ -1,12 +1,11 @@ 20.4 +<?xml version="1.0" encoding="iso-8859-1"?> 20.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 20.6 <html xmlns="http://www.w3.org/1999/xhtml"><head> 20.7 - 20.8 - <title>Request Header Parameters</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 20.9 + <title>Request Header Parameters</title> 20.10 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 20.11 <body> 20.12 <h1>Request Header Parameters</h1> 20.13 20.14 - 20.15 <p>Header parameters are typically specified in the URL like this:</p> 20.16 <pre>http://www.boddie.org.uk/application?param1=value1&param2=value2</pre> 20.17 20.18 @@ -39,7 +38,7 @@ 20.19 <dd>This returns the request parameters (fields) from the request headers 20.20 (as defined in the path or URL). The fields are provided in a 20.21 dictionary mapping field names to lists of values<br /> 20.22 -An optional <code>encoding</code> parameter may be used to assist 20.23 +An optional <code>encoding</code> parameter may be used to assist 20.24 the process of converting parameter values to Unicode objects - see 20.25 below for a discussion of the issues with this parameter.</dd> 20.26 <dt><code>get_query_string</code></dt> 20.27 @@ -61,4 +60,4 @@ 20.28 </li> 20.29 20.30 </ul> 20.31 -</body></html> 20.32 \ No newline at end of file 20.33 +</body></html>
21.1 --- a/docs/parameters.html Sat Sep 08 16:01:41 2007 +0000 21.2 +++ b/docs/parameters.html Sat Sep 08 16:02:18 2007 +0000 21.3 @@ -1,7 +1,7 @@ 21.4 +<?xml version="1.0" encoding="iso-8859-1"?> 21.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 21.6 <html xmlns="http://www.w3.org/1999/xhtml"><head> 21.7 - 21.8 - <title>Request Parameters and Uploads</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 21.9 + <title>Request Parameters and Uploads</title> 21.10 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 21.11 <body> 21.12 <h1>Request Parameters and Uploads</h1> 21.13 @@ -29,7 +29,7 @@ 21.14 <ul> 21.15 <li><a href="parameters-headers.html">Request header parameters</a> - parameters specified in the URL as a 21.16 "query string".</li> 21.17 - <li><a href="parameters-body.html">Request body parameters</a> - parameters are found in the request body when the POST <a href="methods.html">request method</a> 21.18 + <li><a href="parameters-body.html">Request body parameters</a> - parameters are found in the request body when the POST <a href="methods.html">request method</a> 21.19 is used.</li> 21.20 </ul> 21.21 <p>One useful application of parameters transferred in request bodies 21.22 @@ -56,9 +56,9 @@ 21.23 <dt><code>get_query_string</code></dt> 21.24 <dd>This method returns the part of the URL which contains parameter 21.25 information. Such information will be "URL-encoded", meaning that 21.26 -certain characters will have the form <code>%xx</code> where <code>xx</code> 21.27 +certain characters will have the form <code>%xx</code> where <code>xx</code> 21.28 is a two digit hexadecimal number referring to the byte value of the 21.29 -unencoded character - see <a href="encodings.html">"Character 21.30 +unencoded character - see <a href="encodings.html">"Character 21.31 Encodings"</a> for information on how byte values should be 21.32 interpreted. </dd> 21.33 </dl> 21.34 @@ -108,4 +108,4 @@ 21.35 </div> 21.36 <p>The purpose and behaviour of <code>PUT</code> <a href="methods.html">request methods</a> is described in the <a href="http://www.w3.org/Protocols/rfc2616/rfc2616.html">HTTP 21.37 specification</a>.</p> 21.38 -</body></html> 21.39 \ No newline at end of file 21.40 +</body></html>
22.1 --- a/docs/path-design.html Sat Sep 08 16:01:41 2007 +0000 22.2 +++ b/docs/path-design.html Sat Sep 08 16:02:18 2007 +0000 22.3 @@ -1,10 +1,9 @@ 22.4 +<?xml version="1.0" encoding="iso-8859-1"?> 22.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 22.6 <html xmlns="http://www.w3.org/1999/xhtml"> 22.7 <head> 22.8 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> 22.9 <title>Path Design and Interpretation</title> 22.10 - <meta name="generator" 22.11 - content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 22.12 <link href="styles.css" rel="stylesheet" type="text/css" /> 22.13 </head> 22.14 <body>
23.1 --- a/docs/path-info-support.html Sat Sep 08 16:01:41 2007 +0000 23.2 +++ b/docs/path-info-support.html Sat Sep 08 16:02:18 2007 +0000 23.3 @@ -1,10 +1,9 @@ 23.4 +<?xml version="1.0" encoding="iso-8859-1"?> 23.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 23.6 <html xmlns="http://www.w3.org/1999/xhtml"><head> 23.7 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> 23.8 - 23.9 - <title>Path Info Support in Server Environments</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 23.10 + <title>Path Info Support in Server Environments</title> 23.11 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 23.12 - 23.13 <body> 23.14 <h1>Path Info Support in Server Environments</h1> 23.15 <p>The following table summarises the support for "path info" within 23.16 @@ -52,4 +51,4 @@ 23.17 </tr> 23.18 </tbody> 23.19 </table> 23.20 -</body></html> 23.21 \ No newline at end of file 23.22 +</body></html>
24.1 --- a/docs/path-info.html Sat Sep 08 16:01:41 2007 +0000 24.2 +++ b/docs/path-info.html Sat Sep 08 16:02:18 2007 +0000 24.3 @@ -1,9 +1,9 @@ 24.4 +<?xml version="1.0" encoding="iso-8859-1"?> 24.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 24.6 -<html xmlns="http://www.w3.org/1999/xhtml"><head> <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /><title>Paths To and Within Applications</title> 24.7 -<meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> <link href="styles.css" rel="stylesheet" type="text/css" /></head> 24.8 -<body><h1>Paths 24.9 -To and 24.10 -Within Applications</h1> 24.11 +<html xmlns="http://www.w3.org/1999/xhtml"><head> 24.12 + <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /><title>Paths To and Within Applications</title> 24.13 + <link href="styles.css" rel="stylesheet" type="text/css" /></head> 24.14 +<body><h1>Paths To and Within Applications</h1> 24.15 <p>One thing to be aware of, in the 24.16 code of an application, is which part 24.17 of 24.18 @@ -30,7 +30,7 @@ 24.19 </p><pre>/resource/operation</pre><p>In WebStack, we 24.20 refer to this latter case - the path within 24.21 the 24.22 -application - as the "path info".</p> 24.23 +application - as the "path info".</p> 24.24 <div class="WebStack"><h3>WebStack API - Paths To 24.25 Resources Within Applications</h3> 24.26 <p>On transaction objects, the 24.27 @@ -40,8 +40,8 @@ 24.28 <dl> <dt><code>get_path_info</code></dt> 24.29 <dd>This gets the path of a 24.30 resource within an application. The path should always contain a 24.31 -leading <code>/</code> character at the very least.<br /> 24.32 -An optional <code>encoding</code> parameter may be 24.33 +leading <code>/</code> character at the very least.<br /> 24.34 +An optional <code>encoding</code> parameter may be 24.35 used to assist the process of converting the path to a Unicode object - 24.36 see <a href="encodings.html">"Character Encodings"</a> 24.37 for more information.</dd> <dt><code>get_virtual_path_info</code></dt> 24.38 @@ -49,9 +49,9 @@ 24.39 resource within a part of an application 24.40 - the application itself decides the scope of the path and can set the 24.41 "virtual path info" using the <code>set_virtual_path_info</code> 24.42 -method. The path should either contain a leading <code>/</code> 24.43 +method. The path should either contain a leading <code>/</code> 24.44 character optionally followed by other characters, or an empty string.<br /> 24.45 -An optional <code>encoding</code> parameter may be 24.46 +An optional <code>encoding</code> parameter may be 24.47 used to assist the process of converting the path to a Unicode object - 24.48 see <a href="encodings.html">"Character Encodings"</a> 24.49 for more information.</dd><dt><code>get_processed_virtual_path_info</code></dt> 24.50 @@ -60,12 +60,12 @@ 24.51 info which does not appear in the virtual path info. In other words, 24.52 when components at the start of the virtual path info are removed, such 24.53 components will appear at the end of the processed virtual path info.<br /> 24.54 -An optional <code>encoding</code> parameter may be 24.55 +An optional <code>encoding</code> parameter may be 24.56 used to assist the process of converting the path to a Unicode object - 24.57 see <a href="encodings.html">"Character Encodings"</a> 24.58 for more information.</dd> 24.59 </dl></div><h2>Choosing the Right Path Value</h2> 24.60 -<p>Given that the path may change depending on 24.61 +<p>Given that the path may change depending on 24.62 where an 24.63 application is deployed in a server environment, it may not be very 24.64 easy to use when determining which resources are being requested or 24.65 @@ -81,7 +81,7 @@ 24.66 resources within an application.</td> </tr> <tr><td align="undefined" valign="undefined">Path without 24.67 path info</td><td align="undefined" valign="undefined">Finding 24.68 the location of the application in a server environment. (This is the 24.69 -path with the "path info" subtracted from 24.70 +path with the "path info" subtracted from 24.71 the end.)</td></tr><tr> <td align="undefined" valign="undefined">Path info</td> <td align="undefined" valign="undefined">Determining 24.72 which 24.73 resources are being accessed within an application.</td> </tr> 24.74 @@ -91,9 +91,9 @@ 24.75 application-defined version of "path info" and is discussed below.</td> 24.76 </tr> </tbody></table><h2>Using the Virtual 24.77 Path</h2> 24.78 -<p>Although WebStack sets the "path info" so that 24.79 +<p>Although WebStack sets the "path info" so that 24.80 applications 24.81 -know which part of themselves are being accessed, you may 24.82 +know which part of themselves are being accessed, you may 24.83 decide 24.84 that upon 24.85 processing the request, these different parts of your application 24.86 @@ -110,7 +110,7 @@ 24.87 same 24.88 as the "path info")...</p> 24.89 <pre>/company/department/employee</pre><p>...a 24.90 -resource might extract <code>company</code> from 24.91 +resource might extract <code>company</code> from 24.92 the start 24.93 of the path as follows:</p> 24.94 <pre> # Inside a respond method...<br /> path = trans.get_virtual_path_info() # get the virtual path<br /> parts = path.split("/") # split the path into components - the first will be empty</pre><p>Then, 24.95 @@ -118,12 +118,12 @@ 24.96 the first part will be an empty string)...</p> 24.97 <pre> if len(parts) > 1: # check to see how deep we are in the path<br /> process_something(parts[1]) # process the first non-empty part</pre><p>...it 24.98 will reconstruct the path, removing the processed part (but 24.99 -remembering to preserve a leading <code>/</code> 24.100 +remembering to preserve a leading <code>/</code> 24.101 character)...</p> 24.102 <pre> trans.set_virtual_path_info("/" + "/".join(parts[2:]))</pre><p>...and 24.103 hand over control to another resource which would do the same 24.104 thing with the first of the other path components (<code>department</code> 24.105 -and <code>employee</code>), and so on.</p> 24.106 +and <code>employee</code>), and so on.</p> 24.107 <p>The compelling thing about this strategy is the way that each 24.108 resource would only need to take the "virtual path info" into 24.109 consideration, and that each resource would believe that it is running 24.110 @@ -137,9 +137,9 @@ 24.111 following method exists to set virtual paths within applications.</p> 24.112 <dl><dt><code>set_virtual_path_info</code></dt><dd>This 24.113 sets the virtual path, affecting subsequent calls to the <code>get_virtual_path_info</code> 24.114 -method. The path should either contain a leading <code>/</code> 24.115 +method. The path should either contain a leading <code>/</code> 24.116 character optionally followed by other characters, or an empty string.</dd></dl> 24.117 -</div><h2>Summary</h2><p>The following illustration hopefully provides a more memorable way of representing the structure of paths:</p> 24.118 +</div><h2>Summary</h2><p>The following illustration hopefully provides a more memorable way of representing the structure of paths:</p> 24.119 <table style="text-align: left; width: 80%;" align="center" border="1" cellpadding="5" cellspacing="0" width="80%"> 24.120 <tbody> 24.121 <tr> 24.122 @@ -172,4 +172,4 @@ 24.123 </tr> 24.124 </tbody> 24.125 </table> 24.126 -</body></html> 24.127 \ No newline at end of file 24.128 +</body></html>
25.1 --- a/docs/path-manipulation.html Sat Sep 08 16:01:41 2007 +0000 25.2 +++ b/docs/path-manipulation.html Sat Sep 08 16:02:18 2007 +0000 25.3 @@ -1,8 +1,8 @@ 25.4 +<?xml version="1.0" encoding="iso-8859-1"?> 25.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 25.6 <html xmlns="http://www.w3.org/1999/xhtml"><head> 25.7 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> 25.8 - 25.9 - <title>Manipulating Paths</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 25.10 + <title>Manipulating Paths</title> 25.11 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 25.12 <body> 25.13 <h1>Manipulating Paths</h1><p>Whilst path values are useful in telling 25.14 @@ -10,4 +10,4 @@ 25.15 processing of a resource has progressed, it is sometimes useful to 25.16 apply some kind of transformation to the path in order to produce a 25.17 reference to another resource or application. Consider the simple case 25.18 -of <a href="redirection.html">redirecting</a> a user to another resource:</p><p>First we must obtain a reference to the current resource:<br /></p><pre>this_resource = trans.get_path_without_query() # eg. "/app/resource/some-data"</pre><p>We may wish to redirect the user to the main application resource; this is done by removing <code>resource</code> from the end of the path:</p><pre>this_app = trans.update_path("..") # produces "/app/resource"</pre><p>A complete description of this method can be found in the <a href="../apidocs/public/WebStack.Generic.Transaction-class.html#update_path">API documentation</a>.</p></body></html> 25.19 \ No newline at end of file 25.20 +of <a href="redirection.html">redirecting</a> a user to another resource:</p><p>First we must obtain a reference to the current resource:<br /></p><pre>this_resource = trans.get_path_without_query() # eg. "/app/resource/some-data"</pre><p>We may wish to redirect the user to the main application resource; this is done by removing <code>resource</code> from the end of the path:</p><pre>this_app = trans.update_path("..") # produces "/app/resource"</pre><p>A complete description of this method can be found in the <a href="../apidocs/public/WebStack.Generic.Transaction-class.html#update_path">API documentation</a>.</p></body></html>
26.1 --- a/docs/path-strategies.html Sat Sep 08 16:01:41 2007 +0000 26.2 +++ b/docs/path-strategies.html Sat Sep 08 16:02:18 2007 +0000 26.3 @@ -1,15 +1,17 @@ 26.4 +<?xml version="1.0" encoding="iso-8859-1"?> 26.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 26.6 -<html xmlns="http://www.w3.org/1999/xhtml"><head> <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /><title>Path Processing Strategies</title> 26.7 -<meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> <link href="styles.css" rel="stylesheet" type="text/css" /></head> 26.8 +<html xmlns="http://www.w3.org/1999/xhtml"><head> 26.9 + <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /><title>Path Processing Strategies</title> 26.10 + <link href="styles.css" rel="stylesheet" type="text/css" /></head> 26.11 <body><h1>Path Processing Strategies</h1> 26.12 <p>In the development of most Web applications, the structure of the 26.13 -application - also known as the "site map" - needs to be defined 26.14 +application - also known as the "site map" - needs to be defined 26.15 at a very early stage. We might decide that if a user requests a 26.16 certain path, a particular part of the application will be invoked, and 26.17 -we might define the site map in a number of different ways:</p><p>As a set of acceptable paths...</p><ul><li><code>/</code> is the main page</li><li><code>/services/finance/salaries/</code> is the salary report page</li><li><code>/services/customer/complaints/</code> is the complaints page</li></ul><p>As a tree of resources...</p><ul><li><code>/</code> is the main page</li><ul><li><code>.../services/</code> refers to services (which may not be defined as anything viewable)</li><ul><li><code>.../finance/</code> is the finance department</li><ul><li><code>.../salaries/</code> is the salary report page</li></ul><li><code>.../customer/</code> is the customer service department</li><ul><li><code>.../complaints/</code> is the complaints page</li></ul></ul></ul></ul><p>Since 26.18 +we might define the site map in a number of different ways:</p><p>As a set of acceptable paths...</p><ul><li><code>/</code> is the main page</li><li><code>/services/finance/salaries/</code> is the salary report page</li><li><code>/services/customer/complaints/</code> is the complaints page</li></ul><p>As a tree of resources...</p><ul><li><code>/</code> is the main page</li><ul><li><code>.../services/</code> refers to services (which may not be defined as anything viewable)</li><ul><li><code>.../finance/</code> is the finance department</li><ul><li><code>.../salaries/</code> is the salary report page</li></ul><li><code>.../customer/</code> is the customer service department</li><ul><li><code>.../complaints/</code> is the complaints page</li></ul></ul></ul></ul><p>Since 26.19 all of the action in WebStack applications takes place inside 26.20 resources, the challenge is to define resources in such a way which 26.21 -makes processing paths relatively easy.</p><h2>Chaining Resources</h2><p>Whilst the classic resource, as described in <a href="resources.html">"Applications and Resources"</a>, might resemble a simple class whose <code>respond</code> 26.22 +makes processing paths relatively easy.</p><h2>Chaining Resources</h2><p>Whilst the classic resource, as described in <a href="resources.html">"Applications and Resources"</a>, might resemble a simple class whose <code>respond</code> 26.23 method performs most of the necessary work, it is useful to reconsider 26.24 such a resource as doing such work only for a particular narrow part of 26.25 a larger Web application. Moreover, resources are not restricted in 26.26 @@ -20,13 +22,13 @@ 26.27 resource then invokes other resources to produce certain pages, we can 26.28 separate the path processing from the rest of the application's 26.29 functionality. So, for the first site map strategy, we could define a 26.30 -path processing resource as follows:</p><pre>from WebStack.Generic import EndOfResponse<br /><br />class PathProcessor:<br /><br /> "A path processing resource."<br /><br /> def __init__(self, main_page, salary_report_page, complaints_page):<br /><br /> # Supplied resources are chained to this resource.<br /><br /> self.main_page = main_page<br /> self.salary_report_page = salary_report_page<br /> self.complaints_page = complaints_page<br /><br /> def respond(self, trans):<br /><br /> # This is where the resources are invoked...<br /><br /> path = trans.get_path_without_query() # should really use an encoding here<br /> if path == "/":<br /> self.main_page.respond(trans)<br /> elif path == "/services/finance/salaries/":<br /> self.main_page.respond(trans)<br /> elif path == "/services/finance/salaries/":<br /> self.main_page.respond(trans)<br /><br /> # Administrative details...<br /><br /> else:<br /> trans.set_response_code(404) # not found!<br /> raise EndOfResponse</pre><p>Of 26.31 +path processing resource as follows:</p><pre>from WebStack.Generic import EndOfResponse<br /><br />class PathProcessor:<br /><br /> "A path processing resource."<br /><br /> def __init__(self, main_page, salary_report_page, complaints_page):<br /><br /> # Supplied resources are chained to this resource.<br /><br /> self.main_page = main_page<br /> self.salary_report_page = salary_report_page<br /> self.complaints_page = complaints_page<br /><br /> def respond(self, trans):<br /><br /> # This is where the resources are invoked...<br /><br /> path = trans.get_path_without_query() # should really use an encoding here<br /> if path == "/":<br /> self.main_page.respond(trans)<br /> elif path == "/services/finance/salaries/":<br /> self.main_page.respond(trans)<br /> elif path == "/services/finance/salaries/":<br /> self.main_page.respond(trans)<br /><br /> # Administrative details...<br /><br /> else:<br /> trans.set_response_code(404) # not found!<br /> raise EndOfResponse</pre><p>Of 26.32 course, more elegant methods of mapping paths to resources could be 26.33 employed - a dictionary might be an acceptable solution, if defined in 26.34 the initialiser method. The above class might be initialised as follows:</p><pre>main_page = MainResource()<br />salary_report_page = SalaryReportResource()<br />complaints_page = ComplaintsResource()<br />path_processor = PathProcessor(main_page, salary_report_page, complaints_page)</pre><p>For 26.35 the second site map strategy, we retain the basic parts of the above 26.36 strategy, focusing only on one level in the path as opposed to the 26.37 complete path. However, this means that our path processing resources 26.38 -need to know exactly which part of the path they should be 26.39 +need to know exactly which part of the path they should be 26.40 considering, and perhaps which part of the path has already been 26.41 -processed.</p><p>As described in <a href="path-info.html">"Paths To and Within Applications"</a>, special path information of the nature required is provided by two methods: <code>get_virtual_path_info</code> and <code>get_processed_virtual_path_info</code>. Such information can thus be obtained and updated at each level in the processing chain.</p><pre>class MainPathProcessor:<br /><br /> "A path processor for the top of the application."<br /><br /> def __init__(self, main_page, services_processor):<br /> self.main_page = main_page<br /> self.services_processor = services_processor<br /><br /> def respond(self, trans):<br /><br /> # This is where the resources are invoked...<br /><br /> path = trans.get_virtual_path_info() # should really use an encoding here<br /> if path == "/":<br /> self.main_page.respond(trans)<br /> elif path.startswith("/services/"):<br /> trans.set_virtual_path_info(path[len("/services"):]) # cut off "/services"<br /> self.services_processor.respond(trans)<br /><br /> # Administrative details...<br /><br /> else:<br /> trans.set_response_code(404) # not found!<br /> raise EndOfResponse</pre><p>A suite of similar classes can be defined and might be initialised as follows:</p><pre>main_page = MainResource()<br />salary_report_page = SalaryReportResource()<br />complaints_page = ComplaintsResource()<br />finance_processor = FinancePathProcessor(salary_report_page)<br />customer_processor = CustomerPathProcessor(complaints_page)<br />services_processor = ServicesPathProcessor(finance_processor, customer_processor)<br />main_processor = MainPathProcessor(main_page, services_processor)</pre><p>Fortunately, this latter strategy is supported by WebStack in the form of the <code>ResourceMap</code> module. See <a href="paths-filesystem.html">"Treating the Path Like a Filesystem"</a> and <a href="resource-map.html">"ResourceMap - Simple Mappings from Names to Resources"</a> for details.</p></body></html> 26.42 \ No newline at end of file 26.43 +processed.</p><p>As described in <a href="path-info.html">"Paths To and Within Applications"</a>, special path information of the nature required is provided by two methods: <code>get_virtual_path_info</code> and <code>get_processed_virtual_path_info</code>. Such information can thus be obtained and updated at each level in the processing chain.</p><pre>class MainPathProcessor:<br /><br /> "A path processor for the top of the application."<br /><br /> def __init__(self, main_page, services_processor):<br /> self.main_page = main_page<br /> self.services_processor = services_processor<br /><br /> def respond(self, trans):<br /><br /> # This is where the resources are invoked...<br /><br /> path = trans.get_virtual_path_info() # should really use an encoding here<br /> if path == "/":<br /> self.main_page.respond(trans)<br /> elif path.startswith("/services/"):<br /> trans.set_virtual_path_info(path[len("/services"):]) # cut off "/services"<br /> self.services_processor.respond(trans)<br /><br /> # Administrative details...<br /><br /> else:<br /> trans.set_response_code(404) # not found!<br /> raise EndOfResponse</pre><p>A suite of similar classes can be defined and might be initialised as follows:</p><pre>main_page = MainResource()<br />salary_report_page = SalaryReportResource()<br />complaints_page = ComplaintsResource()<br />finance_processor = FinancePathProcessor(salary_report_page)<br />customer_processor = CustomerPathProcessor(complaints_page)<br />services_processor = ServicesPathProcessor(finance_processor, customer_processor)<br />main_processor = MainPathProcessor(main_page, services_processor)</pre><p>Fortunately, this latter strategy is supported by WebStack in the form of the <code>ResourceMap</code> module. See <a href="paths-filesystem.html">"Treating the Path Like a Filesystem"</a> and <a href="resource-map.html">"ResourceMap - Simple Mappings from Names to Resources"</a> for details.</p></body></html>
27.1 --- a/docs/path-value-encoding.html Sat Sep 08 16:01:41 2007 +0000 27.2 +++ b/docs/path-value-encoding.html Sat Sep 08 16:02:18 2007 +0000 27.3 @@ -1,8 +1,8 @@ 27.4 +<?xml version="1.0" encoding="iso-8859-1"?> 27.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 27.6 <html xmlns="http://www.w3.org/1999/xhtml"><head> 27.7 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> 27.8 - 27.9 - <title>Encoding and Decoding Path Values</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 27.10 + <title>Encoding and Decoding Path Values</title> 27.11 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 27.12 <body> 27.13 <h1>Encoding and Decoding Path Values</h1><p>On some occasions it can 27.14 @@ -12,19 +12,19 @@ 27.15 transaction methods are available:</p><div class="WebStack"> 27.16 <h3>WebStack API - Encoding and Decoding Path Values</h3> 27.17 <p>WebStack provides the following methods to transform path values:</p> 27.18 -<dl><dt><code>decode_path</code></dt><dd>This method accepts a path containing "URL encoded" information (as defined in the <a href="paths.html">"URLs and Paths"</a> 27.19 +<dl><dt><code>decode_path</code></dt><dd>This method accepts a path containing "URL encoded" information (as defined in the <a href="paths.html">"URLs and Paths"</a> 27.20 document) and, using an optional encoding parameter, returns a Unicode 27.21 object containing genuine character values in place of the "URL 27.22 encoded" values.</dd><dt><code>encode_path</code></dt><dd>This method 27.23 accepts a Unicode object containing the path and an optional encoding 27.24 -parameter; it reverses the process carried out by the <code>decode_path</code> method.</dd></dl> 27.25 -</div><p>Generally, the <code>decode_path</code> method is of little interest; its only relatively common application might be to decode query strings:</p><pre>qs = trans.get_query_string() # eg. "a=%E6"<br />new_qs = trans.decode_path(qs, "iso-8859-1") # producing "a=æ"</pre><p>Such operations are generally better performed using the <a href="parameters.html">request parameter methods</a>.</p><p>The <code>encode_path</code> 27.26 +parameter; it reverses the process carried out by the <code>decode_path</code> method.</dd></dl> 27.27 +</div><p>Generally, the <code>decode_path</code> method is of little interest; its only relatively common application might be to decode query strings:</p><pre>qs = trans.get_query_string() # eg. "a=%E6"<br />new_qs = trans.decode_path(qs, "iso-8859-1") # producing "a=æ"</pre><p>Such operations are generally better performed using the <a href="parameters.html">request parameter methods</a>.</p><p>The <code>encode_path</code> 27.28 method is slightly more useful: since various transaction methods 27.29 return values which have already been transformed into Unicode objects, 27.30 we must consider the use of <code>encode_path</code> to produce values 27.31 which are suitable for feeding into other methods. For example, having 27.32 obtained a path, we may wish to cause a <a href="redirection.html">redirect</a> to another location 27.33 -based on that path:</p><pre>path = trans.get_path_without_query("iso-8859-1") # eg. "/app/resource"<br />path += "/æøå"<br />new_path = trans.encode_path(path, "iso-8859-1") # producing "/app/resource/%E6%F8%E5"<br />trans.redirect(new_path)</pre><p>It 27.34 +based on that path:</p><pre>path = trans.get_path_without_query("iso-8859-1") # eg. "/app/resource"<br />path += "/æøå;"<br />new_path = trans.encode_path(path, "iso-8859-1") # producing "/app/resource/%E6%F8%E5"<br />trans.redirect(new_path)</pre><p>It 27.35 is essential to encode the path in such situations because the 27.36 underlying mechanisms do not support the full range of Unicode 27.37 -characters. Some cases where this limitation exists are listed in the <a href="encodings.html">"Character Encodings"</a> document.</p></body></html> 27.38 \ No newline at end of file 27.39 +characters. Some cases where this limitation exists are listed in the <a href="encodings.html">"Character Encodings"</a> document.</p></body></html>
28.1 --- a/docs/paths-filesystem.html Sat Sep 08 16:01:41 2007 +0000 28.2 +++ b/docs/paths-filesystem.html Sat Sep 08 16:02:18 2007 +0000 28.3 @@ -1,68 +1,46 @@ 28.4 +<?xml version="1.0" encoding="iso-8859-1"?> 28.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 28.6 <html xmlns="http://www.w3.org/1999/xhtml"><head> 28.7 - 28.8 - <title>Treating the Path Like a Filesystem</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 28.9 + <title>Treating the Path Like a Filesystem</title> 28.10 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 28.11 <body> 28.12 -<h1>Treating the Path Like a 28.13 -Filesystem</h1> 28.14 -<p>...or as a reference into 28.15 -deeply categorized resources. In this approach, 28.16 +<h1>Treating the Path Like a Filesystem</h1> 28.17 +<p>...or as a reference into deeply categorized resources. In this approach, 28.18 we take a path like this...</p> 28.19 <pre>/documents/news/2005/article.html</pre> 28.20 -<p>...and we consider <code>documents</code>, 28.21 -<code>news</code>, 28.22 -and 28.23 -<code>2005</code> 28.24 -as directories, and <code>article.html</code> 28.25 -as a 28.26 +<p>...and we consider <code>documents</code>, <code>news</code>, and 28.27 +<code>2005</code> as directories, and <code>article.html</code> as a 28.28 file-like resource. If we ask for the following path...</p> 28.29 <pre>/documents/news/2005</pre> 28.30 -<p>...we may decide to provide a 28.31 -listing of files within that directory, or 28.32 -we may decide to refuse such a request. Indeed some kinds of 28.33 -applications insist 28.34 -that such a listing may only be produced with the following path 28.35 -instead:</p> 28.36 +<p>...we may decide to provide a listing of files within that directory, or 28.37 +we may decide to refuse such a request. Indeed some kinds of applications insist 28.38 +that such a listing may only be produced with the following path instead:</p> 28.39 <pre>/documents/news/2005/</pre> 28.40 -<p>Applications of this kind are 28.41 -quite common since the publishing of files 28.42 -on a Web server often just involves exposing parts of a real filesystem 28.43 -to 28.44 +<p>Applications of this kind are quite common since the publishing of files 28.45 +on a Web server often just involves exposing parts of a real filesystem to 28.46 requests through the server.</p> 28.47 -<h2>Resource Hierarchies in 28.48 -WebStack</h2> 28.49 -<p>There are a number of different 28.50 -ways that paths can be interpreted and handled in WebStack 28.51 +<h2>Resource Hierarchies in WebStack</h2> 28.52 +<p>There are a number of different ways that paths can be interpreted and handled in WebStack 28.53 applications, including...</p> 28.54 <ul> 28.55 - <li>Using predefined hierarchies 28.56 -of resources.</li> 28.57 - <li>By inspecting the path in a 28.58 -top-level resource and then creating resources to deal with different 28.59 + <li>Using predefined hierarchies of resources.</li> 28.60 + <li>By inspecting the path in a top-level resource and then creating resources to deal with different 28.61 cases.</li> 28.62 - <li>By handling all kinds of 28.63 -paths in the same resource.</li> 28.64 + <li>By handling all kinds of paths in the same resource.</li> 28.65 </ul> 28.66 -<h3>Predefining Resource 28.67 -Hierarchies</h3> 28.68 -<p>We might decide to represent 28.69 -components in these kinds of paths using 28.70 +<h3>Predefining Resource Hierarchies</h3> 28.71 +<p>We might decide to represent components in these kinds of paths using 28.72 different resource classes; for example:</p> 28.73 <ul> 28.74 - <li>Folders or directories are 28.75 -represented by a special resource class which contains other 28.76 + <li>Folders or directories are represented by a special resource class which contains other 28.77 folders and possibly some files.</li> 28.78 - <li>Files or documents are 28.79 -represented by special resource classes which provide access 28.80 + <li>Files or documents are represented by special resource classes which provide access 28.81 to the content of such files.</li> 28.82 </ul> 28.83 -We might then predefine a hierarchy of resources 28.84 -so that when a request arrives for a resource, we can check it against 28.85 -the 28.86 -hierarchy and process the request according to whichever type of 28.87 -resource is 28.88 -being accessed. For example:<br /> 28.89 +<p>We might then predefine a hierarchy of resources 28.90 +so that when a request arrives for a resource, we can check it against the 28.91 +hierarchy and process the request according to whichever type of resource is 28.92 +being accessed. For example:</p> 28.93 <ul> 28.94 <li><code>documents</code> 28.95 <ul> 28.96 @@ -84,23 +62,22 @@ 28.97 </ul> 28.98 </li> 28.99 </ul> 28.100 -<p>Consider the above hierarchy; 28.101 -we would implement such a hierarchy with a 28.102 -resource object mapped to <code>documents</code>, 28.103 -and that resource object 28.104 +<p>Consider the above hierarchy; we would implement such a hierarchy with a 28.105 +resource object mapped to <code>documents</code>, and that resource object 28.106 would contain a mapping of years to other resources. Eventually, at the 28.107 bottom of the hierarchy, individual resources would represent articles 28.108 -and be 28.109 -mapped to names such as <code>article.html</code>.</p> 28.110 +and be mapped to names such as <code>article.html</code>.</p> 28.111 <div class="WebStack"> 28.112 -<h3>WebStack API - Predefining 28.113 -Resource Hierarchies in Adapter Code</h3> 28.114 +<h3>WebStack API - Predefining Resource Hierarchies in Adapter Code</h3> 28.115 28.116 <p>WebStack provides the <code>MapResource</code> 28.117 class (in the <code>WebStack.Resources.ResourceMap</code> module) for convenient mapping of path 28.118 -components to resource objects<code></code>. See the <a href="resource-map.html">"ResourceMap - Simple Mappings from Names to Resources"</a> document for a more detailed description of the <code>MapResource</code> class.</p><p>This class can be used in <a href="deploying.html">adapter code</a> 28.119 -to initialise an 28.120 -application as follows:</p> 28.121 +components to resource objects<code></code>. 28.122 +See the <a href="resource-map.html">"ResourceMap - Simple Mappings from Names to Resources"</a> 28.123 +document for a more detailed description of the <code>MapResource</code> class.</p> 28.124 + 28.125 +<p>This class can be used in <a href="deploying.html">adapter code</a> 28.126 +to initialise an application as follows:</p> 28.127 <pre>from WebStack.Resources.ResourceMap import MapResource<br />from MyApplication import FileResource # import some resource class<br /><br />article_resource = FileResource(...) # make a resource representing the article<br />document_resource = FileResource(...) # make a resource representing the document<br />year_2004_resource = MapResource({"document.html" : document_resource})<br />year_2005_resource = MapResource({"article.html" : article_resource})<br />news_resource = MapResource({"2005" : year_2005_resource, "2004" : year_2004_resource})<br />documents_resource = MapResource({"news" : news_resource})<br />top_resource = MapResource({"documents" : documents_resource})</pre> 28.128 </div> 28.129 <p>Of course, predefining resource 28.130 @@ -108,4 +85,4 @@ 28.131 hierarchies. We could inspect paths and act dynamically on the supplied 28.132 information, either choosing to create resources or choosing to handle 28.133 such paths in the same resource.</p> 28.134 -</body></html> 28.135 \ No newline at end of file 28.136 +</body></html>
29.1 --- a/docs/paths-opaque.html Sat Sep 08 16:01:41 2007 +0000 29.2 +++ b/docs/paths-opaque.html Sat Sep 08 16:02:18 2007 +0000 29.3 @@ -1,27 +1,20 @@ 29.4 +<?xml version="1.0" encoding="iso-8859-1"?> 29.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 29.6 <html xmlns="http://www.w3.org/1999/xhtml"> 29.7 <head> 29.8 <title>Using the Path as an Opaque Reference into an Application</title> 29.9 - <meta name="generator" 29.10 - content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 29.11 <link href="styles.css" rel="stylesheet" type="text/css" /> 29.12 </head> 29.13 <body> 29.14 <h1>Using the Path as an Opaque Reference into an Application</h1> 29.15 <p>Since many Web applications have complete control over how paths are 29.16 -interpreted, the form of the path doesn't necessarily have to follow 29.17 -any 29.18 -obvious structure as far as users of your application is concerned. 29.19 -Here's an 29.20 +interpreted, the form of the path doesn't necessarily have to follow any 29.21 +obvious structure as far as users of your application is concerned. Here's an 29.22 example:</p> 29.23 <pre>/000251923572ax-0015</pre> 29.24 -<p>Many people would argue that such obscure references, whilst 29.25 -perfectly 29.26 -acceptable to machines, would make any application counter-intuitive 29.27 -and very 29.28 -difficult to reference. However, application developers sometimes 29.29 -do not want people 29.30 -"bookmarking" resources or functions within an application, and so such 29.31 -concerns don't matter to them.</p> 29.32 +<p>Many people would argue that such obscure references, whilst perfectly 29.33 +acceptable to machines, would make any application counter-intuitive and very 29.34 +difficult to reference. However, application developers sometimes do not want people 29.35 +"bookmarking" resources or functions within an application, and so such concerns don't matter to them.</p> 29.36 </body> 29.37 </html>
30.1 --- a/docs/paths-services.html Sat Sep 08 16:01:41 2007 +0000 30.2 +++ b/docs/paths-services.html Sat Sep 08 16:02:18 2007 +0000 30.3 @@ -4,7 +4,6 @@ 30.4 <html xmlns="http://www.w3.org/1999/xhtml"> 30.5 <head> 30.6 <title>Treating the Path Mostly Like a Filesystem</title> 30.7 - <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 30.8 <link href="styles.css" rel="stylesheet" type="text/css" /> 30.9 </head> 30.10
31.1 --- a/docs/paths.html Sat Sep 08 16:01:41 2007 +0000 31.2 +++ b/docs/paths.html Sat Sep 08 16:02:18 2007 +0000 31.3 @@ -1,7 +1,7 @@ 31.4 +<?xml version="1.0" encoding="iso-8859-1"?> 31.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 31.6 <html xmlns="http://www.w3.org/1999/xhtml"><head> 31.7 - 31.8 - <title>URLs and Paths</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 31.9 + <title>URLs and Paths</title> 31.10 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 31.11 <body> 31.12 <h1>URLs and Paths</h1> 31.13 @@ -31,7 +31,7 @@ 31.14 <p>In an application the full URL, containing the address of the 31.15 machine on which it is running, is not always interesting. In the 31.16 WebStack API (and in other Web programming frameworks), we also talk 31.17 -about "paths" - a path is just the part of the 31.18 +about "paths" - a path is just the part of the 31.19 URL which refers to the resource or service, ignoring the actual 31.20 Internet 31.21 address, and so the above example would have a path which looks like 31.22 @@ -53,18 +53,18 @@ 31.23 <dd>This gets the entire path of a resource including parameter 31.24 information (as described in <a href="parameters.html">"Request 31.25 Parameters and Uploads"</a>).<br /> 31.26 -An optional <code>encoding</code> parameter may be used to assist the process of converting the path to a Unicode object - see below.</dd> 31.27 +An optional <code>encoding</code> parameter may be used to assist the process of converting the path to a Unicode object - see below.</dd> 31.28 <dt><code>get_path_without_query</code></dt> 31.29 <dd>This gets the entire path of a resource but without any parameter 31.30 information.<br /> 31.31 31.32 -An optional <code>encoding</code> parameter may be used to assist the process of converting the path to a Unicode object - see below.</dd><dt><code>get_path_without_info</code></dt><dd>This gets the entire path of a resource but without any parameter 31.33 +An optional <code>encoding</code> parameter may be used to assist the process of converting the path to a Unicode object - see below.</dd><dt><code>get_path_without_info</code></dt><dd>This gets the entire path of a resource but without any parameter 31.34 information or any special "path info" (as described in <a href="path-info.html">"Paths To and Within Applications"</a>). 31.35 The result is more or less equivalent to the location where an 31.36 application has been "published" - ie. the location of an application 31.37 in a server environment.<br /> 31.38 31.39 -An optional <code>encoding</code> parameter may be used to assist the process of converting the path to a Unicode object - see below.</dd> 31.40 +An optional <code>encoding</code> parameter may be used to assist the process of converting the path to a Unicode object - see below.</dd> 31.41 </dl> 31.42 </div> 31.43 <p>To obtain the above path using the WebStack API, we can write the following code:</p> 31.44 @@ -95,21 +95,21 @@ 31.45 Uploads"</a>.</p> 31.46 <div class="WebStack"> 31.47 <h3>WebStack API - Getting Query Strings</h3> 31.48 -<p>WebStack provides a method to get only the query string from the URL:</p> 31.49 +<p>WebStack provides a method to get only the query string from the URL:</p> 31.50 <dl><dt><code>get_query_string</code></dt><dd>This method returns the part of the URL which contains parameter 31.51 information. Such information will be "URL encoded", meaning that 31.52 -certain characters will have the form <code>%xx</code> where <code>xx</code> 31.53 +certain characters will have the form <code>%xx</code> where <code>xx</code> 31.54 is a two digit hexadecimal number referring to the byte value of the 31.55 unencoded character - see below for discussion of this. </dd></dl> 31.56 </div> 31.57 -<p>Note that unlike the path access methods, <code>get_query_string</code> 31.58 +<p>Note that unlike the path access methods, <code>get_query_string</code> 31.59 does not accept an encoding as a parameter. Moreover, when retrieving a 31.60 path including a query string, the encoding is not used to interpret 31.61 "URL encoded" character values in the query string itself. Consider 31.62 this example URL:</p> 31.63 <pre>http://www.boddie.org.uk/application-%E6?var%F8=value%E5</pre> 31.64 <p>Upon requesting the path and the query string, certain differences should be noticeable:</p> 31.65 -<pre>trans.get_path("iso-8859-1") # returns /application-æ?var%F8=value%E5<br />trans.get_path_without_query("iso-8859-1") # returns /application-æ<br />trans.get_query_string() # returns var%F8=value%E5</pre> 31.66 +<pre>trans.get_path("iso-8859-1") # returns /application-æ?var%F8=value%E5<br />trans.get_path_without_query("iso-8859-1") # returns /application-æ<br />trans.get_query_string() # returns var%F8=value%E5</pre> 31.67 <p>One reason for this seemingly arbitrary distinction in treatment is 31.68 the way certain servers present path information to WebStack - often 31.69 the "URL encoded" information has been replaced by raw character values 31.70 @@ -121,7 +121,7 @@ 31.71 <pre>http://www.boddie.org.uk/application?a=%26b</pre> 31.72 <p>If we were to just decode the query string and then extract the 31.73 parameters/fields, the result would be two empty parameters with the 31.74 -names <code>a</code> and <code>b</code>, as opposed to the correct interpretation of the query string as describing a single parameter <code>a</code> with the value <code>&b</code>.</p> 31.75 +names <code>a</code> and <code>b</code>, as opposed to the correct interpretation of the query string as describing a single parameter <code>a</code> with the value <code>&b</code>.</p> 31.76 <h3>Final Note</h3> 31.77 <p>Regardless of all this, all inspection of path parameters should be done using the appropriate methods (see <a href="parameters.html">"Request Parameters and 31.78 Uploads"</a>), 31.79 @@ -134,4 +134,4 @@ 31.80 <li><a href="path-info-support.html">Path Info Support in Server 31.81 Environments</a></li> 31.82 </ul> 31.83 -</body></html> 31.84 \ No newline at end of file 31.85 +</body></html>
32.1 --- a/docs/pythonpath.html Sat Sep 08 16:01:41 2007 +0000 32.2 +++ b/docs/pythonpath.html Sat Sep 08 16:02:18 2007 +0000 32.3 @@ -4,7 +4,6 @@ 32.4 <html xmlns="http://www.w3.org/1999/xhtml"> 32.5 <head> 32.6 <title>Getting PYTHONPATH Right</title> 32.7 - <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 32.8 <link href="styles.css" rel="stylesheet" type="text/css" /> 32.9 </head> 32.10
33.1 --- a/docs/redirection.html Sat Sep 08 16:01:41 2007 +0000 33.2 +++ b/docs/redirection.html Sat Sep 08 16:02:18 2007 +0000 33.3 @@ -1,8 +1,8 @@ 33.4 +<?xml version="1.0" encoding="iso-8859-1"?> 33.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 33.6 <html xmlns="http://www.w3.org/1999/xhtml"><head> 33.7 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> 33.8 - 33.9 - <title>Redirection</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 33.10 + <title>Redirection</title> 33.11 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 33.12 <body> 33.13 <h1>Redirection</h1><p>Instead of presenting information to a user when 33.14 @@ -14,4 +14,4 @@ 33.15 <p>WebStack provides the following method in transaction objects to perform redirection:</p> 33.16 <dl><dt><code>redirect</code></dt><dd>This method accepts a path value 33.17 suitable for use in response headers indicating the location to which a 33.18 -user shall be redirected. An optional response code (see <a href="responses.html">"Responses and Presentation"</a>) can be specified to modify the meaning of the redirection (as defined in the HTTP specifications).</dd></dl></div><p>Since the path value must be usable in response header, it is necessary to transform paths as described in the <a href="path-value-encoding.html">"Encoding and Decoding Path Values"</a> document, and an example of redirection is given in that document.</p></body></html> 33.19 \ No newline at end of file 33.20 +user shall be redirected. An optional response code (see <a href="responses.html">"Responses and Presentation"</a>) can be specified to modify the meaning of the redirection (as defined in the HTTP specifications).</dd></dl></div><p>Since the path value must be usable in response header, it is necessary to transform paths as described in the <a href="path-value-encoding.html">"Encoding and Decoding Path Values"</a> document, and an example of redirection is given in that document.</p></body></html>
34.1 --- a/docs/resource-creation.html Sat Sep 08 16:01:41 2007 +0000 34.2 +++ b/docs/resource-creation.html Sat Sep 08 16:02:18 2007 +0000 34.3 @@ -1,24 +1,23 @@ 34.4 +<?xml version="1.0" encoding="iso-8859-1"?> 34.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 34.6 <html xmlns="http://www.w3.org/1999/xhtml"> 34.7 <head> 34.8 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> 34.9 <title>How Resources are Created</title> 34.10 - <meta name="generator" 34.11 - content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 34.12 <link href="styles.css" rel="stylesheet" type="text/css" /> 34.13 </head> 34.14 <body> 34.15 <h1>How Resources are Created 34.16 </h1> 34.17 -<p>In the <code>MyApplication</code> 34.18 +<p>In the <code>MyApplication</code> 34.19 <a href="resources.html">example</a> (and in many applications), 34.20 the only 34.21 thing we need to 34.22 consider is 34.23 -what our code does, not how objects are created from the <code>MyResource</code> 34.24 +what our code does, not how objects are created from the <code>MyResource</code> 34.25 class and how the <code>respond</code> 34.26 method is invoked. However, the mechanisms behind all these things are 34.27 -not magic - the <a href="deploying.html">adapter 34.28 +not magic - the <a href="deploying.html">adapter 34.29 code</a> is responsible for all of 34.30 this. Let us 34.31 turn the diagram of components on its side and investigate what happens 34.32 @@ -51,7 +50,7 @@ 34.33 in the application... </span></td> 34.34 <td 34.35 style="background-color: rgb(193, 255, 102); border-left-style: solid; border-right-style: solid; border-left-width: 1px; border-right-width: 1px;" 34.36 - align="undefined" valign="undefined"><span class="method">A resource 34.37 + align="undefined" valign="undefined"><span class="method">A resource 34.38 object is 34.39 created and initialised. </span></td> 34.40 </tr> 34.41 @@ -79,7 +78,7 @@ 34.42 <p>In more 34.43 complicated applications, there may 34.44 be a 34.45 -need to create a number of resource objects and possibly to do so 34.46 +need to create a number of resource objects and possibly to do so 34.47 dynamically within an application itself, but this is not usually 34.48 interesting or relevant to think about when writing your first 34.49 application - see <a href="paths-filesystem.html">"Treating the Path
35.1 --- a/docs/resource-map.html Sat Sep 08 16:01:41 2007 +0000 35.2 +++ b/docs/resource-map.html Sat Sep 08 16:02:18 2007 +0000 35.3 @@ -1,29 +1,30 @@ 35.4 +<?xml version="1.0" encoding="iso-8859-1"?> 35.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 35.6 -<html xmlns="http://www.w3.org/1999/xhtml"><head><meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> 35.7 - 35.8 - <title>ResourceMap - Simple Mappings from Names to Resources</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 35.9 +<html xmlns="http://www.w3.org/1999/xhtml"><head> 35.10 + <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> 35.11 + <title>ResourceMap - Simple Mappings from Names to Resources</title> 35.12 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 35.13 <body> 35.14 <h1>ResourceMap - Simple Mappings from Names to Resources</h1> 35.15 -<p>The <code>ResourceMap</code> module provides classes (although 35.16 +<p>The <code>ResourceMap</code> module provides classes (although 35.17 currently only one class is supplied) which act as standard WebStack 35.18 resources, but which examine the path or URL from incoming requests and 35.19 direct such requests to other resources based on the contents of the 35.20 path or URL. In other words, such classes map names or patterns to 35.21 -WebStack resources and dispatch requests accordingly.</p><h2>Introducing MapResource</h2><p>The <a href="paths-filesystem.html">"Treating the Path Like a Filesystem"</a> document contains an example involving the <code>MapResource</code> class; this class is initialised with a dictionary mapping names to resources as described below.</p><div class="WebStack"> 35.22 -<h3>WebStack API - The MapResource Class</h3> 35.23 +WebStack resources and dispatch requests accordingly.</p><h2>Introducing MapResource</h2><p>The <a href="paths-filesystem.html">"Treating the Path Like a Filesystem"</a> document contains an example involving the <code>MapResource</code> class; this class is initialised with a dictionary mapping names to resources as described below.</p><div class="WebStack"> 35.24 +<h3>WebStack API - The MapResource Class</h3> 35.25 35.26 -<p>The <code>MapResource</code> 35.27 +<p>The <code>MapResource</code> 35.28 class (found in the 35.29 <code>WebStack.Resources.ResourceMap</code> module) maps names to 35.30 resource objects, where to select a resource the 35.31 -corresponding name must match the first component discovered 35.32 +corresponding name must match the first component discovered 35.33 in the <a href="path-info.html">virtual "path info"</a>. For example, 35.34 consider the following virtual "path info" (where there may have been 35.35 -more information in the path, but this has already been processed):</p><pre>/documents/news/2005/article.html</pre><p>Here, the name <code>documents</code> 35.36 +more information in the path, but this has already been processed):</p><pre>/documents/news/2005/article.html</pre><p>Here, the name <code>documents</code> 35.37 would match the above virtual "path info". Meanwhile, after processing 35.38 more of the information, we might have the following remains of the 35.39 -path:</p><pre>/2005/article.html</pre><p>Here, the name <code>2005</code> would match, leaving the following information unprocessed:</p><pre>/article.html</pre><p>Here, the name <code>article.html</code> would match. However, let us consider the following original virtual "path info" instead:</p><pre>/documents/news/2005/</pre><p>After processing the leading components, we may instead end up with this:</p><pre>/</pre><p>Here, only an empty string as the name will specifically match the above.</p><h4>Further Reading</h4><p>The <a href="../apidocs/public/WebStack.Resources.ResourceMap.MapResource-class.html">API documentation</a> for the <code>MapResource</code> 35.40 +path:</p><pre>/2005/article.html</pre><p>Here, the name <code>2005</code> would match, leaving the following information unprocessed:</p><pre>/article.html</pre><p>Here, the name <code>article.html</code> would match. However, let us consider the following original virtual "path info" instead:</p><pre>/documents/news/2005/</pre><p>After processing the leading components, we may instead end up with this:</p><pre>/</pre><p>Here, only an empty string as the name will specifically match the above.</p><h4>Further Reading</h4><p>The <a href="../apidocs/public/WebStack.Resources.ResourceMap.MapResource-class.html">API documentation</a> for the <code>MapResource</code> 35.41 class provides more detail on the subject of name matching, including 35.42 the special "catch all" name and a discussion of the pass-through 35.43 -parameter.</p></div></body></html> 35.44 \ No newline at end of file 35.45 +parameter.</p></div></body></html>
36.1 --- a/docs/resources.html Sat Sep 08 16:01:41 2007 +0000 36.2 +++ b/docs/resources.html Sat Sep 08 16:02:18 2007 +0000 36.3 @@ -1,12 +1,12 @@ 36.4 +<?xml version="1.0" encoding="iso-8859-1"?> 36.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 36.6 <html xmlns="http://www.w3.org/1999/xhtml"><head> 36.7 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> 36.8 - 36.9 - <title>Applications and Resources</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 36.10 + <title>Applications and Resources</title> 36.11 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 36.12 <body> 36.13 <h1>Applications and Resources</h1> 36.14 -At its simplest a WebStack application is just a single Python 36.15 +At its simplest a WebStack application is just a single Python 36.16 class that we call a "resource". This class can be defined inside a 36.17 normal Python module or package, so let us start by doing the following:<br /> 36.18 <ol> 36.19 @@ -16,19 +16,19 @@ 36.20 <li>Create a file called <code>MyApplication.py</code> 36.21 - this is our module.</li> 36.22 </ol> 36.23 -We are going to call our resource <code>MyResource</code> 36.24 +We are going to call our resource <code>MyResource</code> 36.25 and in principle it will have a structure that looks like this: 36.26 <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> 36.27 <p>It is in this kind of resource 36.28 class that we write the 36.29 actual application code or at least the beginnings of it. When a user 36.30 of the application sends us a request, 36.31 -the <code>respond</code> method 36.32 +the <code>respond</code> method 36.33 will be called and the code 36.34 within it executed. The parts of the pseudo-code in 36.35 the above text which aren't valid Python 36.36 (ie. the bits in square brackets) will, when we have written them, use 36.37 -the <code>trans</code> 36.38 +the <code>trans</code> 36.39 object to find out what any given user of the application has sent us, 36.40 and to send information back 36.41 to the 36.42 @@ -40,23 +40,23 @@ 36.43 to produce some kind of 36.44 response. Here is how we can make our application do something:</p> 36.45 <ol> 36.46 - <li>Edit the module 36.47 -file <code>MyApplication.py</code>.</li> 36.48 + <li>Edit the module 36.49 +file <code>MyApplication.py</code>.</li> 36.50 <li>Write into it the following 36.51 -code which defines <code>MyResource</code>:</li> 36.52 +code which defines <code>MyResource</code>:</li> 36.53 </ol> 36.54 -<pre>class MyResource:<br /> def respond(self, trans):<br /> out = trans.get_response_stream()<br /> print >>out, "Hello world."</pre> 36.55 +<pre>class MyResource:<br /> def respond(self, trans):<br /> out = trans.get_response_stream()<br /> print >>out, "Hello world."</pre> 36.56 <h2>Testing the Resource</h2> 36.57 <p>To test this resource we need to deploy it, and to do that we need 36.58 an 36.59 adapter to connect it to the outside world. Here is a quick way of writing an adapter and testing this 36.60 code:</p> 36.61 <ol> 36.62 - <li> Create a file called <code>MyAdapter.py</code> - you 36.63 + <li> Create a file called <code>MyAdapter.py</code> - you 36.64 can choose another name if you want - this will be where the adapter 36.65 code lives.</li> 36.66 <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> 36.67 -and <code>MyAdapter.py</code>, you may run <code>MyAdapter.py</code> 36.68 +and <code>MyAdapter.py</code>, you may run <code>MyAdapter.py</code> 36.69 as follows:</p><ol> 36.70 36.71 </ol> 36.72 @@ -64,6 +64,6 @@ 36.73 <p>This should start the adapter program and print the following 36.74 message:</p> 36.75 <pre>Serving...</pre> 36.76 -<p>You should now be able to visit <code>http://localhost:8080</code> 36.77 +<p>You should now be able to visit <code>http://localhost:8080</code> 36.78 in your 36.79 -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> 36.80 \ No newline at end of file 36.81 +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>
37.1 --- a/docs/responses.html Sat Sep 08 16:01:41 2007 +0000 37.2 +++ b/docs/responses.html Sat Sep 08 16:02:18 2007 +0000 37.3 @@ -1,7 +1,7 @@ 37.4 +<?xml version="1.0" encoding="iso-8859-1"?> 37.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 37.6 <html xmlns="http://www.w3.org/1999/xhtml"><head> 37.7 - 37.8 - <title>Responses and Presentation</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 37.9 + <title>Responses and Presentation</title> 37.10 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 37.11 <body> 37.12 <h1>Responses and Presentation</h1> 37.13 @@ -33,12 +33,12 @@ 37.14 <p>The kind of code involved may 37.15 well resemble the following:</p> 37.16 <pre>from WebStack.Generic import ContentType<br /><br />class MyResource:<br /> def respond(self, trans):<br /> [Perform the requested operations.]<br /><br /> if [the operation was successful]:<br /> trans.set_response_code(200)<br /> trans.set_content_type(ContentType("text/html", encoding="utf-8"))<br /> out = trans.get_response_stream()<br /> out.write([some data either as a plain string suitably encoded or as Unicode])<br /> else:<br /> trans.set_response_code(500) # or some other code<br /> trans.set_content_type(ContentType("text/html", encoding="utf-8"))<br /> out = trans.get_response_stream()<br /> out.write([some other data either as a plain string suitably encoded or as Unicode])</pre> 37.17 -<h2>Unicode and the Response Stream</h2><p>Although an encoding may be specified or be set as a default by the <code>EncodingSelector</code> (see <a href="selectors.html">"Selectors - Components for Dispatching to Resources"</a>), 37.18 +<h2>Unicode and the Response Stream</h2><p>Although an encoding may be specified or be set as a default by the <code>EncodingSelector</code> (see <a href="selectors.html">"Selectors - Components for Dispatching to Resources"</a>), 37.19 it should be noted that the encoding of textual information will only 37.20 take place if Unicode objects are written to the stream. Where binary 37.21 information or information which should not be changed is being 37.22 written, this must be supplied as plain strings to the transaction 37.23 -object's <code>write</code> method.</p><p>As discussed in <a href="encodings.html">"Character Encodings"</a>, 37.24 +object's <code>write</code> method.</p><p>As discussed in <a href="encodings.html">"Character Encodings"</a>, 37.25 care 37.26 must be taken generating the response so that it meets any expectations 37.27 that 37.28 @@ -69,7 +69,7 @@ 37.29 convey information to the user (and their software) which is comparable 37.30 to that found in <a href="headers.html">request headers</a> sent in to 37.31 the Web application; for example, the content type information is 37.32 -transmitted using response headers (using the <code>Content-Type</code> header name), although the above <code>set_content_type</code> method is a more convenient means of preparing such information.</dd> 37.33 +transmitted using response headers (using the <code>Content-Type</code> header name), although the above <code>set_content_type</code> method is a more convenient means of preparing such information.</dd> 37.34 <dt><code>get_response_stream</code></dt> 37.35 <dd>This returns the output 37.36 stream through which data may be sent to the user.</dd> 37.37 @@ -77,14 +77,14 @@ 37.38 </div> 37.39 <h2>Ending the Response Explicitly</h2> 37.40 <p>Although it is possible to produce some output and then to let 37.41 -the <code>respond</code> function complete normally, sometimes it 37.42 +the <code>respond</code> function complete normally, sometimes it 37.43 is appropriate to terminate the response and to hand control straight 37.44 back to the server environment; in other words, to decide that no more 37.45 activity will be performed within the application and to send the 37.46 -response immediately. Whilst just using a <code>return</code> 37.47 +response immediately. Whilst just using a <code>return</code> 37.48 statement might be adequate in many applications...</p> 37.49 <pre> # In the respond method...<br /> if some_condition:<br /> [Produce a response.]<br /> return<br /> [Produce a different response.]</pre> 37.50 -<p>...sometimes a resource's <code>respond</code> method is being 37.51 +<p>...sometimes a resource's <code>respond</code> method is being 37.52 called from another resource, and it may be the case that this other 37.53 resource may produce additional output if control is returned to it.</p> 37.54 <p>To provide a definitive end of response signal, a special exception 37.55 @@ -108,9 +108,9 @@ 37.56 it is usually advisable to consider using templating systems which 37.57 combine raw data and templates to produce formatted output that can be 37.58 displayed as a Web page (amongst other things).</p> 37.59 -<p>See <a href="integrating.html">"Integration with Other Systems"</a> 37.60 +<p>See <a href="integrating.html">"Integration with Other Systems"</a> 37.61 for more information on the principles of using such external libraries. See also <a href="http://www.boddie.org.uk/python/XSLTools.html">XSLTools</a> 37.62 for a distribution of utilities, including a Web forms framework called 37.63 XSLForms, which can be of use in generating content for Web 37.64 applications.</p> 37.65 -</body></html> 37.66 \ No newline at end of file 37.67 +</body></html>
38.1 --- a/docs/securing.html Sat Sep 08 16:01:41 2007 +0000 38.2 +++ b/docs/securing.html Sat Sep 08 16:02:18 2007 +0000 38.3 @@ -1,9 +1,8 @@ 38.4 +<?xml version="1.0" encoding="iso-8859-1"?> 38.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 38.6 <html xmlns="http://www.w3.org/1999/xhtml"> 38.7 <head> 38.8 <title>Securing a WebStack Application</title> 38.9 - <meta name="generator" 38.10 - content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 38.11 <link href="styles.css" rel="stylesheet" type="text/css" /> 38.12 </head> 38.13 <body>
39.1 --- a/docs/selectors.html Sat Sep 08 16:01:41 2007 +0000 39.2 +++ b/docs/selectors.html Sat Sep 08 16:02:18 2007 +0000 39.3 @@ -1,7 +1,7 @@ 39.4 +<?xml version="1.0" encoding="iso-8859-1"?> 39.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 39.6 <html xmlns="http://www.w3.org/1999/xhtml"><head><meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> 39.7 - 39.8 - <title>Selectors - Components for Dispatching to Resources</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 39.9 + <title>Selectors - Components for Dispatching to Resources</title> 39.10 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 39.11 <body> 39.12 <h1>Selectors - Components for Dispatching to Resources</h1> 39.13 @@ -10,7 +10,7 @@ 39.14 resources, but which attempt to "select" other resources, dispatch each 39.15 request to those resources, and to cause various side-effects, mostly 39.16 on the attributes stored on the transaction object. These "selector" 39.17 -classes behave those in the <code>ResourceMap</code> module, but aspire to be more generally applicable.</p><h2>Selecting Path Roots with PathSelector</h2><p>In 39.18 +classes behave those in the <code>ResourceMap</code> module, but aspire to be more generally applicable.</p><h2>Selecting Path Roots with PathSelector</h2><p>In 39.19 non-trivial applications, it is often desirable to know the path or URL 39.20 to a particular resource, especially the "root" resource under which 39.21 the application or one of its components may reside. The <code>PathSelector</code> 39.22 @@ -20,12 +20,12 @@ 39.23 39.24 <p>The <code>PathSelector</code> 39.25 class (found in the 39.26 -<code>WebStack.Resources.Selectors</code> module) wraps resource 39.27 +<code>WebStack.Resources.Selectors</code> module) wraps resource 39.28 objects whose location (as indicated by a path or URL) should be 39.29 recorded as an attribute on the current transaction. The most common 39.30 use of the class is to record the "root" resource's location, 39.31 and this would be done as follows:</p><pre>def get_site_map():<br /> return PathSelector(MyResource())</pre><p>Here, the <code>get_site_map</code> 39.32 -function (as described in the <a href="deploying.html">"Deploying a WebStack Application"</a> document) would provide a <code>PathSelector</code> object instead of an instance of the <code>MyResource</code> class. However, the side-effect of combining these two resources would be the availability of an attribute named <code>root</code> on the transaction object. Thus, the "root" <code>MyResource</code> 39.33 +function (as described in the <a href="deploying.html">"Deploying a WebStack Application"</a> document) would provide a <code>PathSelector</code> object instead of an instance of the <code>MyResource</code> class. However, the side-effect of combining these two resources would be the availability of an attribute named <code>root</code> on the transaction object. Thus, the "root" <code>MyResource</code> 39.34 object and, indeed, all resource objects visited after this side-effect 39.35 has occurred will have access to the "root" path or URL information.</p><h4>Further Reading</h4><p>The <a href="../apidocs/public/WebStack.Resources.Selectors.PathSelector-class.html">API documentation</a> for the <code>PathSelector</code> 39.36 class provides additional information.</p></div><h2>Defining Encodings using EncodingSelector</h2><p>One 39.37 @@ -33,9 +33,9 @@ 39.38 processing and production of text in different encodings. Whilst the 39.39 WebStack API lets applications explicitly state the character encoding 39.40 for various operations, one often wants to be able to ignore such 39.41 -details since they start to clutter up application code. The <code>EncodingSelector</code> class offers a basic solution which is compatible with the mechanisms in transaction objects: by wrapping WebStack resources with instances of <code>EncodingSelector</code>, 39.42 +details since they start to clutter up application code. The <code>EncodingSelector</code> class offers a basic solution which is compatible with the mechanisms in transaction objects: by wrapping WebStack resources with instances of <code>EncodingSelector</code>, 39.43 an application-wide default encoding (or character set) will be 39.44 -defined; this will result in request information being processed 39.45 +defined; this will result in request information being processed 39.46 according to the stated encoding and response information being 39.47 produced according to that encoding (see below for more details of the 39.48 latter activity).</p><div class="WebStack"> 39.49 @@ -43,22 +43,22 @@ 39.50 39.51 <p>The <code>EncodingSelector</code> 39.52 class (found in the 39.53 -<code>WebStack.Resources.Selectors</code> module) wraps resource 39.54 -objects whilst changing the default encoding of the current transaction object. The class can be applied like this:</p><pre>def get_site_map():<br /> return EncodingSelector(MyResource(), "utf-8")</pre><p>Here, the <code>get_site_map</code> 39.55 -function (as described in the <a href="deploying.html">"Deploying a WebStack Application"</a> document) would provide a <code>EncodingSelector</code> object instead of an instance of the <code>MyResource</code> class. However, the <code>EncodingSelector</code> will forward requests on to <code>MyResource</code> (since it "selects" that resource), whilst setting the default encoding to be <code>"utf-8"</code>.</p><h4>Request Streams and Encodings</h4><p>Although a default encoding affects the processing of request parameters, direct access to the request stream using the <code>get_request_stream</code> 39.56 +<code>WebStack.Resources.Selectors</code> module) wraps resource 39.57 +objects whilst changing the default encoding of the current transaction object. The class can be applied like this:</p><pre>def get_site_map():<br /> return EncodingSelector(MyResource(), "utf-8")</pre><p>Here, the <code>get_site_map</code> 39.58 +function (as described in the <a href="deploying.html">"Deploying a WebStack Application"</a> document) would provide a <code>EncodingSelector</code> object instead of an instance of the <code>MyResource</code> class. However, the <code>EncodingSelector</code> will forward requests on to <code>MyResource</code> (since it "selects" that resource), whilst setting the default encoding to be <code>"utf-8"</code>.</p><h4>Request Streams and Encodings</h4><p>Although a default encoding affects the processing of request parameters, direct access to the request stream using the <code>get_request_stream</code> 39.59 method will only produce plain strings. This behaviour is justified by 39.60 the observation that, if conversion from an encoding to Unicode were to 39.61 take place, the resulting character values may be unsuitable 39.62 substitutes for the original byte values in applications intending to 39.63 make use of the raw incoming (possibly binary) data. A recipe for 39.64 -making a Unicode stream is provided in the <a href="encodings.html">"Character Encodings"</a> document.</p><h4>Response Encodings and Content Types</h4><p>Although <code>EncodingSelector</code> sets 39.65 -a default encoding, responses will generally be written in that 39.66 +making a Unicode stream is provided in the <a href="encodings.html">"Character Encodings"</a> document.</p><h4>Response Encodings and Content Types</h4><p>Although <code>EncodingSelector</code> sets 39.67 +a default encoding, responses will generally be written in that 39.68 encoding, at least if textual data is written to the response stream as 39.69 Unicode objects. However, the content type must typically be set either 39.70 to match the encoding in use or to not specify an encoding. It may 39.71 become necessary to find out what the response stream encoding is when 39.72 -creating a <code>ContentType</code> object. For this and other purposes, the <code>get_response_stream_encoding</code> method is available on the transaction object<code></code>:</p><pre>from WebStack.Generic import ContentType<br /><br />def respond(self, trans):<br /><br /> # Some code...<br /><br /> trans.set_content_type(ContentType("text/html", trans.get_response_stream_encoding()))<br /> out = trans.get_response_stream()<br /> out.write(some_unicode_object)</pre><p>However, it is completely acceptable to omit the encoding information where a default encoding has been set:</p><pre> trans.set_content_type(ContentType("text/html")) # no encoding/charset specified<br /></pre><h4>Reading the Default Directly</h4><p>For 39.73 +creating a <code>ContentType</code> object. For this and other purposes, the <code>get_response_stream_encoding</code> method is available on the transaction object<code></code>:</p><pre>from WebStack.Generic import ContentType<br /><br />def respond(self, trans):<br /><br /> # Some code...<br /><br /> trans.set_content_type(ContentType("text/html", trans.get_response_stream_encoding()))<br /> out = trans.get_response_stream()<br /> out.write(some_unicode_object)</pre><p>However, it is completely acceptable to omit the encoding information where a default encoding has been set:</p><pre> trans.set_content_type(ContentType("text/html")) # no encoding/charset specified<br /></pre><h4>Reading the Default Directly</h4><p>For 39.74 some activities, such as making a Unicode stream from the request 39.75 stream, it is desirable to find out the encoding set by the selector. 39.76 -This information is made available on transaction objects as the <code>default_charset</code> attribute.</p><h4>Further Reading</h4><p>The <a href="../apidocs/public/WebStack.Resources.Selectors.EncodingSelector-class.html">API documentation</a> for the <code>EncodingSelector</code> 39.77 -class provides additional information, along with the <a href="responses.html">"Responses and Presentation"</a> document.</p></div><p></p><br /></body></html> 39.78 \ No newline at end of file 39.79 +This information is made available on transaction objects as the <code>default_charset</code> attribute.</p><h4>Further Reading</h4><p>The <a href="../apidocs/public/WebStack.Resources.Selectors.EncodingSelector-class.html">API documentation</a> for the <code>EncodingSelector</code> 39.80 +class provides additional information, along with the <a href="responses.html">"Responses and Presentation"</a> document.</p></div><p></p><br /></body></html>
40.1 --- a/docs/sessions-servers.html Sat Sep 08 16:01:41 2007 +0000 40.2 +++ b/docs/sessions-servers.html Sat Sep 08 16:02:18 2007 +0000 40.3 @@ -1,18 +1,17 @@ 40.4 +<?xml version="1.0" encoding="iso-8859-1"?> 40.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 40.6 <html xmlns="http://www.w3.org/1999/xhtml"><head> 40.7 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> 40.8 - 40.9 - <title>Server Environment Support for Sessions</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 40.10 + <title>Server Environment Support for Sessions</title> 40.11 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 40.12 - 40.13 <body> 40.14 <h1>Server Environment Support for Sessions</h1> 40.15 <p>Various server environments or frameworks do not support sessions 40.16 directly. In order to provide primitive support for sessions within 40.17 -WebStack upon such frameworks, the <code>WebStack.Helpers.Session</code> 40.18 +WebStack upon such frameworks, the <code>WebStack.Helpers.Session</code> 40.19 module is used to provide a simple file-based session store. Before 40.20 deploying an application on one of these frameworks, it may be necessary to 40.21 -create a directory called <code>WebStack-sessions</code> in a 40.22 +create a directory called <code>WebStack-sessions</code> in a 40.23 particular location so that the storage of session information will 40.24 work, although WebStack will attempt to create such a directory if it does not already exist.</p> 40.25 <p>The location of the <code>WebStack-sessions</code> directory 40.26 @@ -36,7 +35,7 @@ 40.27 <tr> 40.28 <td align="undefined" valign="undefined">mod_python</td> 40.29 <td align="undefined" valign="undefined">The server root (such 40.30 -as <code>/usr/local/apache2</code>).</td> 40.31 +as <code>/usr/local/apache2</code>).</td> 40.32 </tr> 40.33 <tr> 40.34 <td align="undefined" valign="undefined">Twisted</td> 40.35 @@ -45,7 +44,7 @@ 40.36 </tr> 40.37 </tbody> 40.38 </table> 40.39 -<p>Note that the <code>WebStack-sessions</code> directory must 40.40 +<p>Note that the <code>WebStack-sessions</code> directory must 40.41 have the appropriate ownership and privileges necessary for the server 40.42 or framework to write session information into it.<br /> 40.43 </p> 40.44 @@ -57,4 +56,4 @@ 40.45 CVS snapshot used for testing) do not support session detection or 40.46 expiry correctly.</li> 40.47 </ul> 40.48 -</body></html> 40.49 \ No newline at end of file 40.50 +</body></html>
41.1 --- a/docs/sessions-usage.html Sat Sep 08 16:01:41 2007 +0000 41.2 +++ b/docs/sessions-usage.html Sat Sep 08 16:02:18 2007 +0000 41.3 @@ -1,8 +1,8 @@ 41.4 +<?xml version="1.0" encoding="iso-8859-1"?> 41.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 41.6 <html xmlns="http://www.w3.org/1999/xhtml"><head> 41.7 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> 41.8 - 41.9 - <title>Using Sessions</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 41.10 + <title>Using Sessions</title> 41.11 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 41.12 <body> 41.13 <h1>Using Sessions</h1> 41.14 @@ -13,7 +13,7 @@ 41.15 <ul> 41.16 <li>Sensitive or private information. Although such information can 41.17 be stored without needing to 41.18 -encrypt it, in many applications you will still want to 41.19 +encrypt it, in many applications you will still want to 41.20 encrypt such information anyway, no matter where it is stored or how it 41.21 is communicated.</li> 41.22 <li>Large amounts of session information can be stored, or at least 41.23 @@ -27,14 +27,14 @@ 41.24 accessing and maintenance of session information:</p> 41.25 <dl> 41.26 <dt><code>get_session</code></dt> 41.27 - <dd>This method returns the session for the identified user. The <code>create</code> 41.28 + <dd>This method returns the session for the identified user. The <code>create</code> 41.29 parameter can be set to a true value to create a new session for a user 41.30 if no session previously existed; otherwise <code>None</code> is 41.31 returned in such situations.</dd> 41.32 <dt><code>expire_session</code></dt> 41.33 <dd>This method causes the session information associated with the 41.34 identified user to be forgotten. Note that this may not really happen 41.35 -until the user sends another request, and that the <code>get_session</code> 41.36 +until the user sends another request, and that the <code>get_session</code> 41.37 method may still return the current session.</dd> 41.38 </dl> 41.39 <p>Session objects, which resemble dictionaries, employ plain Python 41.40 @@ -70,4 +70,4 @@ 41.41 string value. These limitations may be removed in a later release.</li> 41.42 </ul> 41.43 41.44 -</body></html> 41.45 \ No newline at end of file 41.46 +</body></html>
42.1 --- a/docs/sessions.html Sat Sep 08 16:01:41 2007 +0000 42.2 +++ b/docs/sessions.html Sat Sep 08 16:02:18 2007 +0000 42.3 @@ -1,8 +1,8 @@ 42.4 +<?xml version="1.0" encoding="iso-8859-1"?> 42.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 42.6 <html xmlns="http://www.w3.org/1999/xhtml"><head> 42.7 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> 42.8 - 42.9 - <title>Sessions and Persistent Information</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 42.10 + <title>Sessions and Persistent Information</title> 42.11 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 42.12 42.13 <body> 42.14 @@ -18,10 +18,10 @@ 42.15 <li>It then accesses a data store containing information associated 42.16 different users.</li> 42.17 <li>Finally, it accesses information specific to the stated user - 42.18 -this is that particular user's session.</li> 42.19 +this is that particular user's session.</li> 42.20 </ol> 42.21 <h2>Sessions vs. Persistent Information</h2> 42.22 -<p>Information can be said to be "persistent" when it is 42.23 +<p>Information can be said to be "persistent" when it is 42.24 remembered beyond the lifetime of a particular request to an 42.25 application. Sessions, meanwhile, are effectively a special case of 42.26 persistent information - data is addressed or accessed using each 42.27 @@ -60,4 +60,4 @@ 42.28 <li><a href="sessions-servers.html">Server Environment Support for 42.29 Sessions</a></li> 42.30 </ul> 42.31 -</body></html> 42.32 \ No newline at end of file 42.33 +</body></html>
43.1 --- a/docs/state.html Sat Sep 08 16:01:41 2007 +0000 43.2 +++ b/docs/state.html Sat Sep 08 16:02:18 2007 +0000 43.3 @@ -1,16 +1,15 @@ 43.4 +<?xml version="1.0" encoding="iso-8859-1"?> 43.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 43.6 <html xmlns="http://www.w3.org/1999/xhtml"> 43.7 <head> 43.8 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> 43.9 <title>Cookies, Sessions, Users and Persistent Information</title> 43.10 - <meta name="generator" 43.11 - content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 43.12 <link href="styles.css" rel="stylesheet" type="text/css" /> 43.13 </head> 43.14 <body> 43.15 <h1>Cookies, Sessions, Users and Persistent Information</h1> 43.16 <p>Due to the nature of the communications mechanisms 43.17 -involved, Web applications do not have automatic or "magic" 43.18 +involved, Web applications do not have automatic or "magic" 43.19 knowledge about the people or entities accessing them as application 43.20 users. Moreover, Web applications do not necessarily remember anything 43.21 about what that user has done before. Due to this behaviour, where
44.1 --- a/docs/supported-frameworks.html Sat Sep 08 16:01:41 2007 +0000 44.2 +++ b/docs/supported-frameworks.html Sat Sep 08 16:02:18 2007 +0000 44.3 @@ -1,7 +1,7 @@ 44.4 +<?xml version="1.0" encoding="iso-8859-1"?> 44.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 44.6 <html xmlns="http://www.w3.org/1999/xhtml"><head><meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> 44.7 - 44.8 - <title>Supported Frameworks</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 44.9 + <title>Supported Frameworks</title> 44.10 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 44.11 <body> 44.12 <h1>Supported Frameworks</h1> 44.13 @@ -55,4 +55,4 @@ 44.14 44.15 <p>See the <a href="deploying-applications.html">"Deploying Applications"</a> document for information on exact deployment procedures for each of the above frameworks.</p> 44.16 <ul></ul> 44.17 -</body></html> 44.18 \ No newline at end of file 44.19 +</body></html>
45.1 --- a/docs/users.html Sat Sep 08 16:01:41 2007 +0000 45.2 +++ b/docs/users.html Sat Sep 08 16:02:18 2007 +0000 45.3 @@ -1,17 +1,16 @@ 45.4 +<?xml version="1.0" encoding="iso-8859-1"?> 45.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 45.6 <html xmlns="http://www.w3.org/1999/xhtml"> 45.7 <head> 45.8 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> 45.9 <title>Users and Authentication</title> 45.10 - <meta name="generator" 45.11 - content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 45.12 <link href="styles.css" rel="stylesheet" type="text/css" /> 45.13 </head> 45.14 <body> 45.15 <h1>Users and Authentication</h1> 45.16 <p>One way of discovering the identity of the user sending a request 45.17 -into your application is to test the identity using methods on the 45.18 -transaction object. Before this can be made to work, you must set 45.19 +into your application is to test the identity using methods on the 45.20 +transaction object. Before this can be made to work, you must set 45.21 up authentication for your application, as described in <a 45.22 href="securing.html">"Securing a WebStack Application"</a>. Once 45.23 authentication is working, every request that arrives in the
46.1 --- a/docs/writing-adapters.html Sat Sep 08 16:01:41 2007 +0000 46.2 +++ b/docs/writing-adapters.html Sat Sep 08 16:02:18 2007 +0000 46.3 @@ -1,7 +1,7 @@ 46.4 +<?xml version="1.0" encoding="iso-8859-1"?> 46.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 46.6 <html xmlns="http://www.w3.org/1999/xhtml"><head> 46.7 - 46.8 - <title>Writing Adapters</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 46.9 + <title>Writing Adapters</title> 46.10 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 46.11 <body> 46.12 <h1>Writing Adapters</h1> 46.13 @@ -19,7 +19,7 @@ 46.14 <p>When deploying an application, 46.15 it is possible to use a one-shot 46.16 deployment 46.17 -function for BaseHTTPRequestServer, CGI, Django, Java Servlet, mod_python, Twisted and WSGI configurations. The 46.18 +function for BaseHTTPRequestServer, CGI, Django, Java Servlet, mod_python, Twisted and WSGI configurations. The 46.19 <code>deploy</code> 46.20 function is called as follows:</p> 46.21 <pre>deploy(resource)<br />deploy(resource, authenticator) # where authenticators are used</pre> 46.22 @@ -27,7 +27,7 @@ 46.23 may be specified:</p> 46.24 <pre>deploy(resource, address=(host_string, port_integer))<br />deploy(resource, authenticator, address=(host_string, port_integer))</pre> 46.25 <p>And for some frameworks, the return value of the function is important:</p><pre>something = deploy(resource)<br />something, something_else = deploy(resource, authenticator)</pre><p>Here is a summary of which 46.26 -frameworks require address information and which produce important return values from the <code>deploy</code> function:</p> 46.27 +frameworks require address information and which produce important return values from the <code>deploy</code> function:</p> 46.28 <table border="1" cellpadding="5" cellspacing="0"> 46.29 <tbody> 46.30 <tr> 46.31 @@ -57,10 +57,10 @@ 46.32 <p>Sometimes, when resources throw unhandled exceptions when processing 46.33 requests, it is desirable to see the details of the exceptions either 46.34 in the Web browser or in the console from which the application was 46.35 -started. For such purposes, a parameter to the <code>deploy</code> 46.36 +started. For such purposes, a parameter to the <code>deploy</code> 46.37 function can be used:</p> 46.38 <pre>deploy(resource, handle_errors=0)</pre> 46.39 -<p>The <code>handle_errors</code> parameter, if specified with a 46.40 +<p>The <code>handle_errors</code> parameter, if specified with a 46.41 false value, will not supress unhandled exceptions with an "internal 46.42 server error" response, but will instead provide the underlying server 46.43 environment's report of such exceptions.</p> 46.44 @@ -143,4 +143,4 @@ 46.45 <p>See <a href="deploying-applications.html">"Deploying an 46.46 Application"</a> 46.47 for more details of the deployment process for each environment.</p> 46.48 -</body></html> 46.49 \ No newline at end of file 46.50 +</body></html>