Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 1 | \section{Standard Module \sectcode{cgi}} |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 2 | \label{module-cgi} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 3 | \stmodindex{cgi} |
| 4 | \indexii{WWW}{server} |
| 5 | \indexii{CGI}{protocol} |
| 6 | \indexii{HTTP}{protocol} |
| 7 | \indexii{MIME}{headers} |
| 8 | \index{URL} |
| 9 | |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 10 | \renewcommand{\indexsubitem}{(in module cgi)} |
| 11 | |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 12 | Support module for CGI (Common Gateway Interface) scripts. |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 13 | |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 14 | This module defines a number of utilities for use by CGI scripts |
| 15 | written in Python. |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 16 | |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 17 | \subsection{Introduction} |
| 18 | \nodename{Introduction to the CGI module} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 19 | |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 20 | A CGI script is invoked by an HTTP server, usually to process user |
| 21 | input submitted through an HTML \code{<FORM>} or \code{<ISINPUT>} element. |
| 22 | |
Fred Drake | a2e268a | 1997-12-09 03:28:42 +0000 | [diff] [blame] | 23 | Most often, CGI scripts live in the server's special \file{cgi-bin} |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 24 | directory. The HTTP server places all sorts of information about the |
| 25 | request (such as the client's hostname, the requested URL, the query |
| 26 | string, and lots of other goodies) in the script's shell environment, |
| 27 | executes the script, and sends the script's output back to the client. |
| 28 | |
| 29 | The script's input is connected to the client too, and sometimes the |
| 30 | form data is read this way; at other times the form data is passed via |
Fred Drake | a2e268a | 1997-12-09 03:28:42 +0000 | [diff] [blame] | 31 | the ``query string'' part of the URL. This module (\file{cgi.py}) is intended |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 32 | to take care of the different cases and provide a simpler interface to |
| 33 | the Python script. It also provides a number of utilities that help |
| 34 | in debugging scripts, and the latest addition is support for file |
| 35 | uploads from a form (if your browser supports it -- Grail 0.3 and |
| 36 | Netscape 2.0 do). |
| 37 | |
| 38 | The output of a CGI script should consist of two sections, separated |
| 39 | by a blank line. The first section contains a number of headers, |
| 40 | telling the client what kind of data is following. Python code to |
| 41 | generate a minimal header section looks like this: |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 42 | |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 43 | \bcode\begin{verbatim} |
| 44 | print "Content-type: text/html" # HTML is following |
| 45 | print # blank line, end of headers |
| 46 | \end{verbatim}\ecode |
| 47 | % |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 48 | The second section is usually HTML, which allows the client software |
| 49 | to display nicely formatted text with header, in-line images, etc. |
| 50 | Here's Python code that prints a simple piece of HTML: |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 51 | |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 52 | \bcode\begin{verbatim} |
| 53 | print "<TITLE>CGI script output</TITLE>" |
| 54 | print "<H1>This is my first CGI script</H1>" |
| 55 | print "Hello, world!" |
| 56 | \end{verbatim}\ecode |
| 57 | % |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 58 | (It may not be fully legal HTML according to the letter of the |
| 59 | standard, but any browser will understand it.) |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 60 | |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 61 | \subsection{Using the cgi module} |
| 62 | \nodename{Using the cgi module} |
| 63 | |
| 64 | Begin by writing \code{import cgi}. Don't use \code{from cgi import *} -- the |
| 65 | module defines all sorts of names for its own use or for backward |
| 66 | compatibility that you don't want in your namespace. |
| 67 | |
| 68 | It's best to use the \code{FieldStorage} class. The other classes define in this |
| 69 | module are provided mostly for backward compatibility. Instantiate it |
| 70 | exactly once, without arguments. This reads the form contents from |
| 71 | standard input or the environment (depending on the value of various |
| 72 | environment variables set according to the CGI standard). Since it may |
| 73 | consume standard input, it should be instantiated only once. |
| 74 | |
| 75 | The \code{FieldStorage} instance can be accessed as if it were a Python |
| 76 | dictionary. For instance, the following code (which assumes that the |
| 77 | \code{Content-type} header and blank line have already been printed) checks that |
| 78 | the fields \code{name} and \code{addr} are both set to a non-empty string: |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 79 | |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 80 | \bcode\begin{verbatim} |
| 81 | form = cgi.FieldStorage() |
| 82 | form_ok = 0 |
| 83 | if form.has_key("name") and form.has_key("addr"): |
| 84 | if form["name"].value != "" and form["addr"].value != "": |
| 85 | form_ok = 1 |
| 86 | if not form_ok: |
| 87 | print "<H1>Error</H1>" |
| 88 | print "Please fill in the name and addr fields." |
| 89 | return |
| 90 | ...further form processing here... |
| 91 | \end{verbatim}\ecode |
| 92 | % |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 93 | Here the fields, accessed through \code{form[key]}, are themselves instances |
| 94 | of \code{FieldStorage} (or \code{MiniFieldStorage}, depending on the form encoding). |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 95 | |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 96 | If the submitted form data contains more than one field with the same |
| 97 | name, the object retrieved by \code{form[key]} is not a \code{(Mini)FieldStorage} |
| 98 | instance but a list of such instances. If you expect this possibility |
| 99 | (i.e., when your HTML form comtains multiple fields with the same |
| 100 | name), use the \code{type()} function to determine whether you have a single |
| 101 | instance or a list of instances. For example, here's code that |
| 102 | concatenates any number of username fields, separated by commas: |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 103 | |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 104 | \bcode\begin{verbatim} |
| 105 | username = form["username"] |
| 106 | if type(username) is type([]): |
| 107 | # Multiple username fields specified |
| 108 | usernames = "" |
| 109 | for item in username: |
| 110 | if usernames: |
| 111 | # Next item -- insert comma |
| 112 | usernames = usernames + "," + item.value |
| 113 | else: |
| 114 | # First item -- don't insert comma |
| 115 | usernames = item.value |
| 116 | else: |
| 117 | # Single username field specified |
| 118 | usernames = username.value |
| 119 | \end{verbatim}\ecode |
| 120 | % |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 121 | If a field represents an uploaded file, the value attribute reads the |
| 122 | entire file in memory as a string. This may not be what you want. You can |
| 123 | test for an uploaded file by testing either the filename attribute or the |
| 124 | file attribute. You can then read the data at leasure from the file |
| 125 | attribute: |
| 126 | |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 127 | \bcode\begin{verbatim} |
| 128 | fileitem = form["userfile"] |
| 129 | if fileitem.file: |
| 130 | # It's an uploaded file; count lines |
| 131 | linecount = 0 |
| 132 | while 1: |
| 133 | line = fileitem.file.readline() |
| 134 | if not line: break |
| 135 | linecount = linecount + 1 |
| 136 | \end{verbatim}\ecode |
| 137 | % |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 138 | The file upload draft standard entertains the possibility of uploading |
| 139 | multiple files from one field (using a recursive \code{multipart/*} |
| 140 | encoding). When this occurs, the item will be a dictionary-like |
| 141 | FieldStorage item. This can be determined by testing its type |
| 142 | attribute, which should have the value \code{multipart/form-data} (or |
| 143 | perhaps another string beginning with \code{multipart/} It this case, it |
| 144 | can be iterated over recursively just like the top-level form object. |
| 145 | |
| 146 | When a form is submitted in the ``old'' format (as the query string or as a |
| 147 | single data part of type \code{application/x-www-form-urlencoded}), the items |
| 148 | will actually be instances of the class \code{MiniFieldStorage}. In this case, |
| 149 | the list, file and filename attributes are always \code{None}. |
| 150 | |
| 151 | |
| 152 | \subsection{Old classes} |
| 153 | |
| 154 | These classes, present in earlier versions of the \code{cgi} module, are still |
Guido van Rossum | a5a4c2a | 1996-10-24 14:47:44 +0000 | [diff] [blame] | 155 | supported for backward compatibility. New applications should use the |
| 156 | FieldStorage class. |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 157 | |
Guido van Rossum | 81e479a | 1997-08-25 18:28:03 +0000 | [diff] [blame] | 158 | \code{SvFormContentDict} |
| 159 | single value form content as dictionary; assumes each |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 160 | field name occurs in the form only once. |
| 161 | |
Guido van Rossum | 81e479a | 1997-08-25 18:28:03 +0000 | [diff] [blame] | 162 | \code{FormContentDict} |
| 163 | multiple value form content as dictionary (the form |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 164 | items are lists of values). Useful if your form contains multiple |
| 165 | fields with the same name. |
| 166 | |
| 167 | Other classes (\code{FormContent}, \code{InterpFormContentDict}) are present for |
| 168 | backwards compatibility with really old applications only. If you still |
| 169 | use these and would be inconvenienced when they disappeared from a next |
| 170 | version of this module, drop me a note. |
| 171 | |
| 172 | |
| 173 | \subsection{Functions} |
Fred Drake | 4b3f031 | 1996-12-13 22:04:31 +0000 | [diff] [blame] | 174 | \nodename{Functions in cgi module} |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 175 | |
| 176 | These are useful if you want more control, or if you want to employ |
| 177 | some of the algorithms implemented in this module in other |
| 178 | circumstances. |
| 179 | |
Guido van Rossum | 81e479a | 1997-08-25 18:28:03 +0000 | [diff] [blame] | 180 | \begin{funcdesc}{parse}{fp} |
| 181 | Parse a query in the environment or from a file (default \code{sys.stdin}). |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 182 | \end{funcdesc} |
| 183 | |
Guido van Rossum | 81e479a | 1997-08-25 18:28:03 +0000 | [diff] [blame] | 184 | \begin{funcdesc}{parse_qs}{qs} |
| 185 | parse a query string given as a string argument (data of type |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 186 | \code{application/x-www-form-urlencoded}). |
| 187 | \end{funcdesc} |
| 188 | |
Guido van Rossum | 81e479a | 1997-08-25 18:28:03 +0000 | [diff] [blame] | 189 | \begin{funcdesc}{parse_multipart}{fp\, pdict} |
| 190 | parse input of type \code{multipart/form-data} (for |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 191 | file uploads). Arguments are \code{fp} for the input file and |
| 192 | \code{pdict} for the dictionary containing other parameters of \code{content-type} header |
| 193 | |
Guido van Rossum | 81e479a | 1997-08-25 18:28:03 +0000 | [diff] [blame] | 194 | Returns a dictionary just like \code{parse_qs()} |
| 195 | keys are the field names, each |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 196 | value is a list of values for that field. This is easy to use but not |
| 197 | much good if you are expecting megabytes to be uploaded -- in that case, |
| 198 | use the \code{FieldStorage} class instead which is much more flexible. Note |
| 199 | that \code{content-type} is the raw, unparsed contents of the \code{content-type} |
| 200 | header. |
| 201 | |
| 202 | Note that this does not parse nested multipart parts -- use \code{FieldStorage} for |
| 203 | that. |
| 204 | \end{funcdesc} |
| 205 | |
Guido van Rossum | 81e479a | 1997-08-25 18:28:03 +0000 | [diff] [blame] | 206 | \begin{funcdesc}{parse_header}{string} |
| 207 | parse a header like \code{Content-type} into a main |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 208 | content-type and a dictionary of parameters. |
| 209 | \end{funcdesc} |
| 210 | |
Guido van Rossum | 81e479a | 1997-08-25 18:28:03 +0000 | [diff] [blame] | 211 | \begin{funcdesc}{test}{} |
| 212 | robust test CGI script, usable as main program. |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 213 | Writes minimal HTTP headers and formats all information provided to |
| 214 | the script in HTML form. |
| 215 | \end{funcdesc} |
| 216 | |
Guido van Rossum | 81e479a | 1997-08-25 18:28:03 +0000 | [diff] [blame] | 217 | \begin{funcdesc}{print_environ}{} |
| 218 | format the shell environment in HTML. |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 219 | \end{funcdesc} |
| 220 | |
Guido van Rossum | 81e479a | 1997-08-25 18:28:03 +0000 | [diff] [blame] | 221 | \begin{funcdesc}{print_form}{form} |
| 222 | format a form in HTML. |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 223 | \end{funcdesc} |
| 224 | |
Guido van Rossum | 81e479a | 1997-08-25 18:28:03 +0000 | [diff] [blame] | 225 | \begin{funcdesc}{print_directory}{} |
| 226 | format the current directory in HTML. |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 227 | \end{funcdesc} |
| 228 | |
Guido van Rossum | 81e479a | 1997-08-25 18:28:03 +0000 | [diff] [blame] | 229 | \begin{funcdesc}{print_environ_usage}{} |
| 230 | print a list of useful (used by CGI) environment variables in |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 231 | HTML. |
| 232 | \end{funcdesc} |
| 233 | |
Guido van Rossum | 81e479a | 1997-08-25 18:28:03 +0000 | [diff] [blame] | 234 | \begin{funcdesc}{escape}{s\optional{\, quote}} |
| 235 | convert the characters |
Guido van Rossum | 6576dd6 | 1997-07-19 20:16:07 +0000 | [diff] [blame] | 236 | ``\code{\&}'', ``\code{<}'' and ``\code{>}'' in string \var{s} to HTML-safe |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 237 | sequences. Use this if you need to display text that might contain |
Guido van Rossum | 6576dd6 | 1997-07-19 20:16:07 +0000 | [diff] [blame] | 238 | such characters in HTML. If the optional flag \var{quote} is true, |
| 239 | the double quote character (\code{"}) is also translated; this helps |
| 240 | for inclusion in an HTML attribute value, e.g. in ``\code{<A HREF="...">}''. |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 241 | \end{funcdesc} |
| 242 | |
| 243 | |
| 244 | \subsection{Caring about security} |
| 245 | |
| 246 | There's one important rule: if you invoke an external program (e.g. |
| 247 | via the \code{os.system()} or \code{os.popen()} functions), make very sure you don't |
| 248 | pass arbitrary strings received from the client to the shell. This is |
| 249 | a well-known security hole whereby clever hackers anywhere on the web |
| 250 | can exploit a gullible CGI script to invoke arbitrary shell commands. |
| 251 | Even parts of the URL or field names cannot be trusted, since the |
| 252 | request doesn't have to come from your form! |
| 253 | |
| 254 | To be on the safe side, if you must pass a string gotten from a form |
| 255 | to a shell command, you should make sure the string contains only |
| 256 | alphanumeric characters, dashes, underscores, and periods. |
| 257 | |
| 258 | |
| 259 | \subsection{Installing your CGI script on a Unix system} |
| 260 | |
| 261 | Read the documentation for your HTTP server and check with your local |
| 262 | system administrator to find the directory where CGI scripts should be |
Fred Drake | a2e268a | 1997-12-09 03:28:42 +0000 | [diff] [blame] | 263 | installed; usually this is in a directory \file{cgi-bin} in the server tree. |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 264 | |
| 265 | Make sure that your script is readable and executable by ``others''; the |
Fred Drake | efc1e0f | 1998-01-13 19:00:33 +0000 | [diff] [blame] | 266 | \UNIX{} file mode should be 755 (use \code{chmod 755 filename}). Make sure |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 267 | that the first line of the script contains \code{\#!} starting in column 1 |
| 268 | followed by the pathname of the Python interpreter, for instance: |
| 269 | |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 270 | \bcode\begin{verbatim} |
| 271 | #!/usr/local/bin/python |
| 272 | \end{verbatim}\ecode |
| 273 | % |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 274 | Make sure the Python interpreter exists and is executable by ``others''. |
| 275 | |
| 276 | Make sure that any files your script needs to read or write are |
| 277 | readable or writable, respectively, by ``others'' -- their mode should |
| 278 | be 644 for readable and 666 for writable. This is because, for |
| 279 | security reasons, the HTTP server executes your script as user |
| 280 | ``nobody'', without any special privileges. It can only read (write, |
| 281 | execute) files that everybody can read (write, execute). The current |
| 282 | directory at execution time is also different (it is usually the |
| 283 | server's cgi-bin directory) and the set of environment variables is |
| 284 | also different from what you get at login. in particular, don't count |
| 285 | on the shell's search path for executables (\code{\$PATH}) or the Python |
| 286 | module search path (\code{\$PYTHONPATH}) to be set to anything interesting. |
| 287 | |
| 288 | If you need to load modules from a directory which is not on Python's |
| 289 | default module search path, you can change the path in your script, |
| 290 | before importing other modules, e.g.: |
| 291 | |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 292 | \bcode\begin{verbatim} |
| 293 | import sys |
| 294 | sys.path.insert(0, "/usr/home/joe/lib/python") |
| 295 | sys.path.insert(0, "/usr/local/lib/python") |
| 296 | \end{verbatim}\ecode |
| 297 | % |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 298 | (This way, the directory inserted last will be searched first!) |
| 299 | |
Fred Drake | efc1e0f | 1998-01-13 19:00:33 +0000 | [diff] [blame] | 300 | Instructions for non-\UNIX{} systems will vary; check your HTTP server's |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 301 | documentation (it will usually have a section on CGI scripts). |
| 302 | |
| 303 | |
| 304 | \subsection{Testing your CGI script} |
| 305 | |
| 306 | Unfortunately, a CGI script will generally not run when you try it |
| 307 | from the command line, and a script that works perfectly from the |
| 308 | command line may fail mysteriously when run from the server. There's |
| 309 | one reason why you should still test your script from the command |
| 310 | line: if it contains a syntax error, the python interpreter won't |
| 311 | execute it at all, and the HTTP server will most likely send a cryptic |
| 312 | error to the client. |
| 313 | |
| 314 | Assuming your script has no syntax errors, yet it does not work, you |
| 315 | have no choice but to read the next section: |
| 316 | |
| 317 | |
| 318 | \subsection{Debugging CGI scripts} |
| 319 | |
| 320 | First of all, check for trivial installation errors -- reading the |
| 321 | section above on installing your CGI script carefully can save you a |
| 322 | lot of time. If you wonder whether you have understood the |
| 323 | installation procedure correctly, try installing a copy of this module |
Fred Drake | a2e268a | 1997-12-09 03:28:42 +0000 | [diff] [blame] | 324 | file (\file{cgi.py}) as a CGI script. When invoked as a script, the file |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 325 | will dump its environment and the contents of the form in HTML form. |
| 326 | Give it the right mode etc, and send it a request. If it's installed |
Fred Drake | a2e268a | 1997-12-09 03:28:42 +0000 | [diff] [blame] | 327 | in the standard \file{cgi-bin} directory, it should be possible to send it a |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 328 | request by entering a URL into your browser of the form: |
| 329 | |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 330 | \bcode\begin{verbatim} |
| 331 | http://yourhostname/cgi-bin/cgi.py?name=Joe+Blow&addr=At+Home |
| 332 | \end{verbatim}\ecode |
| 333 | % |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 334 | If this gives an error of type 404, the server cannot find the script |
| 335 | -- perhaps you need to install it in a different directory. If it |
| 336 | gives another error (e.g. 500), there's an installation problem that |
| 337 | you should fix before trying to go any further. If you get a nicely |
| 338 | formatted listing of the environment and form content (in this |
| 339 | example, the fields should be listed as ``addr'' with value ``At Home'' |
Fred Drake | a2e268a | 1997-12-09 03:28:42 +0000 | [diff] [blame] | 340 | and ``name'' with value ``Joe Blow''), the \file{cgi.py} script has been |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 341 | installed correctly. If you follow the same procedure for your own |
| 342 | script, you should now be able to debug it. |
| 343 | |
Fred Drake | a2e268a | 1997-12-09 03:28:42 +0000 | [diff] [blame] | 344 | The next step could be to call the \code{cgi} module's \code{test()} |
| 345 | function from your script: replace its main code with the single |
| 346 | statement |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 347 | |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 348 | \bcode\begin{verbatim} |
| 349 | cgi.test() |
| 350 | \end{verbatim}\ecode |
| 351 | % |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 352 | This should produce the same results as those gotten from installing |
Fred Drake | a2e268a | 1997-12-09 03:28:42 +0000 | [diff] [blame] | 353 | the \file{cgi.py} file itself. |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 354 | |
| 355 | When an ordinary Python script raises an unhandled exception |
| 356 | (e.g. because of a typo in a module name, a file that can't be opened, |
| 357 | etc.), the Python interpreter prints a nice traceback and exits. |
| 358 | While the Python interpreter will still do this when your CGI script |
| 359 | raises an exception, most likely the traceback will end up in one of |
| 360 | the HTTP server's log file, or be discarded altogether. |
| 361 | |
| 362 | Fortunately, once you have managed to get your script to execute |
| 363 | *some* code, it is easy to catch exceptions and cause a traceback to |
| 364 | be printed. The \code{test()} function below in this module is an example. |
| 365 | Here are the rules: |
| 366 | |
| 367 | \begin{enumerate} |
| 368 | \item Import the traceback module (before entering the |
| 369 | try-except!) |
| 370 | |
| 371 | \item Make sure you finish printing the headers and the blank |
| 372 | line early |
| 373 | |
| 374 | \item Assign \code{sys.stderr} to \code{sys.stdout} |
| 375 | |
| 376 | \item Wrap all remaining code in a try-except statement |
| 377 | |
| 378 | \item In the except clause, call \code{traceback.print_exc()} |
| 379 | \end{enumerate} |
| 380 | |
| 381 | For example: |
| 382 | |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 383 | \bcode\begin{verbatim} |
| 384 | import sys |
| 385 | import traceback |
| 386 | print "Content-type: text/html" |
| 387 | print |
| 388 | sys.stderr = sys.stdout |
| 389 | try: |
| 390 | ...your code here... |
| 391 | except: |
| 392 | print "\n\n<PRE>" |
| 393 | traceback.print_exc() |
| 394 | \end{verbatim}\ecode |
| 395 | % |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 396 | Notes: The assignment to \code{sys.stderr} is needed because the traceback |
Guido van Rossum | 9d62e80 | 1997-11-25 00:35:44 +0000 | [diff] [blame] | 397 | prints to \code{sys.stderr}. |
| 398 | The \code{print "{\e}n{\e}n<PRE>"} statement is necessary to |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 399 | disable the word wrapping in HTML. |
| 400 | |
| 401 | If you suspect that there may be a problem in importing the traceback |
| 402 | module, you can use an even more robust approach (which only uses |
| 403 | built-in modules): |
| 404 | |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 405 | \bcode\begin{verbatim} |
| 406 | import sys |
| 407 | sys.stderr = sys.stdout |
| 408 | print "Content-type: text/plain" |
| 409 | print |
| 410 | ...your code here... |
| 411 | \end{verbatim}\ecode |
| 412 | % |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 413 | This relies on the Python interpreter to print the traceback. The |
| 414 | content type of the output is set to plain text, which disables all |
| 415 | HTML processing. If your script works, the raw HTML will be displayed |
| 416 | by your client. If it raises an exception, most likely after the |
| 417 | first two lines have been printed, a traceback will be displayed. |
| 418 | Because no HTML interpretation is going on, the traceback will |
| 419 | readable. |
| 420 | |
| 421 | |
| 422 | \subsection{Common problems and solutions} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 423 | |
| 424 | \begin{itemize} |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 425 | \item Most HTTP servers buffer the output from CGI scripts until the |
| 426 | script is completed. This means that it is not possible to display a |
| 427 | progress report on the client's display while the script is running. |
| 428 | |
| 429 | \item Check the installation instructions above. |
| 430 | |
| 431 | \item Check the HTTP server's log files. (\code{tail -f logfile} in a separate |
| 432 | window may be useful!) |
| 433 | |
| 434 | \item Always check a script for syntax errors first, by doing something |
| 435 | like \code{python script.py}. |
| 436 | |
| 437 | \item When using any of the debugging techniques, don't forget to add |
| 438 | \code{import sys} to the top of the script. |
| 439 | |
| 440 | \item When invoking external programs, make sure they can be found. |
| 441 | Usually, this means using absolute path names -- \code{\$PATH} is usually not |
| 442 | set to a very useful value in a CGI script. |
| 443 | |
| 444 | \item When reading or writing external files, make sure they can be read |
| 445 | or written by every user on the system. |
| 446 | |
| 447 | \item Don't try to give a CGI script a set-uid mode. This doesn't work on |
| 448 | most systems, and is a security liability as well. |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 449 | \end{itemize} |
| 450 | |