|
24 | 24 | <p>The wrapper provides the following benefits:</p>
|
25 | 25 |
|
26 | 26 | <ul>
|
27 |
| - <li>Sets up global variables <em>headers</em>, <em>fields</em>, <em>env</em>, <em>wrapper</em> and <em>WebUtils</em> for use by the target script.</li> |
28 |
| - <li>Catches exceptions that the target script doesn't in order to provide a meaningful message to the web page reader and useful debugging information to the developer.</li> |
29 |
| - <li>Logs the date, time, duration and name of the target script for usage statistics and performance monitoring.</li> |
30 |
| - <li>Simplifies URLs by leaving out the extension and possibly the location of the script. This also hides the nature of the implementation of the page from the browser of your site.</li> |
31 |
| - <li>Provides a hook for integrating an object for cookies.</li> |
32 |
| - <li>Provides a hook for class-based CGIs.</li> |
| 27 | + <li>Sets up global variables <em>headers</em>, <em>fields</em>, <em>env</em>, <em>wrapper</em> and <em>WebUtils</em> for use by the target script.</li> |
| 28 | + <li>Catches exceptions that the target script doesn't in order to provide a meaningful message to the web page reader and useful debugging information to the developer.</li> |
| 29 | + <li>Logs the date, time, duration and name of the target script for usage statistics and performance monitoring.</li> |
| 30 | + <li>Simplifies URLs by leaving out the extension and possibly the location of the script. This also hides the nature of the implementation of the page from the browser of your site.</li> |
| 31 | + <li>Provides a hook for integrating an object for cookies.</li> |
| 32 | + <li>Provides a hook for class-based CGIs.</li> |
33 | 33 | </ul>
|
34 | 34 |
|
35 | 35 | <p>You don't have to immediately write code to play with CGI Wrapper. There are several samples included. See <a href="#Running">Running and Testing</a> below.</p>
|
|
42 | 42 | <table align="center" cellspacing="0" cellpadding="4" border="1" width="80%">
|
43 | 43 | <tr><th>Global</th> <th>Type/Class</th> <th>Description</th> </tr>
|
44 | 44 | <tr>
|
45 |
| - <td><code>headers</code> </td> |
46 |
| - <td>dictionary </td> |
47 |
| - <td>Contains all the HTTP headers that will be sent back to the client. The default contents are 'Content-type': 'text/html'. Often, the headers don't need to be modified at all. One popular use of the headers is 'Redirect': 'someURL' to point the client to a different place. </td> |
| 45 | + <td><code>headers</code> </td> |
| 46 | + <td>dictionary </td> |
| 47 | + <td>Contains all the HTTP headers that will be sent back to the client. The default contents are 'Content-type': 'text/html'. Often, the headers don't need to be modified at all. One popular use of the headers is 'Redirect': 'someURL' to point the client to a different place. </td> |
48 | 48 | </tr>
|
49 | 49 | <tr>
|
50 |
| - <td><code>fields</code> </td> |
51 |
| - <td>cgi.FieldStorage </td> |
52 |
| - <td>This instance of FieldStorage comes from the standard Python cgi module. Typical uses include <code>fields.has_key('someField')</code> and <code>fields['someField'].value</code>. See the Python standard module documentation for cgi for more information. </td> |
| 50 | + <td><code>fields</code> </td> |
| 51 | + <td>cgi.FieldStorage </td> |
| 52 | + <td>This instance of FieldStorage comes from the standard Python cgi module. Typical uses include <code>fields.has_key('someField')</code> and <code>fields['someField'].value</code>. See the Python standard module documentation for cgi for more information. </td> |
53 | 53 | </tr>
|
54 | 54 | <tr>
|
55 |
| - <td><code>environ</code> </td> |
56 |
| - <td>dictionary </td> |
57 |
| - <td>This dictionary represents the environment variables passed to the CGI scripts. Scripts should use this rather than <code>os.environ</code> since future versions of CGI Wrapper could be tightly integrated into web servers, thereby changing the nature of how environment variables get passed around (e.g., no longer through the OS). Also, note that the environment may seem a little non-standard to the target CGI script since the web server is setting it up to run the CGI Wrapper instead. In most CGI scripts (that execute under the wrapper), the environment is not even needed. </td> |
| 55 | + <td><code>environ</code> </td> |
| 56 | + <td>dictionary </td> |
| 57 | + <td>This dictionary represents the environment variables passed to the CGI scripts. Scripts should use this rather than <code>os.environ</code> since future versions of CGI Wrapper could be tightly integrated into web servers, thereby changing the nature of how environment variables get passed around (e.g., no longer through the OS). Also, note that the environment may seem a little non-standard to the target CGI script since the web server is setting it up to run the CGI Wrapper instead. In most CGI scripts (that execute under the wrapper), the environment is not even needed. </td> |
58 | 58 | </tr>
|
59 | 59 | <tr>
|
60 |
| - <td><code>wrapper</code> </td> |
61 |
| - <td>CGIWrapper </td> |
62 |
| - <td>This is a pointer back to the CGI Wrapper instance. This allows CGI scripts to communicate with the wrapper if they want. However, this is hardly ever needed. </td> |
| 60 | + <td><code>wrapper</code> </td> |
| 61 | + <td>CGIWrapper </td> |
| 62 | + <td>This is a pointer back to the CGI Wrapper instance. This allows CGI scripts to communicate with the wrapper if they want. However, this is hardly ever needed. </td> |
63 | 63 | </tr>
|
64 | 64 | <tr>
|
65 |
| - <td><code>cookies</code> </td> |
66 |
| - <td>Cookie </td> |
67 |
| - <td>This global is <b>not</b> set up by the wrapper, but is looked for upon exit of the CGI script. See the <em>Cookies</em> section below for more information. </td> |
| 65 | + <td><code>cookies</code> </td> |
| 66 | + <td>Cookie </td> |
| 67 | + <td>This global is <b>not</b> set up by the wrapper, but is looked for upon exit of the CGI script. See the <em>Cookies</em> section below for more information. </td> |
68 | 68 | </tr>
|
69 | 69 | </table>
|
70 | 70 |
|
|
74 | 74 | <p>One of the main benefits of the wrapper is the handling of uncaught exceptions raised by target CGI scripts. The typical behavior of the wrapper upon detecting an uncaught exception is:</p>
|
75 | 75 |
|
76 | 76 | <ol>
|
77 |
| - <li>Log the time, error, script name and traceback to <code>stderr</code>. This information will typically appear in the web server's error log.</li> |
78 |
| - <li>Display a web page containing an apologetic message to the user and useful debugging information for developers.</li> |
79 |
| - <li>Save the above web page to a file so that developers can look at it after-the-fact. These HTML-based error messages are stored one-per-file, if the <code>SaveErrorMessages</code> setting is true (the default). They are stored in the directory named by the <code>ErrorMessagesDir</code> (defaults to 'ErrorMsgs').</li> |
80 |
| - <li>Add an entry to the CGI Wrapper's error log, called <i>Errors.csv</i>.</li> |
81 |
| - <li>E-mail the error message if the <code>EmailErrors</code> setting is true, using the settings <code>ErrorEmailServer</code> and <code>ErrorEmailHeaders</code>.</li> |
| 77 | + <li>Log the time, error, script name and traceback to <code>stderr</code>. This information will typically appear in the web server's error log.</li> |
| 78 | + <li>Display a web page containing an apologetic message to the user and useful debugging information for developers.</li> |
| 79 | + <li>Save the above web page to a file so that developers can look at it after-the-fact. These HTML-based error messages are stored one-per-file, if the <code>SaveErrorMessages</code> setting is true (the default). They are stored in the directory named by the <code>ErrorMessagesDir</code> (defaults to 'ErrorMsgs').</li> |
| 80 | + <li>Add an entry to the CGI Wrapper's error log, called <i>Errors.csv</i>.</li> |
| 81 | + <li>E-mail the error message if the <code>EmailErrors</code> setting is true, using the settings <code>ErrorEmailServer</code> and <code>ErrorEmailHeaders</code>.</li> |
82 | 82 | </ol>
|
83 | 83 |
|
84 | 84 | <p>Archived error messages can be browsed through the <a href="#Administration">administration page</a>.</p>
|
@@ -386,21 +386,21 @@ A list of IP addresses or networks from which admin scripts can be accessed.
|
386 | 386 | <a name="ToDo"></a><h3>To Do</h3>
|
387 | 387 |
|
388 | 388 | <ol>
|
389 |
| - <li>Examples: Make a Cookie example. (In the meantime, just see the main doc string of Cookie.py in WebUtils.)</li> |
390 |
| - <li>Wrapper: When a script produces no output, the CGI Wrapper should report that problem. (This most often happens for class based CGIs with incorrect class names.)</li> |
391 |
| - <li>Wrapper: There should probably be an option to clear the output of a script that raised an uncaught exception. Sometimes that could help in debugging.</li> |
392 |
| - <li>Admin: Create a summary page for the script and error logs.</li> |
393 |
| - <li>Wrapper: It's intended that the CGIWrapper class could be embedded in a server and a single instance reused several times. The class is not quite there yet.</li> |
394 |
| - <li>Wrapper: CGI scripts never get cached as byte code (.pyc) which would provide a performance boost.</li> |
395 |
| - <li>Wrapper: The error log columns should be configurable just like the script log columns.</li> |
396 |
| - <li>Code review: Misc functions towards bottom of CGIWrapper</li> |
397 |
| - <li>Code review: Use of _realStdout and sys.stdout on multiple serve() calls.</li> |
398 |
| - <li>Wrapper: Create a subclass of Python's CGI server that uses CGIWrapper. This would include caching the byte code in memory.</li> |
399 |
| - <li>Wrapper: htmlErrorPageFilename() uses a "mostly works" technique that could be better. See source.</li> |
400 |
| - <li>Wrapper: Keep a list of file extensions (such as .py .html .pl) mapped to their handlers. When processing a URL, iterate through the list until a file with that extension is found, then serve it up through its handler.</li> |
401 |
| - <li>Admin: Add password protection on the administration scripts.</li> |
402 |
| - <li>Wrapper: Provide integration (and therefore increased performance) with web servers such as Apache.</li> |
403 |
| - <li>Wrapper: Error e-mails are always in HTML format. It may be useful to have a plain text version for those with more primitive e-mail clients.</li> |
| 389 | + <li>Examples: Make a Cookie example. (In the meantime, just see the main doc string of Cookie.py in WebUtils.)</li> |
| 390 | + <li>Wrapper: When a script produces no output, the CGI Wrapper should report that problem. (This most often happens for class based CGIs with incorrect class names.)</li> |
| 391 | + <li>Wrapper: There should probably be an option to clear the output of a script that raised an uncaught exception. Sometimes that could help in debugging.</li> |
| 392 | + <li>Admin: Create a summary page for the script and error logs.</li> |
| 393 | + <li>Wrapper: It's intended that the CGIWrapper class could be embedded in a server and a single instance reused several times. The class is not quite there yet.</li> |
| 394 | + <li>Wrapper: CGI scripts never get cached as byte code (.pyc) which would provide a performance boost.</li> |
| 395 | + <li>Wrapper: The error log columns should be configurable just like the script log columns.</li> |
| 396 | + <li>Code review: Misc functions towards bottom of CGIWrapper</li> |
| 397 | + <li>Code review: Use of _realStdout and sys.stdout on multiple serve() calls.</li> |
| 398 | + <li>Wrapper: Create a subclass of Python's CGI server that uses CGIWrapper. This would include caching the byte code in memory.</li> |
| 399 | + <li>Wrapper: htmlErrorPageFilename() uses a "mostly works" technique that could be better. See source.</li> |
| 400 | + <li>Wrapper: Keep a list of file extensions (such as .py .html .pl) mapped to their handlers. When processing a URL, iterate through the list until a file with that extension is found, then serve it up through its handler.</li> |
| 401 | + <li>Admin: Add password protection on the administration scripts.</li> |
| 402 | + <li>Wrapper: Provide integration (and therefore increased performance) with web servers such as Apache.</li> |
| 403 | + <li>Wrapper: Error e-mails are always in HTML format. It may be useful to have a plain text version for those with more primitive e-mail clients.</li> |
404 | 404 | </ol>
|
405 | 405 |
|
406 | 406 |
|
|
0 commit comments