Mercurial > cpython-lru_cache-weakref
annotate Doc/lib/libcgi.tex @ 38664:7619216bbc19 2.4
Bug #1502728: Correctly link against librt library on HP-UX.
(backport from rev. 46743)
| author | Georg Brandl <georg@python.org> |
|---|---|
| date | Thu, 08 Jun 2006 12:54:16 +0000 |
| parents | 280650792ef7 |
| children |
| 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 |
|
18574
346dcafc878b
Minor changes to match the style guide.
Fred Drake <fdrake@acm.org>
parents:
18411
diff
changeset
|
15 Support module for Common Gateway Interface (CGI) scripts.% |
|
7806
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 |
|
36368
280650792ef7
Remove reference to Grail and Netscape 2.0 from cgi docs.
Georg Brandl <georg@python.org>
parents:
32570
diff
changeset
|
39 uploads from a form (if your browser supports it). |
| 2449 | 40 |
|
3856
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
41 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
|
42 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
|
43 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
|
44 generate a minimal header section looks like this: |
| 2449 | 45 |
|
7277
bf4e790bd61a
Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents:
7086
diff
changeset
|
46 \begin{verbatim} |
|
14196
41234ae95d2a
Closing patch #101120 -- After everyone agreed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
13625
diff
changeset
|
47 print "Content-Type: text/html" # HTML is following |
| 5818 | 48 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
|
49 \end{verbatim} |
| 7663 | 50 |
|
3856
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
51 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
|
52 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
|
53 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
|
54 |
|
7277
bf4e790bd61a
Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents:
7086
diff
changeset
|
55 \begin{verbatim} |
| 5818 | 56 print "<TITLE>CGI script output</TITLE>" |
| 57 print "<H1>This is my first CGI script</H1>" | |
| 58 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
|
59 \end{verbatim} |
| 7663 | 60 |
|
3856
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
61 \subsection{Using the cgi module} |
|
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
62 \nodename{Using the cgi module} |
|
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
63 |
| 7663 | 64 Begin by writing \samp{import cgi}. Do not use \samp{from cgi import |
| 65 *} --- the module defines all sorts of names for its own use or for | |
| 66 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
|
67 |
|
21504
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
68 When you write a new script, consider adding the line: |
|
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
69 |
|
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
70 \begin{verbatim} |
|
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
71 import cgitb; cgitb.enable() |
|
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
72 \end{verbatim} |
|
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
73 |
|
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
74 This activates a special exception handler that will display detailed |
|
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
75 reports in the Web browser if any errors occur. If you'd rather not |
|
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
76 show the guts of your program to users of your script, you can have |
|
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
77 the reports saved to files instead, with a line like this: |
|
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
78 |
|
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
79 \begin{verbatim} |
|
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
80 import cgitb; cgitb.enable(display=0, logdir="/tmp") |
|
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
81 \end{verbatim} |
|
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
82 |
|
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
83 It's very helpful to use this feature during script development. |
|
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
84 The reports produced by \refmodule{cgitb} provide information that |
|
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
85 can save you a lot of time in tracking down bugs. You can always |
|
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
86 remove the \code{cgitb} line later when you have tested your script |
|
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
87 and are confident that it works correctly. |
|
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
88 |
|
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
89 To get at submitted form data, |
|
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
90 it's best to use the \class{FieldStorage} class. The other classes |
| 7663 | 91 defined in this module are provided mostly for backward compatibility. |
| 92 Instantiate it exactly once, without arguments. This reads the form | |
| 93 contents from standard input or the environment (depending on the | |
| 94 value of various environment variables set according to the CGI | |
| 95 standard). Since it may consume standard input, it should be | |
| 96 instantiated only once. | |
|
3856
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
97 |
|
14196
41234ae95d2a
Closing patch #101120 -- After everyone agreed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
13625
diff
changeset
|
98 The \class{FieldStorage} instance can be indexed like a Python |
|
41234ae95d2a
Closing patch #101120 -- After everyone agreed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
13625
diff
changeset
|
99 dictionary, and also supports the standard dictionary methods |
|
19164
5d6b2c17ea2c
For the escape() function, added a reference to the quoteattrs() function
Fred Drake <fdrake@acm.org>
parents:
18574
diff
changeset
|
100 \method{has_key()} and \method{keys()}. The built-in \function{len()} |
|
5d6b2c17ea2c
For the escape() function, added a reference to the quoteattrs() function
Fred Drake <fdrake@acm.org>
parents:
18574
diff
changeset
|
101 is also supported. Form fields containing empty strings are ignored |
|
14196
41234ae95d2a
Closing patch #101120 -- After everyone agreed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
13625
diff
changeset
|
102 and do not appear in the dictionary; to keep such values, provide |
|
30134
523c3d61dbdd
SF patch#786531 'the the' typo. Contributed by George Yoshida
Raymond Hettinger <python@rcn.com>
parents:
29092
diff
changeset
|
103 a true value for the optional \var{keep_blank_values} keyword |
|
19164
5d6b2c17ea2c
For the escape() function, added a reference to the quoteattrs() function
Fred Drake <fdrake@acm.org>
parents:
18574
diff
changeset
|
104 parameter when creating the \class{FieldStorage} instance. |
|
14196
41234ae95d2a
Closing patch #101120 -- After everyone agreed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
13625
diff
changeset
|
105 |
|
41234ae95d2a
Closing patch #101120 -- After everyone agreed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
13625
diff
changeset
|
106 For instance, the following code (which assumes that the |
|
19164
5d6b2c17ea2c
For the escape() function, added a reference to the quoteattrs() function
Fred Drake <fdrake@acm.org>
parents:
18574
diff
changeset
|
107 \mailheader{Content-Type} header and blank line have already been |
|
5d6b2c17ea2c
For the escape() function, added a reference to the quoteattrs() function
Fred Drake <fdrake@acm.org>
parents:
18574
diff
changeset
|
108 printed) checks that the fields \code{name} and \code{addr} are both |
|
5d6b2c17ea2c
For the escape() function, added a reference to the quoteattrs() function
Fred Drake <fdrake@acm.org>
parents:
18574
diff
changeset
|
109 set to a non-empty string: |
|
3856
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
110 |
|
7277
bf4e790bd61a
Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents:
7086
diff
changeset
|
111 \begin{verbatim} |
| 5818 | 112 form = cgi.FieldStorage() |
|
18338
5668a8550be4
Simplify an example based on comment from Thomas Holenstein <thomas@hex.ch>:
Fred Drake <fdrake@acm.org>
parents:
14196
diff
changeset
|
113 if not (form.has_key("name") and form.has_key("addr")): |
| 5818 | 114 print "<H1>Error</H1>" |
| 115 print "Please fill in the name and addr fields." | |
| 116 return | |
|
14196
41234ae95d2a
Closing patch #101120 -- After everyone agreed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
13625
diff
changeset
|
117 print "<p>name:", form["name"].value |
|
41234ae95d2a
Closing patch #101120 -- After everyone agreed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
13625
diff
changeset
|
118 print "<p>addr:", form["addr"].value |
| 5818 | 119 ...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
|
120 \end{verbatim} |
| 7663 | 121 |
| 122 Here the fields, accessed through \samp{form[\var{key}]}, are | |
| 123 themselves instances of \class{FieldStorage} (or | |
| 124 \class{MiniFieldStorage}, depending on the form encoding). | |
|
14196
41234ae95d2a
Closing patch #101120 -- After everyone agreed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
13625
diff
changeset
|
125 The \member{value} attribute of the instance yields the string value |
|
19164
5d6b2c17ea2c
For the escape() function, added a reference to the quoteattrs() function
Fred Drake <fdrake@acm.org>
parents:
18574
diff
changeset
|
126 of the field. The \method{getvalue()} method returns this string value |
|
14196
41234ae95d2a
Closing patch #101120 -- After everyone agreed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
13625
diff
changeset
|
127 directly; it also accepts an optional second argument as a default to |
|
41234ae95d2a
Closing patch #101120 -- After everyone agreed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
13625
diff
changeset
|
128 return if the requested key is not present. |
|
3856
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
129 |
|
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
130 If the submitted form data contains more than one field with the same |
| 7663 | 131 name, the object retrieved by \samp{form[\var{key}]} is not a |
| 132 \class{FieldStorage} or \class{MiniFieldStorage} | |
|
14196
41234ae95d2a
Closing patch #101120 -- After everyone agreed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
13625
diff
changeset
|
133 instance but a list of such instances. Similarly, in this situation, |
|
41234ae95d2a
Closing patch #101120 -- After everyone agreed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
13625
diff
changeset
|
134 \samp{form.getvalue(\var{key})} would return a list of strings. |
|
41234ae95d2a
Closing patch #101120 -- After everyone agreed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
13625
diff
changeset
|
135 If you expect this possibility |
|
19164
5d6b2c17ea2c
For the escape() function, added a reference to the quoteattrs() function
Fred Drake <fdrake@acm.org>
parents:
18574
diff
changeset
|
136 (when your HTML form contains multiple fields with the same name), use |
|
32285
91388c845b16
[Bug #953177] Mention .getlist(); text from Paul Moore
Andrew M. Kuchling <amk@amk.ca>
parents:
31416
diff
changeset
|
137 the \function{getlist()} function, which always returns a list of values (so that you |
|
91388c845b16
[Bug #953177] Mention .getlist(); text from Paul Moore
Andrew M. Kuchling <amk@amk.ca>
parents:
31416
diff
changeset
|
138 do not need to special-case the single item case). For example, this |
|
19164
5d6b2c17ea2c
For the escape() function, added a reference to the quoteattrs() function
Fred Drake <fdrake@acm.org>
parents:
18574
diff
changeset
|
139 code concatenates any number of username fields, separated by |
| 7663 | 140 commas: |
| 2449 | 141 |
|
7277
bf4e790bd61a
Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents:
7086
diff
changeset
|
142 \begin{verbatim} |
|
32285
91388c845b16
[Bug #953177] Mention .getlist(); text from Paul Moore
Andrew M. Kuchling <amk@amk.ca>
parents:
31416
diff
changeset
|
143 value = form.getlist("username") |
|
91388c845b16
[Bug #953177] Mention .getlist(); text from Paul Moore
Andrew M. Kuchling <amk@amk.ca>
parents:
31416
diff
changeset
|
144 usernames = ",".join(value) |
|
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 |
|
14196
41234ae95d2a
Closing patch #101120 -- After everyone agreed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
13625
diff
changeset
|
147 If a field represents an uploaded file, accessing the value via the |
|
41234ae95d2a
Closing patch #101120 -- After everyone agreed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
13625
diff
changeset
|
148 \member{value} attribute or the \function{getvalue()} method reads the |
| 7663 | 149 entire file in memory as a string. This may not be what you want. |
|
14196
41234ae95d2a
Closing patch #101120 -- After everyone agreed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
13625
diff
changeset
|
150 You can test for an uploaded file by testing either the \member{filename} |
|
41234ae95d2a
Closing patch #101120 -- After everyone agreed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
13625
diff
changeset
|
151 attribute or the \member{file} attribute. You can then read the data at |
|
41234ae95d2a
Closing patch #101120 -- After everyone agreed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
13625
diff
changeset
|
152 leisure from the \member{file} attribute: |
| 2449 | 153 |
|
7277
bf4e790bd61a
Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents:
7086
diff
changeset
|
154 \begin{verbatim} |
| 5818 | 155 fileitem = form["userfile"] |
| 156 if fileitem.file: | |
| 157 # It's an uploaded file; count lines | |
| 158 linecount = 0 | |
| 159 while 1: | |
| 160 line = fileitem.file.readline() | |
| 161 if not line: break | |
| 162 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
|
163 \end{verbatim} |
| 7663 | 164 |
|
3856
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
165 The file upload draft standard entertains the possibility of uploading |
| 7663 | 166 multiple files from one field (using a recursive |
| 167 \mimetype{multipart/*} encoding). When this occurs, the item will be | |
| 168 a dictionary-like \class{FieldStorage} item. This can be determined | |
| 169 by testing its \member{type} attribute, which should be | |
| 170 \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
|
171 \mimetype{multipart/*}). In this case, it can be iterated over |
| 7663 | 172 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
|
173 |
| 7663 | 174 When a form is submitted in the ``old'' format (as the query string or |
| 175 as a single data part of type | |
| 176 \mimetype{application/x-www-form-urlencoded}), the items will actually | |
| 177 be instances of the class \class{MiniFieldStorage}. In this case, the | |
|
14196
41234ae95d2a
Closing patch #101120 -- After everyone agreed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
13625
diff
changeset
|
178 \member{list}, \member{file}, and \member{filename} attributes are |
|
41234ae95d2a
Closing patch #101120 -- After everyone agreed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
13625
diff
changeset
|
179 always \code{None}. |
|
3856
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
180 |
| 2449 | 181 |
|
19866
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
182 \subsection{Higher Level Interface} |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
183 |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
184 \versionadded{2.2} % XXX: Is this true ? |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
185 |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
186 The previous section explains how to read CGI form data using the |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
187 \class{FieldStorage} class. This section describes a higher level |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
188 interface which was added to this class to allow one to do it in a |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
189 more readable and intuitive way. The interface doesn't make the |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
190 techniques described in previous sections obsolete --- they are still |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
191 useful to process file uploads efficiently, for example. |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
192 |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
193 The interface consists of two simple methods. Using the methods |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
194 you can process form data in a generic way, without the need to worry |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
195 whether only one or more values were posted under one name. |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
196 |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
197 In the previous section, you learned to write following code anytime |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
198 you expected a user to post more than one value under one name: |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
199 |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
200 \begin{verbatim} |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
201 item = form.getvalue("item") |
|
24935
64508a37a8d5
Clarify that even though some of the relevant specifications define the
Fred Drake <fdrake@acm.org>
parents:
23289
diff
changeset
|
202 if isinstance(item, list): |
|
19866
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
203 # The user is requesting more than one item. |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
204 else: |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
205 # The user is requesting only one item. |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
206 \end{verbatim} |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
207 |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
208 This situation is common for example when a form contains a group of |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
209 multiple checkboxes with the same name: |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
210 |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
211 \begin{verbatim} |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
212 <input type="checkbox" name="item" value="1" /> |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
213 <input type="checkbox" name="item" value="2" /> |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
214 \end{verbatim} |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
215 |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
216 In most situations, however, there's only one form control with a |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
217 particular name in a form and then you expect and need only one value |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
218 associated with this name. So you write a script containing for |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
219 example this code: |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
220 |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
221 \begin{verbatim} |
|
31416
a15115290e13
fix method name in example code
Fred Drake <fdrake@acm.org>
parents:
30842
diff
changeset
|
222 user = form.getvalue("user").upper() |
|
19866
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
223 \end{verbatim} |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
224 |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
225 The problem with the code is that you should never expect that a |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
226 client will provide valid input to your scripts. For example, if a |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
227 curious user appends another \samp{user=foo} pair to the query string, |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
228 then the script would crash, because in this situation the |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
229 \code{getvalue("user")} method call returns a list instead of a |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
230 string. Calling the \method{toupper()} method on a list is not valid |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
231 (since lists do not have a method of this name) and results in an |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
232 \exception{AttributeError} exception. |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
233 |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
234 Therefore, the appropriate way to read form data values was to always |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
235 use the code which checks whether the obtained value is a single value |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
236 or a list of values. That's annoying and leads to less readable |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
237 scripts. |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
238 |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
239 A more convenient approach is to use the methods \method{getfirst()} |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
240 and \method{getlist()} provided by this higher level interface. |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
241 |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
242 \begin{methoddesc}[FieldStorage]{getfirst}{name\optional{, default}} |
|
32570
70b1504e17ff
SF bug #987486: fix typo.
Raymond Hettinger <python@rcn.com>
parents:
32285
diff
changeset
|
243 This method always returns only one value associated with form field |
|
19866
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
244 \var{name}. The method returns only the first value in case that |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
245 more values were posted under such name. Please note that the order |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
246 in which the values are received may vary from browser to browser |
|
24935
64508a37a8d5
Clarify that even though some of the relevant specifications define the
Fred Drake <fdrake@acm.org>
parents:
23289
diff
changeset
|
247 and should not be counted on.\footnote{Note that some recent |
|
64508a37a8d5
Clarify that even though some of the relevant specifications define the
Fred Drake <fdrake@acm.org>
parents:
23289
diff
changeset
|
248 versions of the HTML specification do state what order the |
|
64508a37a8d5
Clarify that even though some of the relevant specifications define the
Fred Drake <fdrake@acm.org>
parents:
23289
diff
changeset
|
249 field values should be supplied in, but knowing whether a |
|
64508a37a8d5
Clarify that even though some of the relevant specifications define the
Fred Drake <fdrake@acm.org>
parents:
23289
diff
changeset
|
250 request was received from a conforming browser, or even from a |
|
64508a37a8d5
Clarify that even though some of the relevant specifications define the
Fred Drake <fdrake@acm.org>
parents:
23289
diff
changeset
|
251 browser at all, is tedious and error-prone.} If no such form |
|
64508a37a8d5
Clarify that even though some of the relevant specifications define the
Fred Drake <fdrake@acm.org>
parents:
23289
diff
changeset
|
252 field or value exists then the method returns the value specified by |
|
64508a37a8d5
Clarify that even though some of the relevant specifications define the
Fred Drake <fdrake@acm.org>
parents:
23289
diff
changeset
|
253 the optional parameter \var{default}. This parameter defaults to |
|
64508a37a8d5
Clarify that even though some of the relevant specifications define the
Fred Drake <fdrake@acm.org>
parents:
23289
diff
changeset
|
254 \code{None} if not specified. |
|
19866
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
255 \end{methoddesc} |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
256 |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
257 \begin{methoddesc}[FieldStorage]{getlist}{name} |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
258 This method always returns a list of values associated with form |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
259 field \var{name}. The method returns an empty list if no such form |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
260 field or value exists for \var{name}. It returns a list consisting |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
261 of one item if only one such value exists. |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
262 \end{methoddesc} |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
263 |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
264 Using these methods you can write nice compact code: |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
265 |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
266 \begin{verbatim} |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
267 import cgi |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
268 form = cgi.FieldStorage() |
|
31416
a15115290e13
fix method name in example code
Fred Drake <fdrake@acm.org>
parents:
30842
diff
changeset
|
269 user = form.getfirst("user", "").upper() # This way it's safe. |
|
19866
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
270 for item in form.getlist("item"): |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
271 do_something(item) |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
272 \end{verbatim} |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
273 |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
274 |
|
3856
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
275 \subsection{Old classes} |
|
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
276 |
| 7663 | 277 These classes, present in earlier versions of the \module{cgi} module, |
| 278 are still supported for backward compatibility. New applications | |
| 279 should use the \class{FieldStorage} class. | |
|
3856
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
280 |
| 7663 | 281 \class{SvFormContentDict} stores single value form content as |
| 282 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
|
283 |
| 7663 | 284 \class{FormContentDict} stores multiple value form content as a |
| 285 dictionary (the form items are lists of values). Useful if your form | |
| 286 contains multiple fields with the same name. | |
|
3856
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
287 |
| 7663 | 288 Other classes (\class{FormContent}, \class{InterpFormContentDict}) are |
| 289 present for backwards compatibility with really old applications only. | |
| 290 If you still use these and would be inconvenienced when they | |
| 291 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
|
292 |
|
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
293 |
|
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
294 \subsection{Functions} |
|
4728
b218f294b726
(lib<all sorts of stuff>.tex):
Fred Drake <fdrake@acm.org>
parents:
4487
diff
changeset
|
295 \nodename{Functions in cgi module} |
|
3856
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
296 |
|
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
297 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
|
298 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
|
299 circumstances. |
|
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
300 |
|
19866
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
301 \begin{funcdesc}{parse}{fp\optional{, keep_blank_values\optional{, |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
302 strict_parsing}}} |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
303 Parse a query in the environment or from a file (the file defaults |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
304 to \code{sys.stdin}). The \var{keep_blank_values} and |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
305 \var{strict_parsing} parameters are passed to \function{parse_qs()} |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
306 unchanged. |
| 2449 | 307 \end{funcdesc} |
| 308 | |
|
19866
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
309 \begin{funcdesc}{parse_qs}{qs\optional{, keep_blank_values\optional{, |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
310 strict_parsing}}} |
| 7663 | 311 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
|
312 \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
|
313 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
|
314 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
|
315 |
|
b6d3d17195dc
Patch by Jim Fulton to document the new parse_qls().
Guido van Rossum <guido@python.org>
parents:
9903
diff
changeset
|
316 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
|
317 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
|
318 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
|
319 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
|
320 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
|
321 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
|
322 not included. |
|
b6d3d17195dc
Patch by Jim Fulton to document the new parse_qls().
Guido van Rossum <guido@python.org>
parents:
9903
diff
changeset
|
323 |
|
b6d3d17195dc
Patch by Jim Fulton to document the new parse_qls().
Guido van Rossum <guido@python.org>
parents:
9903
diff
changeset
|
324 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
|
325 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
|
326 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
|
327 exception. |
|
29092
4ae3c2d98890
Fix and add reference to urllib.urlencode for parse_qsl? functions.
Brett Cannon <bcannon@gmail.com>
parents:
28777
diff
changeset
|
328 |
|
4ae3c2d98890
Fix and add reference to urllib.urlencode for parse_qsl? functions.
Brett Cannon <bcannon@gmail.com>
parents:
28777
diff
changeset
|
329 Use the \function{\refmodule{urllib}.urlencode()} function to convert |
|
4ae3c2d98890
Fix and add reference to urllib.urlencode for parse_qsl? functions.
Brett Cannon <bcannon@gmail.com>
parents:
28777
diff
changeset
|
330 such dictionaries into query strings. |
|
4ae3c2d98890
Fix and add reference to urllib.urlencode for parse_qsl? functions.
Brett Cannon <bcannon@gmail.com>
parents:
28777
diff
changeset
|
331 |
|
10951
b6d3d17195dc
Patch by Jim Fulton to document the new parse_qls().
Guido van Rossum <guido@python.org>
parents:
9903
diff
changeset
|
332 \end{funcdesc} |
|
b6d3d17195dc
Patch by Jim Fulton to document the new parse_qls().
Guido van Rossum <guido@python.org>
parents:
9903
diff
changeset
|
333 |
|
19866
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
334 \begin{funcdesc}{parse_qsl}{qs\optional{, keep_blank_values\optional{, |
|
a34991b91008
Added documentation on the getfirst() and getlist() methods of the
Fred Drake <fdrake@acm.org>
parents:
19164
diff
changeset
|
335 strict_parsing}}} |
|
10951
b6d3d17195dc
Patch by Jim Fulton to document the new parse_qls().
Guido van Rossum <guido@python.org>
parents:
9903
diff
changeset
|
336 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
|
337 \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
|
338 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
|
339 |
|
b6d3d17195dc
Patch by Jim Fulton to document the new parse_qls().
Guido van Rossum <guido@python.org>
parents:
9903
diff
changeset
|
340 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
|
341 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
|
342 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
|
343 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
|
344 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
|
345 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
|
346 not included. |
|
b6d3d17195dc
Patch by Jim Fulton to document the new parse_qls().
Guido van Rossum <guido@python.org>
parents:
9903
diff
changeset
|
347 |
|
b6d3d17195dc
Patch by Jim Fulton to document the new parse_qls().
Guido van Rossum <guido@python.org>
parents:
9903
diff
changeset
|
348 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
|
349 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
|
350 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
|
351 exception. |
|
28777
3ebb4bcebdd7
Add cross-references between urllib.urlencode() and cgi.parse_qs[l]().
Fred Drake <fdrake@acm.org>
parents:
25008
diff
changeset
|
352 |
|
29092
4ae3c2d98890
Fix and add reference to urllib.urlencode for parse_qsl? functions.
Brett Cannon <bcannon@gmail.com>
parents:
28777
diff
changeset
|
353 Use the \function{\refmodule{urllib}.urlencode()} function to convert |
|
28777
3ebb4bcebdd7
Add cross-references between urllib.urlencode() and cgi.parse_qs[l]().
Fred Drake <fdrake@acm.org>
parents:
25008
diff
changeset
|
354 such lists of pairs into query strings. |
| 2449 | 355 \end{funcdesc} |
| 356 | |
|
7712
0cbc9df882b6
Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents:
7663
diff
changeset
|
357 \begin{funcdesc}{parse_multipart}{fp, pdict} |
| 7663 | 358 Parse input of type \mimetype{multipart/form-data} (for |
| 359 file uploads). Arguments are \var{fp} for the input file and | |
|
14196
41234ae95d2a
Closing patch #101120 -- After everyone agreed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
13625
diff
changeset
|
360 \var{pdict} for a dictionary containing other parameters in |
|
19164
5d6b2c17ea2c
For the escape() function, added a reference to the quoteattrs() function
Fred Drake <fdrake@acm.org>
parents:
18574
diff
changeset
|
361 the \mailheader{Content-Type} header. |
|
3856
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
362 |
| 7663 | 363 Returns a dictionary just like \function{parse_qs()} keys are the |
| 364 field names, each value is a list of values for that field. This is | |
| 365 easy to use but not much good if you are expecting megabytes to be | |
| 366 uploaded --- in that case, use the \class{FieldStorage} class instead | |
|
14196
41234ae95d2a
Closing patch #101120 -- After everyone agreed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
13625
diff
changeset
|
367 which is much more flexible. |
|
3856
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
368 |
| 7663 | 369 Note that this does not parse nested multipart parts --- use |
| 370 \class{FieldStorage} for that. | |
| 2449 | 371 \end{funcdesc} |
| 372 | |
|
6153
17a26f986007
Removed some colons that shouldn't be there (probably leftovers from
Guido van Rossum <guido@python.org>
parents:
5871
diff
changeset
|
373 \begin{funcdesc}{parse_header}{string} |
|
19164
5d6b2c17ea2c
For the escape() function, added a reference to the quoteattrs() function
Fred Drake <fdrake@acm.org>
parents:
18574
diff
changeset
|
374 Parse a MIME header (such as \mailheader{Content-Type}) into a main |
|
14196
41234ae95d2a
Closing patch #101120 -- After everyone agreed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
13625
diff
changeset
|
375 value and a dictionary of parameters. |
|
3856
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
376 \end{funcdesc} |
|
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
377 |
|
6153
17a26f986007
Removed some colons that shouldn't be there (probably leftovers from
Guido van Rossum <guido@python.org>
parents:
5871
diff
changeset
|
378 \begin{funcdesc}{test}{} |
| 7663 | 379 Robust test CGI script, usable as main program. |
| 380 Writes minimal HTTP headers and formats all information provided to | |
| 381 the script in HTML form. | |
| 2449 | 382 \end{funcdesc} |
| 383 | |
|
6153
17a26f986007
Removed some colons that shouldn't be there (probably leftovers from
Guido van Rossum <guido@python.org>
parents:
5871
diff
changeset
|
384 \begin{funcdesc}{print_environ}{} |
| 7663 | 385 Format the shell environment in HTML. |
|
3856
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
386 \end{funcdesc} |
|
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
387 |
|
6153
17a26f986007
Removed some colons that shouldn't be there (probably leftovers from
Guido van Rossum <guido@python.org>
parents:
5871
diff
changeset
|
388 \begin{funcdesc}{print_form}{form} |
| 7663 | 389 Format a form in HTML. |
|
3856
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
390 \end{funcdesc} |
| 2449 | 391 |
|
6153
17a26f986007
Removed some colons that shouldn't be there (probably leftovers from
Guido van Rossum <guido@python.org>
parents:
5871
diff
changeset
|
392 \begin{funcdesc}{print_directory}{} |
| 7663 | 393 Format the current directory in HTML. |
|
3856
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
394 \end{funcdesc} |
|
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
395 |
|
6153
17a26f986007
Removed some colons that shouldn't be there (probably leftovers from
Guido van Rossum <guido@python.org>
parents:
5871
diff
changeset
|
396 \begin{funcdesc}{print_environ_usage}{} |
| 7663 | 397 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
|
398 HTML. |
| 2449 | 399 \end{funcdesc} |
| 400 | |
|
7712
0cbc9df882b6
Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents:
7663
diff
changeset
|
401 \begin{funcdesc}{escape}{s\optional{, quote}} |
| 7663 | 402 Convert the characters |
| 403 \character{\&}, \character{<} and \character{>} in string \var{s} to | |
| 404 HTML-safe sequences. Use this if you need to display text that might | |
| 405 contain such characters in HTML. If the optional flag \var{quote} is | |
|
19164
5d6b2c17ea2c
For the escape() function, added a reference to the quoteattrs() function
Fred Drake <fdrake@acm.org>
parents:
18574
diff
changeset
|
406 true, the double-quote character (\character{"}) is also translated; |
|
18411
eeb2e77c5bad
Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents:
18338
diff
changeset
|
407 this helps for inclusion in an HTML attribute value, as in \code{<A |
|
25008
acecdc4f7333
Fix typo reported to python-docs.
Fred Drake <fdrake@acm.org>
parents:
24935
diff
changeset
|
408 HREF="...">}. If the value to be quoted might include single- or |
|
19164
5d6b2c17ea2c
For the escape() function, added a reference to the quoteattrs() function
Fred Drake <fdrake@acm.org>
parents:
18574
diff
changeset
|
409 double-quote characters, or both, consider using the |
|
5d6b2c17ea2c
For the escape() function, added a reference to the quoteattrs() function
Fred Drake <fdrake@acm.org>
parents:
18574
diff
changeset
|
410 \function{quoteattr()} function in the \refmodule{xml.sax.saxutils} |
|
5d6b2c17ea2c
For the escape() function, added a reference to the quoteattrs() function
Fred Drake <fdrake@acm.org>
parents:
18574
diff
changeset
|
411 module instead. |
| 2449 | 412 \end{funcdesc} |
| 413 | |
|
3856
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
414 |
|
21504
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
415 \subsection{Caring about security \label{cgi-security}} |
|
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
416 |
|
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
417 \indexii{CGI}{security} |
| 2449 | 418 |
|
18411
eeb2e77c5bad
Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents:
18338
diff
changeset
|
419 There's one important rule: if you invoke an external program (via the |
|
eeb2e77c5bad
Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents:
18338
diff
changeset
|
420 \function{os.system()} or \function{os.popen()} functions. or others |
|
eeb2e77c5bad
Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents:
18338
diff
changeset
|
421 with similar functionality), make very sure you don't pass arbitrary |
|
eeb2e77c5bad
Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents:
18338
diff
changeset
|
422 strings received from the client to the shell. This is a well-known |
|
18574
346dcafc878b
Minor changes to match the style guide.
Fred Drake <fdrake@acm.org>
parents:
18411
diff
changeset
|
423 security hole whereby clever hackers anywhere on the Web can exploit a |
|
18411
eeb2e77c5bad
Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents:
18338
diff
changeset
|
424 gullible CGI script to invoke arbitrary shell commands. Even parts of |
|
eeb2e77c5bad
Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents:
18338
diff
changeset
|
425 the URL or field names cannot be trusted, since the request doesn't |
|
eeb2e77c5bad
Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents:
18338
diff
changeset
|
426 have to come from your form! |
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
427 |
|
3856
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
428 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
|
429 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
|
430 alphanumeric characters, dashes, underscores, and periods. |
|
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
431 |
|
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
432 |
|
21062
bc02c3b09626
Clean up some markup cruft. A number of the macros that take no
Fred Drake <fdrake@acm.org>
parents:
19866
diff
changeset
|
433 \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
|
434 |
|
3856
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
435 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
|
436 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
|
437 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
|
438 |
|
3856
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
439 Make sure that your script is readable and executable by ``others''; the |
| 7663 | 440 \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
|
441 \var{filename}}). Make sure that the first line of the script contains |
| 7663 | 442 \code{\#!} starting in column 1 followed by the pathname of the Python |
| 443 interpreter, for instance: | |
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
444 |
|
7277
bf4e790bd61a
Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents:
7086
diff
changeset
|
445 \begin{verbatim} |
| 5818 | 446 #!/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
|
447 \end{verbatim} |
| 7663 | 448 |
|
3856
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
449 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
|
450 |
|
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
451 Make sure that any files your script needs to read or write are |
| 7663 | 452 readable or writable, respectively, by ``others'' --- their mode |
| 453 should be \code{0644} for readable and \code{0666} for writable. This | |
| 454 is because, for security reasons, the HTTP server executes your script | |
| 455 as user ``nobody'', without any special privileges. It can only read | |
| 456 (write, execute) files that everybody can read (write, execute). The | |
| 457 current directory at execution time is also different (it is usually | |
| 458 the server's cgi-bin directory) and the set of environment variables | |
|
18574
346dcafc878b
Minor changes to match the style guide.
Fred Drake <fdrake@acm.org>
parents:
18411
diff
changeset
|
459 is also different from what you get when you log in. In particular, don't |
| 7663 | 460 count on the shell's search path for executables (\envvar{PATH}) or |
| 461 the Python module search path (\envvar{PYTHONPATH}) to be set to | |
| 462 anything interesting. | |
|
3856
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
463 |
|
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
464 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
|
465 default module search path, you can change the path in your script, |
|
18411
eeb2e77c5bad
Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents:
18338
diff
changeset
|
466 before importing other modules. For example: |
|
3856
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
467 |
|
7277
bf4e790bd61a
Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents:
7086
diff
changeset
|
468 \begin{verbatim} |
| 5818 | 469 import sys |
| 470 sys.path.insert(0, "/usr/home/joe/lib/python") | |
| 471 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
|
472 \end{verbatim} |
| 7663 | 473 |
|
3856
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
474 (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
|
475 |
| 7086 | 476 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
|
477 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
|
478 |
|
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
479 |
|
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
480 \subsection{Testing your CGI script} |
|
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
481 |
|
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
482 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
|
483 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
|
484 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
|
485 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
|
486 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
|
487 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
|
488 error to the client. |
|
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
489 |
|
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
490 Assuming your script has no syntax errors, yet it does not work, you |
| 7663 | 491 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
|
492 |
|
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
493 |
|
21504
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
494 \subsection{Debugging CGI scripts} \indexii{CGI}{debugging} |
|
3856
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
495 |
| 7663 | 496 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
|
497 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
|
498 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
|
499 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
|
500 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
|
501 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
|
502 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
|
503 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
|
504 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
|
505 |
|
7277
bf4e790bd61a
Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents:
7086
diff
changeset
|
506 \begin{verbatim} |
| 5818 | 507 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
|
508 \end{verbatim} |
| 7663 | 509 |
|
3856
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
510 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
|
511 -- perhaps you need to install it in a different directory. If it |
|
18411
eeb2e77c5bad
Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents:
18338
diff
changeset
|
512 gives another error, there's an installation problem that |
|
3856
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
513 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
|
514 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
|
515 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
|
516 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
|
517 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
|
518 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
|
519 |
| 7663 | 520 The next step could be to call the \module{cgi} module's |
| 521 \function{test()} function from your script: replace its main code | |
| 522 with the single statement | |
|
3856
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
523 |
|
7277
bf4e790bd61a
Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents:
7086
diff
changeset
|
524 \begin{verbatim} |
| 5818 | 525 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
|
526 \end{verbatim} |
| 7663 | 527 |
|
3856
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
528 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
|
529 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
|
530 |
|
18411
eeb2e77c5bad
Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents:
18338
diff
changeset
|
531 When an ordinary Python script raises an unhandled exception (for |
|
eeb2e77c5bad
Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents:
18338
diff
changeset
|
532 whatever reason: of a typo in a module name, a file that can't be |
|
eeb2e77c5bad
Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents:
18338
diff
changeset
|
533 opened, etc.), the Python interpreter prints a nice traceback and |
|
eeb2e77c5bad
Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents:
18338
diff
changeset
|
534 exits. While the Python interpreter will still do this when your CGI |
|
eeb2e77c5bad
Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents:
18338
diff
changeset
|
535 script raises an exception, most likely the traceback will end up in |
|
21504
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
536 one of the HTTP server's log files, or be discarded altogether. |
|
3856
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
537 |
|
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
538 Fortunately, once you have managed to get your script to execute |
|
21504
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
539 \emph{some} code, you can easily send tracebacks to the Web browser |
|
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
540 using the \refmodule{cgitb} module. If you haven't done so already, |
|
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
541 just add the line: |
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
542 |
|
7277
bf4e790bd61a
Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents:
7086
diff
changeset
|
543 \begin{verbatim} |
|
21504
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
544 import cgitb; cgitb.enable() |
|
7277
bf4e790bd61a
Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents:
7086
diff
changeset
|
545 \end{verbatim} |
| 7663 | 546 |
|
21504
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
547 to the top of your script. Then try running it again; when a |
|
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
548 problem occurs, you should see a detailed report that will |
|
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
549 likely make apparent the cause of the crash. |
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
550 |
|
21504
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
551 If you suspect that there may be a problem in importing the |
|
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
552 \refmodule{cgitb} module, you can use an even more robust approach |
|
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
553 (which only uses built-in modules): |
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
554 |
|
7277
bf4e790bd61a
Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents:
7086
diff
changeset
|
555 \begin{verbatim} |
| 5818 | 556 import sys |
| 557 sys.stderr = sys.stdout | |
|
14196
41234ae95d2a
Closing patch #101120 -- After everyone agreed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
13625
diff
changeset
|
558 print "Content-Type: text/plain" |
| 5818 | 559 print |
| 560 ...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
|
561 \end{verbatim} |
| 7663 | 562 |
|
3856
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
563 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
|
564 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
|
565 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
|
566 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
|
567 first two lines have been printed, a traceback will be displayed. |
|
21504
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
568 Because no HTML interpretation is going on, the traceback will be |
|
3856
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
569 readable. |
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
570 |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
571 |
|
3856
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
572 \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
|
573 |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
574 \begin{itemize} |
|
3856
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
575 \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
|
576 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
|
577 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
|
578 |
|
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
579 \item Check the installation instructions above. |
|
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
580 |
| 7663 | 581 \item Check the HTTP server's log files. (\samp{tail -f logfile} in a |
| 582 separate window may be useful!) | |
|
3856
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
583 |
|
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
584 \item Always check a script for syntax errors first, by doing something |
| 7663 | 585 like \samp{python script.py}. |
|
3856
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
586 |
|
21504
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
587 \item If your script does not have any syntax errors, try adding |
|
a03b13be2f68
Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
588 \samp{import cgitb; cgitb.enable()} to the top of the script. |
|
3856
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
589 |
|
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
590 \item When invoking external programs, make sure they can be found. |
| 7663 | 591 Usually, this means using absolute path names --- \envvar{PATH} is |
| 592 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
|
593 |
|
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
594 \item When reading or writing external files, make sure they can be read |
|
30842
fe9a5a2dd2c1
Avoid giving advice that's bad for security, as per SF bug #823515
Alex Martelli <aleaxit@gmail.com>
parents:
30134
diff
changeset
|
595 or written by the userid under which your CGI script will be running: |
|
fe9a5a2dd2c1
Avoid giving advice that's bad for security, as per SF bug #823515
Alex Martelli <aleaxit@gmail.com>
parents:
30134
diff
changeset
|
596 this is typically the userid under which the web server is running, or some |
|
fe9a5a2dd2c1
Avoid giving advice that's bad for security, as per SF bug #823515
Alex Martelli <aleaxit@gmail.com>
parents:
30134
diff
changeset
|
597 explicitly specified userid for a web server's \samp{suexec} feature. |
|
3856
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
598 |
|
5830ede4086c
Document the *new* cgi.py
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
599 \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
|
600 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
|
601 \end{itemize} |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
602 |