cpython-lru_cache-weakref: Doc/lib/libcgi.tex annotate

annotate Doc/lib/libcgi.tex @ 20010:d03c19db3094 legacy-trunk

Document new file() constructor, with the body of open()'s text, plus a "new in 2.2" blurb at the end. Replace open()'s text by pointing back to file().

author	Tim Peters <tim.peters@gmail.com>
date	Thu, 20 Sep 2001 19:55:29 +0000
parents	a34991b91008
children	bc02c3b09626

rev	line source
8918 acfffe14628e New section header style. Fred Drake <fdrake@acm.org> parents: 8716 diff changeset	1 \section{\module{cgi} ---
acfffe14628e New section header style. Fred Drake <fdrake@acm.org> parents: 8716 diff changeset	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 acfffe14628e New section header style. Fred Drake <fdrake@acm.org> parents: 8716 diff changeset	5 \modulesynopsis{Common Gateway Interface support, used to interpret
acfffe14628e New section header style. Fred Drake <fdrake@acm.org> parents: 8716 diff changeset	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 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	8 \indexii{WWW}{server}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	9 \indexii{CGI}{protocol}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	10 \indexii{HTTP}{protocol}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	11 \indexii{MIME}{headers}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	12 \index{URL}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	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 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	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 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	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 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	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 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	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 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	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 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	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}
14196 41234ae95d2a Closing patch #101120 -- After everyone agreed. Moshe Zadka <moshez@math.huji.ac.il> parents: 13625 diff changeset	48 print "Content-Type: text/html" # HTML is following
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	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 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	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 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	57 print "<TITLE>CGI script output</TITLE>"
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	58 print "<H1>This is my first CGI script</H1>"
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	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 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	61
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	62 \subsection{Using the cgi module}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	63 \nodename{Using the cgi module}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	64
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	65 Begin by writing \samp{import cgi}. Do not use \samp{from cgi import
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	66 *} --- the module defines all sorts of names for its own use or for
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	67 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	68
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	69 It's best to use the \class{FieldStorage} class. The other classes
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	70 defined in this module are provided mostly for backward compatibility.
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	71 Instantiate it exactly once, without arguments. This reads the form
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	72 contents from standard input or the environment (depending on the
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	73 value of various environment variables set according to the CGI
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	74 standard). Since it may consume standard input, it should be
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	75 instantiated only once.
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	76
14196 41234ae95d2a Closing patch #101120 -- After everyone agreed. Moshe Zadka <moshez@math.huji.ac.il> parents: 13625 diff changeset	77 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	78 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	79 \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	80 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	81 and do not appear in the dictionary; to keep such values, provide
19164 5d6b2c17ea2c For the escape() function, added a reference to the quoteattrs() function Fred Drake <fdrake@acm.org> parents: 18574 diff changeset	82 a true value for the the optional \var{keep_blank_values} keyword
5d6b2c17ea2c For the escape() function, added a reference to the quoteattrs() function Fred Drake <fdrake@acm.org> parents: 18574 diff changeset	83 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	84
41234ae95d2a Closing patch #101120 -- After everyone agreed. Moshe Zadka <moshez@math.huji.ac.il> parents: 13625 diff changeset	85 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	86 \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	87 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	88 set to a non-empty string:
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	89
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 7086 diff changeset	90 \begin{verbatim}
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	91 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	92 if not (form.has_key("name") and form.has_key("addr")):
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	93 print "<H1>Error</H1>"
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	94 print "Please fill in the name and addr fields."
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	95 return
14196 41234ae95d2a Closing patch #101120 -- After everyone agreed. Moshe Zadka <moshez@math.huji.ac.il> parents: 13625 diff changeset	96 print "<p>name:", form["name"].value
41234ae95d2a Closing patch #101120 -- After everyone agreed. Moshe Zadka <moshez@math.huji.ac.il> parents: 13625 diff changeset	97 print "<p>addr:", form["addr"].value
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	98 ...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	99 \end{verbatim}
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	100
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	101 Here the fields, accessed through \samp{form[\var{key}]}, are
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	102 themselves instances of \class{FieldStorage} (or
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	103 \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	104 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	105 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	106 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	107 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	108
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	109 If the submitted form data contains more than one field with the same
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	110 name, the object retrieved by \samp{form[\var{key}]} is not a
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	111 \class{FieldStorage} or \class{MiniFieldStorage}
14196 41234ae95d2a Closing patch #101120 -- After everyone agreed. Moshe Zadka <moshez@math.huji.ac.il> parents: 13625 diff changeset	112 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	113 \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	114 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	115 (when your HTML form contains multiple fields with the same name), use
5d6b2c17ea2c For the escape() function, added a reference to the quoteattrs() function Fred Drake <fdrake@acm.org> parents: 18574 diff changeset	116 the \function{type()} built-in function to determine whether you
5d6b2c17ea2c For the escape() function, added a reference to the quoteattrs() function Fred Drake <fdrake@acm.org> parents: 18574 diff changeset	117 have a single instance or a list of instances. For example, this
5d6b2c17ea2c For the escape() function, added a reference to the quoteattrs() function Fred Drake <fdrake@acm.org> parents: 18574 diff changeset	118 code concatenates any number of username fields, separated by
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	119 commas:
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	120
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 7086 diff changeset	121 \begin{verbatim}
19866 a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	122 from types import ListType
19164 5d6b2c17ea2c For the escape() function, added a reference to the quoteattrs() function Fred Drake <fdrake@acm.org> parents: 18574 diff changeset	123
14196 41234ae95d2a Closing patch #101120 -- After everyone agreed. Moshe Zadka <moshez@math.huji.ac.il> parents: 13625 diff changeset	124 value = form.getvalue("username", "")
19164 5d6b2c17ea2c For the escape() function, added a reference to the quoteattrs() function Fred Drake <fdrake@acm.org> parents: 18574 diff changeset	125 if isinstance(value, ListType):
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	126 # Multiple username fields specified
14196 41234ae95d2a Closing patch #101120 -- After everyone agreed. Moshe Zadka <moshez@math.huji.ac.il> parents: 13625 diff changeset	127 usernames = ",".join(value)
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	128 else:
14196 41234ae95d2a Closing patch #101120 -- After everyone agreed. Moshe Zadka <moshez@math.huji.ac.il> parents: 13625 diff changeset	129 # Single or no username field specified
41234ae95d2a Closing patch #101120 -- After everyone agreed. Moshe Zadka <moshez@math.huji.ac.il> parents: 13625 diff changeset	130 usernames = value
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 7086 diff changeset	131 \end{verbatim}
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	132
14196 41234ae95d2a Closing patch #101120 -- After everyone agreed. Moshe Zadka <moshez@math.huji.ac.il> parents: 13625 diff changeset	133 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	134 \member{value} attribute or the \function{getvalue()} method reads the
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	135 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	136 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	137 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	138 leisure from the \member{file} attribute:
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	139
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 7086 diff changeset	140 \begin{verbatim}
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	141 fileitem = form["userfile"]
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	142 if fileitem.file:
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	143 # It's an uploaded file; count lines
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	144 linecount = 0
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	145 while 1:
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	146 line = fileitem.file.readline()
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	147 if not line: break
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	148 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	149 \end{verbatim}
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	150
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	151 The file upload draft standard entertains the possibility of uploading
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	152 multiple files from one field (using a recursive
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	153 \mimetype{multipart/*} encoding). When this occurs, the item will be
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	154 a dictionary-like \class{FieldStorage} item. This can be determined
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	155 by testing its \member{type} attribute, which should be
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	156 \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	157 \mimetype{multipart/*}). In this case, it can be iterated over
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	158 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	159
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	160 When a form is submitted in the ``old'' format (as the query string or
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	161 as a single data part of type
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	162 \mimetype{application/x-www-form-urlencoded}), the items will actually
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	163 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	164 \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	165 always \code{None}.
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	166
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	167
19866 a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	168 \subsection{Higher Level Interface}
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	169
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	170 \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	171
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	172 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	173 \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	174 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	175 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	176 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	177 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	178
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	179 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	180 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	181 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	182
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	183 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	184 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	185
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	186 \begin{verbatim}
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	187 from types import ListType
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	188
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	189 item = form.getvalue("item")
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	190 if isinstance(item, ListType):
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	191 # 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	192 else:
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	193 # 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	194 \end{verbatim}
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	195
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	196 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	197 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	198
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	199 \begin{verbatim}
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	200 <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	201 <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	202 \end{verbatim}
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	203
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	204 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	205 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	206 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	207 example this code:
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	208
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	209 \begin{verbatim}
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	210 user = form.getvalue("user").toupper()
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	211 \end{verbatim}
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	212
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	213 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	214 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	215 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	216 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	217 \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	218 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	219 (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	220 \exception{AttributeError} exception.
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	221
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	222 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	223 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	224 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	225 scripts.
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	226
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	227 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	228 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	229
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	230 \begin{methoddesc}[FieldStorage]{getfirst}{name\optional{, default}}
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	231 Thin method always returns only one value associated with form field
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	232 \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	233 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	234 in which the values are received may vary from browser to browser
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	235 and should not be counted on. If no such form field or value exists
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	236 then the method returns the value specified by the optional
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	237 parameter \var{default}. This parameter defaults to \code{None} if
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	238 not specified.
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	239 \end{methoddesc}
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	240
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	241 \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	242 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	243 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	244 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	245 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	246 \end{methoddesc}
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	247
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	248 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	249
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	250 \begin{verbatim}
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	251 import cgi
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	252 form = cgi.FieldStorage()
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	253 user = form.getfirst("user").toupper() # This way it's safe.
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	254 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	255 do_something(item)
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	256 \end{verbatim}
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	257
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	258
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	259 \subsection{Old classes}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	260
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	261 These classes, present in earlier versions of the \module{cgi} module,
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	262 are still supported for backward compatibility. New applications
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	263 should use the \class{FieldStorage} class.
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	264
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	265 \class{SvFormContentDict} stores single value form content as
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	266 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	267
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	268 \class{FormContentDict} stores multiple value form content as a
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	269 dictionary (the form items are lists of values). Useful if your form
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	270 contains multiple fields with the same name.
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	271
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	272 Other classes (\class{FormContent}, \class{InterpFormContentDict}) are
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	273 present for backwards compatibility with really old applications only.
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	274 If you still use these and would be inconvenienced when they
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	275 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	276
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	277
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	278 \subsection{Functions}
4728 b218f294b726 (lib<all sorts of stuff>.tex): Fred Drake <fdrake@acm.org> parents: 4487 diff changeset	279 \nodename{Functions in cgi module}
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	280
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	281 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	282 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	283 circumstances.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	284
19866 a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	285 \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	286 strict_parsing}}}
a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	287 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	288 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	289 \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	290 unchanged.
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	291 \end{funcdesc}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	292
19866 a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	293 \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	294 strict_parsing}}}
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	295 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	296 \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	297 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	298 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	299
b6d3d17195dc Patch by Jim Fulton to document the new parse_qls(). Guido van Rossum <guido@python.org> parents: 9903 diff changeset	300 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	301 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	302 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	303 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	304 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	305 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	306 not included.
b6d3d17195dc Patch by Jim Fulton to document the new parse_qls(). Guido van Rossum <guido@python.org> parents: 9903 diff changeset	307
b6d3d17195dc Patch by Jim Fulton to document the new parse_qls(). Guido van Rossum <guido@python.org> parents: 9903 diff changeset	308 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	309 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	310 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	311 exception.
b6d3d17195dc Patch by Jim Fulton to document the new parse_qls(). Guido van Rossum <guido@python.org> parents: 9903 diff changeset	312 \end{funcdesc}
b6d3d17195dc Patch by Jim Fulton to document the new parse_qls(). Guido van Rossum <guido@python.org> parents: 9903 diff changeset	313
19866 a34991b91008 Added documentation on the getfirst() and getlist() methods of the Fred Drake <fdrake@acm.org> parents: 19164 diff changeset	314 \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	315 strict_parsing}}}
10951 b6d3d17195dc Patch by Jim Fulton to document the new parse_qls(). Guido van Rossum <guido@python.org> parents: 9903 diff changeset	316 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	317 \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	318 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	319
b6d3d17195dc Patch by Jim Fulton to document the new parse_qls(). Guido van Rossum <guido@python.org> parents: 9903 diff changeset	320 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	321 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	322 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	323 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	324 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	325 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	326 not included.
b6d3d17195dc Patch by Jim Fulton to document the new parse_qls(). Guido van Rossum <guido@python.org> parents: 9903 diff changeset	327
b6d3d17195dc Patch by Jim Fulton to document the new parse_qls(). Guido van Rossum <guido@python.org> parents: 9903 diff changeset	328 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	329 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	330 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	331 exception.
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	332 \end{funcdesc}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	333
7712 0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain, Fred Drake <fdrake@acm.org> parents: 7663 diff changeset	334 \begin{funcdesc}{parse_multipart}{fp, pdict}
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	335 Parse input of type \mimetype{multipart/form-data} (for
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	336 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	337 \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	338 the \mailheader{Content-Type} header.
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	339
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	340 Returns a dictionary just like \function{parse_qs()} keys are the
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	341 field names, each value is a list of values for that field. This is
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	342 easy to use but not much good if you are expecting megabytes to be
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	343 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	344 which is much more flexible.
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	345
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	346 Note that this does not parse nested multipart parts --- use
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	347 \class{FieldStorage} for that.
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	348 \end{funcdesc}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	349
6153 17a26f986007 Removed some colons that shouldn't be there (probably leftovers from Guido van Rossum <guido@python.org> parents: 5871 diff changeset	350 \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	351 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	352 value and a dictionary of parameters.
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	353 \end{funcdesc}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	354
6153 17a26f986007 Removed some colons that shouldn't be there (probably leftovers from Guido van Rossum <guido@python.org> parents: 5871 diff changeset	355 \begin{funcdesc}{test}{}
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	356 Robust test CGI script, usable as main program.
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	357 Writes minimal HTTP headers and formats all information provided to
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	358 the script in HTML form.
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	359 \end{funcdesc}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	360
6153 17a26f986007 Removed some colons that shouldn't be there (probably leftovers from Guido van Rossum <guido@python.org> parents: 5871 diff changeset	361 \begin{funcdesc}{print_environ}{}
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	362 Format the shell environment in HTML.
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	363 \end{funcdesc}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	364
6153 17a26f986007 Removed some colons that shouldn't be there (probably leftovers from Guido van Rossum <guido@python.org> parents: 5871 diff changeset	365 \begin{funcdesc}{print_form}{form}
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	366 Format a form in HTML.
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	367 \end{funcdesc}
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	368
6153 17a26f986007 Removed some colons that shouldn't be there (probably leftovers from Guido van Rossum <guido@python.org> parents: 5871 diff changeset	369 \begin{funcdesc}{print_directory}{}
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	370 Format the current directory in HTML.
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	371 \end{funcdesc}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	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}{print_environ_usage}{}
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	374 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	375 HTML.
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	376 \end{funcdesc}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	377
7712 0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain, Fred Drake <fdrake@acm.org> parents: 7663 diff changeset	378 \begin{funcdesc}{escape}{s\optional{, quote}}
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	379 Convert the characters
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	380 \character{\&}, \character{<} and \character{>} in string \var{s} to
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	381 HTML-safe sequences. Use this if you need to display text that might
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	382 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	383 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	384 this helps for inclusion in an HTML attribute value, as in \code{<A
19164 5d6b2c17ea2c For the escape() function, added a reference to the quoteattrs() function Fred Drake <fdrake@acm.org> parents: 18574 diff changeset	385 HREF="...">}. If the value to be qouted might include single- or
5d6b2c17ea2c For the escape() function, added a reference to the quoteattrs() function Fred Drake <fdrake@acm.org> parents: 18574 diff changeset	386 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	387 \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	388 module instead.
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	389 \end{funcdesc}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	390
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	391
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	392 \subsection{Caring about security}
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	393
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	394 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	395 \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	396 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	397 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	398 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	399 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	400 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	401 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	402
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	403 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	404 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	405 alphanumeric characters, dashes, underscores, and periods.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	406
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	407
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	408 \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	409
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	410 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	411 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	412 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	413
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	414 Make sure that your script is readable and executable by ``others''; the
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	415 \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	416 \var{filename}}). Make sure that the first line of the script contains
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	417 \code{\#!} starting in column 1 followed by the pathname of the Python
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	418 interpreter, for instance:
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	419
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 7086 diff changeset	420 \begin{verbatim}
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	421 #!/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	422 \end{verbatim}
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	423
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	424 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	425
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	426 Make sure that any files your script needs to read or write are
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	427 readable or writable, respectively, by ``others'' --- their mode
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	428 should be \code{0644} for readable and \code{0666} for writable. This
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	429 is because, for security reasons, the HTTP server executes your script
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	430 as user ``nobody'', without any special privileges. It can only read
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	431 (write, execute) files that everybody can read (write, execute). The
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	432 current directory at execution time is also different (it is usually
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	433 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	434 is also different from what you get when you log in. In particular, don't
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	435 count on the shell's search path for executables (\envvar{PATH}) or
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	436 the Python module search path (\envvar{PYTHONPATH}) to be set to
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	437 anything interesting.
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	438
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	439 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	440 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	441 before importing other modules. For example:
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	442
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 7086 diff changeset	443 \begin{verbatim}
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	444 import sys
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	445 sys.path.insert(0, "/usr/home/joe/lib/python")
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	446 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	447 \end{verbatim}
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	448
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	449 (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	450
7086 fcb2e3ee8995 Consistency: Fred Drake <fdrake@acm.org> parents: 6788 diff changeset	451 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	452 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	453
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	454
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	455 \subsection{Testing your CGI script}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	456
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	457 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	458 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	459 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	460 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	461 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	462 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	463 error to the client.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	464
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	465 Assuming your script has no syntax errors, yet it does not work, you
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	466 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	467
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	468
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	469 \subsection{Debugging CGI scripts}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	470
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	471 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	472 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	473 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	474 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	475 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	476 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	477 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	478 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	479 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	480
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 7086 diff changeset	481 \begin{verbatim}
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	482 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	483 \end{verbatim}
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	484
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	485 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	486 -- 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	487 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	488 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	489 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	490 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	491 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	492 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	493 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	494
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	495 The next step could be to call the \module{cgi} module's
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	496 \function{test()} function from your script: replace its main code
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	497 with the single statement
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	498
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 7086 diff changeset	499 \begin{verbatim}
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	500 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	501 \end{verbatim}
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	502
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	503 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	504 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	505
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	506 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	507 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	508 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	509 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	510 script raises an exception, most likely the traceback will end up in
eeb2e77c5bad Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18338 diff changeset	511 one of the HTTP server's log file, or be discarded altogether.
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	512
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	513 Fortunately, once you have managed to get your script to execute
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	514 \emph{some} code, it is easy to catch exceptions and cause a traceback
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	515 to be printed. The \function{test()} function below in this module is
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	516 an example. Here are the rules:
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	517
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	518 \begin{enumerate}
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	519 \item Import the traceback module before entering the \keyword{try}
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	520 ... \keyword{except} statement
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	521
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	522 \item Assign \code{sys.stderr} to be \code{sys.stdout}
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	523
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	524 \item Make sure you finish printing the headers and the blank line
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	525 early
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	526
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	527 \item Wrap all remaining code in a \keyword{try} ... \keyword{except}
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	528 statement
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	529
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	530 \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	531 \end{enumerate}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	532
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	533 For example:
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	534
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 7086 diff changeset	535 \begin{verbatim}
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	536 import sys
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	537 import traceback
14196 41234ae95d2a Closing patch #101120 -- After everyone agreed. Moshe Zadka <moshez@math.huji.ac.il> parents: 13625 diff changeset	538 print "Content-Type: text/html"
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	539 print
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	540 sys.stderr = sys.stdout
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	541 try:
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	542 ...your code here...
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	543 except:
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	544 print "\n\n<PRE>"
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	545 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	546 \end{verbatim}
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	547
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	548 Notes: The assignment to \code{sys.stderr} is needed because the
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	549 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	550 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	551 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	552
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	553 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	554 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	555 built-in modules):
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	556
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 7086 diff changeset	557 \begin{verbatim}
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	558 import sys
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	559 sys.stderr = sys.stdout
14196 41234ae95d2a Closing patch #101120 -- After everyone agreed. Moshe Zadka <moshez@math.huji.ac.il> parents: 13625 diff changeset	560 print "Content-Type: text/plain"
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	561 print
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	562 ...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	563 \end{verbatim}
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	564
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	565 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	566 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	567 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	568 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	569 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	570 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	571 readable.
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	572
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	573
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	574 \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	575
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	576 \begin{itemize}
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	577 \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	578 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	579 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	580
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	581 \item Check the installation instructions above.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	582
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	583 \item Check the HTTP server's log files. (\samp{tail -f logfile} in a
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	584 separate window may be useful!)
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	585
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	586 \item Always check a script for syntax errors first, by doing something
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	587 like \samp{python script.py}.
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	588
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	589 \item When using any of the debugging techniques, don't forget to add
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	590 \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	591
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	592 \item When invoking external programs, make sure they can be found.
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	593 Usually, this means using absolute path names --- \envvar{PATH} is
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	594 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	595
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	596 \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	597 or written by every user on the system.
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

Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libcgi.tex @ 20010:d03c19db3094 legacy-trunk