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