Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame] | 1 | \section{\module{cgi} --- |
| 2 | Common Gateway Interface support.} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 3 | \declaremodule{standard}{cgi} |
| 4 | |
Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame] | 5 | \modulesynopsis{Common Gateway Interface support, used to interpret |
| 6 | forms in server-side scripts.} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 7 | |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 8 | \indexii{WWW}{server} |
| 9 | \indexii{CGI}{protocol} |
| 10 | \indexii{HTTP}{protocol} |
| 11 | \indexii{MIME}{headers} |
| 12 | \index{URL} |
| 13 | |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 14 | |
Fred Drake | 8ee679f | 2001-07-14 02:50:55 +0000 | [diff] [blame] | 15 | Support module for Common Gateway Interface (CGI) scripts.% |
Fred Drake | 6a79be8 | 1998-04-03 03:47:03 +0000 | [diff] [blame] | 16 | \index{Common Gateway Interface} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 17 | |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 18 | This module defines a number of utilities for use by CGI scripts |
| 19 | written in Python. |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 20 | |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 21 | \subsection{Introduction} |
Fred Drake | 12d9fc9 | 1998-04-14 17:19:54 +0000 | [diff] [blame] | 22 | \nodename{cgi-intro} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 23 | |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 24 | A CGI script is invoked by an HTTP server, usually to process user |
Fred Drake | 637af13 | 1998-08-21 20:02:06 +0000 | [diff] [blame] | 25 | input submitted through an HTML \code{<FORM>} or \code{<ISINDEX>} element. |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 26 | |
Fred Drake | a2e268a | 1997-12-09 03:28:42 +0000 | [diff] [blame] | 27 | 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] | 28 | directory. The HTTP server places all sorts of information about the |
| 29 | request (such as the client's hostname, the requested URL, the query |
| 30 | string, and lots of other goodies) in the script's shell environment, |
| 31 | executes the script, and sends the script's output back to the client. |
| 32 | |
| 33 | The script's input is connected to the client too, and sometimes the |
| 34 | form data is read this way; at other times the form data is passed via |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 35 | the ``query string'' part of the URL. This module is intended |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 36 | to take care of the different cases and provide a simpler interface to |
| 37 | the Python script. It also provides a number of utilities that help |
| 38 | in debugging scripts, and the latest addition is support for file |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 39 | uploads from a form (if your browser supports it --- Grail 0.3 and |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 40 | Netscape 2.0 do). |
| 41 | |
| 42 | The output of a CGI script should consist of two sections, separated |
| 43 | by a blank line. The first section contains a number of headers, |
| 44 | telling the client what kind of data is following. Python code to |
| 45 | generate a minimal header section looks like this: |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 46 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 47 | \begin{verbatim} |
Moshe Zadka | a1a4b59 | 2000-08-25 21:47:56 +0000 | [diff] [blame] | 48 | print "Content-Type: text/html" # HTML is following |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 49 | print # blank line, end of headers |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 50 | \end{verbatim} |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 51 | |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 52 | The second section is usually HTML, which allows the client software |
| 53 | to display nicely formatted text with header, in-line images, etc. |
| 54 | Here's Python code that prints a simple piece of HTML: |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 55 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 56 | \begin{verbatim} |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 57 | print "<TITLE>CGI script output</TITLE>" |
| 58 | print "<H1>This is my first CGI script</H1>" |
| 59 | print "Hello, world!" |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 60 | \end{verbatim} |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 61 | |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 62 | \subsection{Using the cgi module} |
| 63 | \nodename{Using the cgi module} |
| 64 | |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 65 | Begin by writing \samp{import cgi}. Do not use \samp{from cgi import |
| 66 | *} --- the module defines all sorts of names for its own use or for |
| 67 | backward compatibility that you don't want in your namespace. |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 68 | |
Fred Drake | 34a37b8 | 2001-12-20 17:13:09 +0000 | [diff] [blame] | 69 | When you write a new script, consider adding the line: |
| 70 | |
| 71 | \begin{verbatim} |
| 72 | import cgitb; cgitb.enable() |
| 73 | \end{verbatim} |
| 74 | |
| 75 | This activates a special exception handler that will display detailed |
| 76 | reports in the Web browser if any errors occur. If you'd rather not |
| 77 | show the guts of your program to users of your script, you can have |
| 78 | the reports saved to files instead, with a line like this: |
| 79 | |
| 80 | \begin{verbatim} |
| 81 | import cgitb; cgitb.enable(display=0, logdir="/tmp") |
| 82 | \end{verbatim} |
| 83 | |
| 84 | It's very helpful to use this feature during script development. |
| 85 | The reports produced by \refmodule{cgitb} provide information that |
| 86 | can save you a lot of time in tracking down bugs. You can always |
| 87 | remove the \code{cgitb} line later when you have tested your script |
| 88 | and are confident that it works correctly. |
| 89 | |
| 90 | To get at submitted form data, |
| 91 | it's best to use the \class{FieldStorage} class. The other classes |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 92 | defined in this module are provided mostly for backward compatibility. |
| 93 | Instantiate it exactly once, without arguments. This reads the form |
| 94 | contents from standard input or the environment (depending on the |
| 95 | value of various environment variables set according to the CGI |
| 96 | standard). Since it may consume standard input, it should be |
| 97 | instantiated only once. |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 98 | |
Moshe Zadka | a1a4b59 | 2000-08-25 21:47:56 +0000 | [diff] [blame] | 99 | The \class{FieldStorage} instance can be indexed like a Python |
| 100 | dictionary, and also supports the standard dictionary methods |
Fred Drake | 84e58ab | 2001-08-11 03:28:41 +0000 | [diff] [blame] | 101 | \method{has_key()} and \method{keys()}. The built-in \function{len()} |
| 102 | is also supported. Form fields containing empty strings are ignored |
Moshe Zadka | a1a4b59 | 2000-08-25 21:47:56 +0000 | [diff] [blame] | 103 | and do not appear in the dictionary; to keep such values, provide |
Raymond Hettinger | f17d65d | 2003-08-12 00:01:16 +0000 | [diff] [blame] | 104 | a true value for the optional \var{keep_blank_values} keyword |
Fred Drake | 84e58ab | 2001-08-11 03:28:41 +0000 | [diff] [blame] | 105 | parameter when creating the \class{FieldStorage} instance. |
Moshe Zadka | a1a4b59 | 2000-08-25 21:47:56 +0000 | [diff] [blame] | 106 | |
| 107 | For instance, the following code (which assumes that the |
Fred Drake | 84e58ab | 2001-08-11 03:28:41 +0000 | [diff] [blame] | 108 | \mailheader{Content-Type} header and blank line have already been |
| 109 | printed) checks that the fields \code{name} and \code{addr} are both |
| 110 | set to a non-empty string: |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 111 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 112 | \begin{verbatim} |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 113 | form = cgi.FieldStorage() |
Fred Drake | 9f9bd6a | 2001-06-29 14:59:01 +0000 | [diff] [blame] | 114 | if not (form.has_key("name") and form.has_key("addr")): |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 115 | print "<H1>Error</H1>" |
| 116 | print "Please fill in the name and addr fields." |
| 117 | return |
Moshe Zadka | a1a4b59 | 2000-08-25 21:47:56 +0000 | [diff] [blame] | 118 | print "<p>name:", form["name"].value |
| 119 | print "<p>addr:", form["addr"].value |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 120 | ...further form processing here... |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 121 | \end{verbatim} |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 122 | |
| 123 | Here the fields, accessed through \samp{form[\var{key}]}, are |
| 124 | themselves instances of \class{FieldStorage} (or |
| 125 | \class{MiniFieldStorage}, depending on the form encoding). |
Moshe Zadka | a1a4b59 | 2000-08-25 21:47:56 +0000 | [diff] [blame] | 126 | The \member{value} attribute of the instance yields the string value |
Fred Drake | 84e58ab | 2001-08-11 03:28:41 +0000 | [diff] [blame] | 127 | of the field. The \method{getvalue()} method returns this string value |
Moshe Zadka | a1a4b59 | 2000-08-25 21:47:56 +0000 | [diff] [blame] | 128 | directly; it also accepts an optional second argument as a default to |
| 129 | return if the requested key is not present. |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 130 | |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 131 | If the submitted form data contains more than one field with the same |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 132 | name, the object retrieved by \samp{form[\var{key}]} is not a |
| 133 | \class{FieldStorage} or \class{MiniFieldStorage} |
Moshe Zadka | a1a4b59 | 2000-08-25 21:47:56 +0000 | [diff] [blame] | 134 | instance but a list of such instances. Similarly, in this situation, |
| 135 | \samp{form.getvalue(\var{key})} would return a list of strings. |
| 136 | If you expect this possibility |
Fred Drake | 84e58ab | 2001-08-11 03:28:41 +0000 | [diff] [blame] | 137 | (when your HTML form contains multiple fields with the same name), use |
Andrew M. Kuchling | 44cbfd7 | 2004-06-06 23:28:23 +0000 | [diff] [blame] | 138 | the \function{getlist()} function, which always returns a list of values (so that you |
| 139 | do not need to special-case the single item case). For example, this |
Fred Drake | 84e58ab | 2001-08-11 03:28:41 +0000 | [diff] [blame] | 140 | code concatenates any number of username fields, separated by |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 141 | commas: |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 142 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 143 | \begin{verbatim} |
Andrew M. Kuchling | 44cbfd7 | 2004-06-06 23:28:23 +0000 | [diff] [blame] | 144 | value = form.getlist("username") |
| 145 | usernames = ",".join(value) |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 146 | \end{verbatim} |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 147 | |
Moshe Zadka | a1a4b59 | 2000-08-25 21:47:56 +0000 | [diff] [blame] | 148 | If a field represents an uploaded file, accessing the value via the |
| 149 | \member{value} attribute or the \function{getvalue()} method reads the |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 150 | entire file in memory as a string. This may not be what you want. |
Moshe Zadka | a1a4b59 | 2000-08-25 21:47:56 +0000 | [diff] [blame] | 151 | You can test for an uploaded file by testing either the \member{filename} |
| 152 | attribute or the \member{file} attribute. You can then read the data at |
| 153 | leisure from the \member{file} attribute: |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 154 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 155 | \begin{verbatim} |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 156 | fileitem = form["userfile"] |
| 157 | if fileitem.file: |
| 158 | # It's an uploaded file; count lines |
| 159 | linecount = 0 |
| 160 | while 1: |
| 161 | line = fileitem.file.readline() |
| 162 | if not line: break |
| 163 | linecount = linecount + 1 |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 164 | \end{verbatim} |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 165 | |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 166 | The file upload draft standard entertains the possibility of uploading |
| 167 | multiple files from one field (using a recursive |
| 168 | \mimetype{multipart/*} encoding). When this occurs, the item will be |
| 169 | a dictionary-like \class{FieldStorage} item. This can be determined |
| 170 | by testing its \member{type} attribute, which should be |
| 171 | \mimetype{multipart/form-data} (or perhaps another MIME type matching |
Fred Drake | 7eca8e5 | 1999-01-18 15:46:02 +0000 | [diff] [blame] | 172 | \mimetype{multipart/*}). In this case, it can be iterated over |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 173 | recursively just like the top-level form object. |
| 174 | |
| 175 | When a form is submitted in the ``old'' format (as the query string or |
| 176 | as a single data part of type |
| 177 | \mimetype{application/x-www-form-urlencoded}), the items will actually |
| 178 | be instances of the class \class{MiniFieldStorage}. In this case, the |
Moshe Zadka | a1a4b59 | 2000-08-25 21:47:56 +0000 | [diff] [blame] | 179 | \member{list}, \member{file}, and \member{filename} attributes are |
| 180 | always \code{None}. |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 181 | |
| 182 | |
Fred Drake | 2732cb4 | 2001-09-11 16:27:03 +0000 | [diff] [blame] | 183 | \subsection{Higher Level Interface} |
| 184 | |
| 185 | \versionadded{2.2} % XXX: Is this true ? |
| 186 | |
| 187 | The previous section explains how to read CGI form data using the |
| 188 | \class{FieldStorage} class. This section describes a higher level |
| 189 | interface which was added to this class to allow one to do it in a |
| 190 | more readable and intuitive way. The interface doesn't make the |
| 191 | techniques described in previous sections obsolete --- they are still |
| 192 | useful to process file uploads efficiently, for example. |
| 193 | |
| 194 | The interface consists of two simple methods. Using the methods |
| 195 | you can process form data in a generic way, without the need to worry |
| 196 | whether only one or more values were posted under one name. |
| 197 | |
| 198 | In the previous section, you learned to write following code anytime |
| 199 | you expected a user to post more than one value under one name: |
| 200 | |
| 201 | \begin{verbatim} |
Fred Drake | 2732cb4 | 2001-09-11 16:27:03 +0000 | [diff] [blame] | 202 | item = form.getvalue("item") |
Fred Drake | 5b09eee | 2002-08-21 19:24:21 +0000 | [diff] [blame] | 203 | if isinstance(item, list): |
Fred Drake | 2732cb4 | 2001-09-11 16:27:03 +0000 | [diff] [blame] | 204 | # The user is requesting more than one item. |
| 205 | else: |
| 206 | # The user is requesting only one item. |
| 207 | \end{verbatim} |
| 208 | |
| 209 | This situation is common for example when a form contains a group of |
| 210 | multiple checkboxes with the same name: |
| 211 | |
| 212 | \begin{verbatim} |
| 213 | <input type="checkbox" name="item" value="1" /> |
| 214 | <input type="checkbox" name="item" value="2" /> |
| 215 | \end{verbatim} |
| 216 | |
| 217 | In most situations, however, there's only one form control with a |
| 218 | particular name in a form and then you expect and need only one value |
| 219 | associated with this name. So you write a script containing for |
| 220 | example this code: |
| 221 | |
| 222 | \begin{verbatim} |
Fred Drake | 226f697 | 2004-01-23 04:05:27 +0000 | [diff] [blame] | 223 | user = form.getvalue("user").upper() |
Fred Drake | 2732cb4 | 2001-09-11 16:27:03 +0000 | [diff] [blame] | 224 | \end{verbatim} |
| 225 | |
| 226 | The problem with the code is that you should never expect that a |
| 227 | client will provide valid input to your scripts. For example, if a |
| 228 | curious user appends another \samp{user=foo} pair to the query string, |
| 229 | then the script would crash, because in this situation the |
| 230 | \code{getvalue("user")} method call returns a list instead of a |
| 231 | string. Calling the \method{toupper()} method on a list is not valid |
| 232 | (since lists do not have a method of this name) and results in an |
| 233 | \exception{AttributeError} exception. |
| 234 | |
| 235 | Therefore, the appropriate way to read form data values was to always |
| 236 | use the code which checks whether the obtained value is a single value |
| 237 | or a list of values. That's annoying and leads to less readable |
| 238 | scripts. |
| 239 | |
| 240 | A more convenient approach is to use the methods \method{getfirst()} |
| 241 | and \method{getlist()} provided by this higher level interface. |
| 242 | |
| 243 | \begin{methoddesc}[FieldStorage]{getfirst}{name\optional{, default}} |
| 244 | Thin method always returns only one value associated with form field |
| 245 | \var{name}. The method returns only the first value in case that |
| 246 | more values were posted under such name. Please note that the order |
| 247 | in which the values are received may vary from browser to browser |
Fred Drake | 5b09eee | 2002-08-21 19:24:21 +0000 | [diff] [blame] | 248 | and should not be counted on.\footnote{Note that some recent |
| 249 | versions of the HTML specification do state what order the |
| 250 | field values should be supplied in, but knowing whether a |
| 251 | request was received from a conforming browser, or even from a |
| 252 | browser at all, is tedious and error-prone.} If no such form |
| 253 | field or value exists then the method returns the value specified by |
| 254 | the optional parameter \var{default}. This parameter defaults to |
| 255 | \code{None} if not specified. |
Fred Drake | 2732cb4 | 2001-09-11 16:27:03 +0000 | [diff] [blame] | 256 | \end{methoddesc} |
| 257 | |
| 258 | \begin{methoddesc}[FieldStorage]{getlist}{name} |
| 259 | This method always returns a list of values associated with form |
| 260 | field \var{name}. The method returns an empty list if no such form |
| 261 | field or value exists for \var{name}. It returns a list consisting |
| 262 | of one item if only one such value exists. |
| 263 | \end{methoddesc} |
| 264 | |
| 265 | Using these methods you can write nice compact code: |
| 266 | |
| 267 | \begin{verbatim} |
| 268 | import cgi |
| 269 | form = cgi.FieldStorage() |
Fred Drake | 226f697 | 2004-01-23 04:05:27 +0000 | [diff] [blame] | 270 | user = form.getfirst("user", "").upper() # This way it's safe. |
Fred Drake | 2732cb4 | 2001-09-11 16:27:03 +0000 | [diff] [blame] | 271 | for item in form.getlist("item"): |
| 272 | do_something(item) |
| 273 | \end{verbatim} |
| 274 | |
| 275 | |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 276 | \subsection{Old classes} |
| 277 | |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 278 | These classes, present in earlier versions of the \module{cgi} module, |
| 279 | are still supported for backward compatibility. New applications |
| 280 | should use the \class{FieldStorage} class. |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 281 | |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 282 | \class{SvFormContentDict} stores single value form content as |
| 283 | dictionary; it assumes each field name occurs in the form only once. |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 284 | |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 285 | \class{FormContentDict} stores multiple value form content as a |
| 286 | dictionary (the form items are lists of values). Useful if your form |
| 287 | contains multiple fields with the same name. |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 288 | |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 289 | Other classes (\class{FormContent}, \class{InterpFormContentDict}) are |
| 290 | present for backwards compatibility with really old applications only. |
| 291 | If you still use these and would be inconvenienced when they |
| 292 | disappeared from a next version of this module, drop me a note. |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 293 | |
| 294 | |
| 295 | \subsection{Functions} |
Fred Drake | 4b3f031 | 1996-12-13 22:04:31 +0000 | [diff] [blame] | 296 | \nodename{Functions in cgi module} |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 297 | |
| 298 | These are useful if you want more control, or if you want to employ |
| 299 | some of the algorithms implemented in this module in other |
| 300 | circumstances. |
| 301 | |
Fred Drake | 2732cb4 | 2001-09-11 16:27:03 +0000 | [diff] [blame] | 302 | \begin{funcdesc}{parse}{fp\optional{, keep_blank_values\optional{, |
| 303 | strict_parsing}}} |
| 304 | Parse a query in the environment or from a file (the file defaults |
| 305 | to \code{sys.stdin}). The \var{keep_blank_values} and |
| 306 | \var{strict_parsing} parameters are passed to \function{parse_qs()} |
| 307 | unchanged. |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 308 | \end{funcdesc} |
| 309 | |
Fred Drake | 2732cb4 | 2001-09-11 16:27:03 +0000 | [diff] [blame] | 310 | \begin{funcdesc}{parse_qs}{qs\optional{, keep_blank_values\optional{, |
| 311 | strict_parsing}}} |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 312 | Parse a query string given as a string argument (data of type |
Guido van Rossum | 66ab4e8 | 1999-06-10 03:11:41 +0000 | [diff] [blame] | 313 | \mimetype{application/x-www-form-urlencoded}). Data are |
| 314 | returned as a dictionary. The dictionary keys are the unique query |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 315 | variable names and the values are lists of values for each name. |
Guido van Rossum | 66ab4e8 | 1999-06-10 03:11:41 +0000 | [diff] [blame] | 316 | |
| 317 | The optional argument \var{keep_blank_values} is |
| 318 | a flag indicating whether blank values in |
| 319 | URL encoded queries should be treated as blank strings. |
| 320 | A true value indicates that blanks should be retained as |
| 321 | blank strings. The default false value indicates that |
| 322 | blank values are to be ignored and treated as if they were |
| 323 | not included. |
| 324 | |
| 325 | The optional argument \var{strict_parsing} is a flag indicating what |
| 326 | to do with parsing errors. If false (the default), errors |
| 327 | are silently ignored. If true, errors raise a ValueError |
| 328 | exception. |
Brett Cannon | 1213bdd | 2003-05-13 02:50:36 +0000 | [diff] [blame] | 329 | |
| 330 | Use the \function{\refmodule{urllib}.urlencode()} function to convert |
| 331 | such dictionaries into query strings. |
| 332 | |
Guido van Rossum | 66ab4e8 | 1999-06-10 03:11:41 +0000 | [diff] [blame] | 333 | \end{funcdesc} |
| 334 | |
Fred Drake | 2732cb4 | 2001-09-11 16:27:03 +0000 | [diff] [blame] | 335 | \begin{funcdesc}{parse_qsl}{qs\optional{, keep_blank_values\optional{, |
| 336 | strict_parsing}}} |
Guido van Rossum | 66ab4e8 | 1999-06-10 03:11:41 +0000 | [diff] [blame] | 337 | Parse a query string given as a string argument (data of type |
| 338 | \mimetype{application/x-www-form-urlencoded}). Data are |
| 339 | returned as a list of name, value pairs. |
| 340 | |
| 341 | The optional argument \var{keep_blank_values} is |
| 342 | a flag indicating whether blank values in |
| 343 | URL encoded queries should be treated as blank strings. |
| 344 | A true value indicates that blanks should be retained as |
| 345 | blank strings. The default false value indicates that |
| 346 | blank values are to be ignored and treated as if they were |
| 347 | not included. |
| 348 | |
| 349 | The optional argument \var{strict_parsing} is a flag indicating what |
| 350 | to do with parsing errors. If false (the default), errors |
| 351 | are silently ignored. If true, errors raise a ValueError |
| 352 | exception. |
Fred Drake | d859d47 | 2003-04-24 16:22:47 +0000 | [diff] [blame] | 353 | |
Brett Cannon | 1213bdd | 2003-05-13 02:50:36 +0000 | [diff] [blame] | 354 | Use the \function{\refmodule{urllib}.urlencode()} function to convert |
Fred Drake | d859d47 | 2003-04-24 16:22:47 +0000 | [diff] [blame] | 355 | such lists of pairs into query strings. |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 356 | \end{funcdesc} |
| 357 | |
Fred Drake | cce1090 | 1998-03-17 06:33:25 +0000 | [diff] [blame] | 358 | \begin{funcdesc}{parse_multipart}{fp, pdict} |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 359 | Parse input of type \mimetype{multipart/form-data} (for |
| 360 | file uploads). Arguments are \var{fp} for the input file and |
Moshe Zadka | a1a4b59 | 2000-08-25 21:47:56 +0000 | [diff] [blame] | 361 | \var{pdict} for a dictionary containing other parameters in |
Fred Drake | 84e58ab | 2001-08-11 03:28:41 +0000 | [diff] [blame] | 362 | the \mailheader{Content-Type} header. |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 363 | |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 364 | Returns a dictionary just like \function{parse_qs()} keys are the |
| 365 | field names, each value is a list of values for that field. This is |
| 366 | easy to use but not much good if you are expecting megabytes to be |
| 367 | uploaded --- in that case, use the \class{FieldStorage} class instead |
Moshe Zadka | a1a4b59 | 2000-08-25 21:47:56 +0000 | [diff] [blame] | 368 | which is much more flexible. |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 369 | |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 370 | Note that this does not parse nested multipart parts --- use |
| 371 | \class{FieldStorage} for that. |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 372 | \end{funcdesc} |
| 373 | |
Guido van Rossum | 81e479a | 1997-08-25 18:28:03 +0000 | [diff] [blame] | 374 | \begin{funcdesc}{parse_header}{string} |
Fred Drake | 84e58ab | 2001-08-11 03:28:41 +0000 | [diff] [blame] | 375 | Parse a MIME header (such as \mailheader{Content-Type}) into a main |
Moshe Zadka | a1a4b59 | 2000-08-25 21:47:56 +0000 | [diff] [blame] | 376 | value and a dictionary of parameters. |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 377 | \end{funcdesc} |
| 378 | |
Guido van Rossum | 81e479a | 1997-08-25 18:28:03 +0000 | [diff] [blame] | 379 | \begin{funcdesc}{test}{} |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 380 | Robust test CGI script, usable as main program. |
| 381 | Writes minimal HTTP headers and formats all information provided to |
| 382 | the script in HTML form. |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 383 | \end{funcdesc} |
| 384 | |
Guido van Rossum | 81e479a | 1997-08-25 18:28:03 +0000 | [diff] [blame] | 385 | \begin{funcdesc}{print_environ}{} |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 386 | Format the shell environment in HTML. |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 387 | \end{funcdesc} |
| 388 | |
Guido van Rossum | 81e479a | 1997-08-25 18:28:03 +0000 | [diff] [blame] | 389 | \begin{funcdesc}{print_form}{form} |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 390 | Format a form in HTML. |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 391 | \end{funcdesc} |
| 392 | |
Guido van Rossum | 81e479a | 1997-08-25 18:28:03 +0000 | [diff] [blame] | 393 | \begin{funcdesc}{print_directory}{} |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 394 | Format the current directory in HTML. |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 395 | \end{funcdesc} |
| 396 | |
Guido van Rossum | 81e479a | 1997-08-25 18:28:03 +0000 | [diff] [blame] | 397 | \begin{funcdesc}{print_environ_usage}{} |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 398 | Print a list of useful (used by CGI) environment variables in |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 399 | HTML. |
| 400 | \end{funcdesc} |
| 401 | |
Fred Drake | cce1090 | 1998-03-17 06:33:25 +0000 | [diff] [blame] | 402 | \begin{funcdesc}{escape}{s\optional{, quote}} |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 403 | Convert the characters |
| 404 | \character{\&}, \character{<} and \character{>} in string \var{s} to |
| 405 | HTML-safe sequences. Use this if you need to display text that might |
| 406 | contain such characters in HTML. If the optional flag \var{quote} is |
Fred Drake | 84e58ab | 2001-08-11 03:28:41 +0000 | [diff] [blame] | 407 | true, the double-quote character (\character{"}) is also translated; |
Fred Drake | 91f2f26 | 2001-07-06 19:28:48 +0000 | [diff] [blame] | 408 | this helps for inclusion in an HTML attribute value, as in \code{<A |
Fred Drake | 055be47 | 2002-08-23 21:19:53 +0000 | [diff] [blame] | 409 | HREF="...">}. If the value to be quoted might include single- or |
Fred Drake | 84e58ab | 2001-08-11 03:28:41 +0000 | [diff] [blame] | 410 | double-quote characters, or both, consider using the |
| 411 | \function{quoteattr()} function in the \refmodule{xml.sax.saxutils} |
| 412 | module instead. |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 413 | \end{funcdesc} |
| 414 | |
| 415 | |
Fred Drake | 34a37b8 | 2001-12-20 17:13:09 +0000 | [diff] [blame] | 416 | \subsection{Caring about security \label{cgi-security}} |
| 417 | |
| 418 | \indexii{CGI}{security} |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 419 | |
Fred Drake | 91f2f26 | 2001-07-06 19:28:48 +0000 | [diff] [blame] | 420 | There's one important rule: if you invoke an external program (via the |
| 421 | \function{os.system()} or \function{os.popen()} functions. or others |
| 422 | with similar functionality), make very sure you don't pass arbitrary |
| 423 | strings received from the client to the shell. This is a well-known |
Fred Drake | 8ee679f | 2001-07-14 02:50:55 +0000 | [diff] [blame] | 424 | security hole whereby clever hackers anywhere on the Web can exploit a |
Fred Drake | 91f2f26 | 2001-07-06 19:28:48 +0000 | [diff] [blame] | 425 | gullible CGI script to invoke arbitrary shell commands. Even parts of |
| 426 | the URL or field names cannot be trusted, since the request doesn't |
| 427 | have to come from your form! |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 428 | |
| 429 | To be on the safe side, if you must pass a string gotten from a form |
| 430 | to a shell command, you should make sure the string contains only |
| 431 | alphanumeric characters, dashes, underscores, and periods. |
| 432 | |
| 433 | |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 434 | \subsection{Installing your CGI script on a \UNIX\ system} |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 435 | |
| 436 | Read the documentation for your HTTP server and check with your local |
| 437 | system administrator to find the directory where CGI scripts should be |
Fred Drake | a2e268a | 1997-12-09 03:28:42 +0000 | [diff] [blame] | 438 | 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] | 439 | |
| 440 | Make sure that your script is readable and executable by ``others''; the |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 441 | \UNIX{} file mode should be \code{0755} octal (use \samp{chmod 0755 |
Fred Drake | 7eca8e5 | 1999-01-18 15:46:02 +0000 | [diff] [blame] | 442 | \var{filename}}). Make sure that the first line of the script contains |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 443 | \code{\#!} starting in column 1 followed by the pathname of the Python |
| 444 | interpreter, for instance: |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 445 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 446 | \begin{verbatim} |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 447 | #!/usr/local/bin/python |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 448 | \end{verbatim} |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 449 | |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 450 | Make sure the Python interpreter exists and is executable by ``others''. |
| 451 | |
| 452 | Make sure that any files your script needs to read or write are |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 453 | readable or writable, respectively, by ``others'' --- their mode |
| 454 | should be \code{0644} for readable and \code{0666} for writable. This |
| 455 | is because, for security reasons, the HTTP server executes your script |
| 456 | as user ``nobody'', without any special privileges. It can only read |
| 457 | (write, execute) files that everybody can read (write, execute). The |
| 458 | current directory at execution time is also different (it is usually |
| 459 | the server's cgi-bin directory) and the set of environment variables |
Fred Drake | 8ee679f | 2001-07-14 02:50:55 +0000 | [diff] [blame] | 460 | is also different from what you get when you log in. In particular, don't |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 461 | count on the shell's search path for executables (\envvar{PATH}) or |
| 462 | the Python module search path (\envvar{PYTHONPATH}) to be set to |
| 463 | anything interesting. |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 464 | |
| 465 | If you need to load modules from a directory which is not on Python's |
| 466 | default module search path, you can change the path in your script, |
Fred Drake | 91f2f26 | 2001-07-06 19:28:48 +0000 | [diff] [blame] | 467 | before importing other modules. For example: |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 468 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 469 | \begin{verbatim} |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 470 | import sys |
| 471 | sys.path.insert(0, "/usr/home/joe/lib/python") |
| 472 | sys.path.insert(0, "/usr/local/lib/python") |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 473 | \end{verbatim} |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 474 | |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 475 | (This way, the directory inserted last will be searched first!) |
| 476 | |
Fred Drake | efc1e0f | 1998-01-13 19:00:33 +0000 | [diff] [blame] | 477 | 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] | 478 | documentation (it will usually have a section on CGI scripts). |
| 479 | |
| 480 | |
| 481 | \subsection{Testing your CGI script} |
| 482 | |
| 483 | Unfortunately, a CGI script will generally not run when you try it |
| 484 | from the command line, and a script that works perfectly from the |
| 485 | command line may fail mysteriously when run from the server. There's |
| 486 | one reason why you should still test your script from the command |
Fred Drake | 6a79be8 | 1998-04-03 03:47:03 +0000 | [diff] [blame] | 487 | line: if it contains a syntax error, the Python interpreter won't |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 488 | execute it at all, and the HTTP server will most likely send a cryptic |
| 489 | error to the client. |
| 490 | |
| 491 | Assuming your script has no syntax errors, yet it does not work, you |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 492 | have no choice but to read the next section. |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 493 | |
| 494 | |
Fred Drake | 34a37b8 | 2001-12-20 17:13:09 +0000 | [diff] [blame] | 495 | \subsection{Debugging CGI scripts} \indexii{CGI}{debugging} |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 496 | |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 497 | First of all, check for trivial installation errors --- reading the |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 498 | section above on installing your CGI script carefully can save you a |
| 499 | lot of time. If you wonder whether you have understood the |
| 500 | installation procedure correctly, try installing a copy of this module |
Fred Drake | a2e268a | 1997-12-09 03:28:42 +0000 | [diff] [blame] | 501 | 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] | 502 | will dump its environment and the contents of the form in HTML form. |
| 503 | 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] | 504 | 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] | 505 | request by entering a URL into your browser of the form: |
| 506 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 507 | \begin{verbatim} |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 508 | http://yourhostname/cgi-bin/cgi.py?name=Joe+Blow&addr=At+Home |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 509 | \end{verbatim} |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 510 | |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 511 | If this gives an error of type 404, the server cannot find the script |
| 512 | -- perhaps you need to install it in a different directory. If it |
Fred Drake | 91f2f26 | 2001-07-06 19:28:48 +0000 | [diff] [blame] | 513 | gives another error, there's an installation problem that |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 514 | you should fix before trying to go any further. If you get a nicely |
| 515 | formatted listing of the environment and form content (in this |
| 516 | example, the fields should be listed as ``addr'' with value ``At Home'' |
Fred Drake | a2e268a | 1997-12-09 03:28:42 +0000 | [diff] [blame] | 517 | 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] | 518 | installed correctly. If you follow the same procedure for your own |
| 519 | script, you should now be able to debug it. |
| 520 | |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 521 | The next step could be to call the \module{cgi} module's |
| 522 | \function{test()} function from your script: replace its main code |
| 523 | with the single statement |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 524 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 525 | \begin{verbatim} |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 526 | cgi.test() |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 527 | \end{verbatim} |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 528 | |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 529 | This should produce the same results as those gotten from installing |
Fred Drake | a2e268a | 1997-12-09 03:28:42 +0000 | [diff] [blame] | 530 | the \file{cgi.py} file itself. |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 531 | |
Fred Drake | 91f2f26 | 2001-07-06 19:28:48 +0000 | [diff] [blame] | 532 | When an ordinary Python script raises an unhandled exception (for |
| 533 | whatever reason: of a typo in a module name, a file that can't be |
| 534 | opened, etc.), the Python interpreter prints a nice traceback and |
| 535 | exits. While the Python interpreter will still do this when your CGI |
| 536 | script raises an exception, most likely the traceback will end up in |
Fred Drake | 34a37b8 | 2001-12-20 17:13:09 +0000 | [diff] [blame] | 537 | one of the HTTP server's log files, or be discarded altogether. |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 538 | |
| 539 | Fortunately, once you have managed to get your script to execute |
Fred Drake | 34a37b8 | 2001-12-20 17:13:09 +0000 | [diff] [blame] | 540 | \emph{some} code, you can easily send tracebacks to the Web browser |
| 541 | using the \refmodule{cgitb} module. If you haven't done so already, |
| 542 | just add the line: |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 543 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 544 | \begin{verbatim} |
Fred Drake | 34a37b8 | 2001-12-20 17:13:09 +0000 | [diff] [blame] | 545 | import cgitb; cgitb.enable() |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 546 | \end{verbatim} |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 547 | |
Fred Drake | 34a37b8 | 2001-12-20 17:13:09 +0000 | [diff] [blame] | 548 | to the top of your script. Then try running it again; when a |
| 549 | problem occurs, you should see a detailed report that will |
| 550 | likely make apparent the cause of the crash. |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 551 | |
Fred Drake | 34a37b8 | 2001-12-20 17:13:09 +0000 | [diff] [blame] | 552 | If you suspect that there may be a problem in importing the |
| 553 | \refmodule{cgitb} module, you can use an even more robust approach |
| 554 | (which only uses built-in modules): |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 555 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 556 | \begin{verbatim} |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 557 | import sys |
| 558 | sys.stderr = sys.stdout |
Moshe Zadka | a1a4b59 | 2000-08-25 21:47:56 +0000 | [diff] [blame] | 559 | print "Content-Type: text/plain" |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 560 | print |
| 561 | ...your code here... |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 562 | \end{verbatim} |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 563 | |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 564 | This relies on the Python interpreter to print the traceback. The |
| 565 | content type of the output is set to plain text, which disables all |
| 566 | HTML processing. If your script works, the raw HTML will be displayed |
| 567 | by your client. If it raises an exception, most likely after the |
| 568 | first two lines have been printed, a traceback will be displayed. |
Fred Drake | 34a37b8 | 2001-12-20 17:13:09 +0000 | [diff] [blame] | 569 | Because no HTML interpretation is going on, the traceback will be |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 570 | readable. |
| 571 | |
| 572 | |
| 573 | \subsection{Common problems and solutions} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 574 | |
| 575 | \begin{itemize} |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 576 | \item Most HTTP servers buffer the output from CGI scripts until the |
| 577 | script is completed. This means that it is not possible to display a |
| 578 | progress report on the client's display while the script is running. |
| 579 | |
| 580 | \item Check the installation instructions above. |
| 581 | |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 582 | \item Check the HTTP server's log files. (\samp{tail -f logfile} in a |
| 583 | separate window may be useful!) |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 584 | |
| 585 | \item Always check a script for syntax errors first, by doing something |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 586 | like \samp{python script.py}. |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 587 | |
Fred Drake | 34a37b8 | 2001-12-20 17:13:09 +0000 | [diff] [blame] | 588 | \item If your script does not have any syntax errors, try adding |
| 589 | \samp{import cgitb; cgitb.enable()} to the top of the script. |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 590 | |
| 591 | \item When invoking external programs, make sure they can be found. |
Fred Drake | 6ef871c | 1998-03-12 06:52:05 +0000 | [diff] [blame] | 592 | Usually, this means using absolute path names --- \envvar{PATH} is |
| 593 | usually not set to a very useful value in a CGI script. |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 594 | |
| 595 | \item When reading or writing external files, make sure they can be read |
Alex Martelli | 50324a6 | 2003-11-09 16:31:18 +0000 | [diff] [blame] | 596 | or written by the userid under which your CGI script will be running: |
| 597 | this is typically the userid under which the web server is running, or some |
| 598 | explicitly specified userid for a web server's \samp{suexec} feature. |
Guido van Rossum | a29cc97 | 1996-07-30 18:22:07 +0000 | [diff] [blame] | 599 | |
| 600 | \item Don't try to give a CGI script a set-uid mode. This doesn't work on |
| 601 | most systems, and is a security liability as well. |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 602 | \end{itemize} |
| 603 | |