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

annotate Doc/lib/libcgi.tex @ 19283:b865cd5c1925 legacy-trunk

Added comments before recently added/assigned slots in the type object, so the backward compatibility issues will be easier to understand. I only added comments indicating additions and assignments back to Python 2.0.

author	Fred Drake <fdrake@acm.org>
date	Wed, 15 Aug 2001 18:32:33 +0000
parents	5d6b2c17ea2c
children	a34991b91008

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}
19164 5d6b2c17ea2c For the escape() function, added a reference to the quoteattrs() function Fred Drake <fdrake@acm.org> parents: 18574 diff changeset	122 ListType = type([])
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
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	168 \subsection{Old classes}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	169
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	170 These classes, present in earlier versions of the \module{cgi} module,
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	171 are still supported for backward compatibility. New applications
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	172 should use the \class{FieldStorage} class.
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	173
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	174 \class{SvFormContentDict} stores single value form content as
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	175 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	176
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	177 \class{FormContentDict} stores multiple value form content as a
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	178 dictionary (the form items are lists of values). Useful if your form
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	179 contains multiple fields with the same name.
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	180
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	181 Other classes (\class{FormContent}, \class{InterpFormContentDict}) are
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	182 present for backwards compatibility with really old applications only.
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	183 If you still use these and would be inconvenienced when they
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	184 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	185
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	186
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	187 \subsection{Functions}
4728 b218f294b726 (lib<all sorts of stuff>.tex): Fred Drake <fdrake@acm.org> parents: 4487 diff changeset	188 \nodename{Functions in cgi module}
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	189
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	190 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	191 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	192 circumstances.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	193
6153 17a26f986007 Removed some colons that shouldn't be there (probably leftovers from Guido van Rossum <guido@python.org> parents: 5871 diff changeset	194 \begin{funcdesc}{parse}{fp}
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	195 Parse a query in the environment or from a file (default
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	196 \code{sys.stdin}).
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	197 \end{funcdesc}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	198
10951 b6d3d17195dc Patch by Jim Fulton to document the new parse_qls(). Guido van Rossum <guido@python.org> parents: 9903 diff changeset	199 \begin{funcdesc}{parse_qs}{qs\optional{, keep_blank_values, strict_parsing}}
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	200 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	201 \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	202 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	203 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	204
b6d3d17195dc Patch by Jim Fulton to document the new parse_qls(). Guido van Rossum <guido@python.org> parents: 9903 diff changeset	205 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	206 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	207 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	208 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	209 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	210 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	211 not included.
b6d3d17195dc Patch by Jim Fulton to document the new parse_qls(). Guido van Rossum <guido@python.org> parents: 9903 diff changeset	212
b6d3d17195dc Patch by Jim Fulton to document the new parse_qls(). Guido van Rossum <guido@python.org> parents: 9903 diff changeset	213 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	214 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	215 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	216 exception.
b6d3d17195dc Patch by Jim Fulton to document the new parse_qls(). Guido van Rossum <guido@python.org> parents: 9903 diff changeset	217 \end{funcdesc}
b6d3d17195dc Patch by Jim Fulton to document the new parse_qls(). Guido van Rossum <guido@python.org> parents: 9903 diff changeset	218
b6d3d17195dc Patch by Jim Fulton to document the new parse_qls(). Guido van Rossum <guido@python.org> parents: 9903 diff changeset	219 \begin{funcdesc}{parse_qsl}{qs\optional{, keep_blank_values, strict_parsing}}
b6d3d17195dc Patch by Jim Fulton to document the new parse_qls(). Guido van Rossum <guido@python.org> parents: 9903 diff changeset	220 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	221 \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	222 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	223
b6d3d17195dc Patch by Jim Fulton to document the new parse_qls(). Guido van Rossum <guido@python.org> parents: 9903 diff changeset	224 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	225 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	226 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	227 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	228 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	229 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	230 not included.
b6d3d17195dc Patch by Jim Fulton to document the new parse_qls(). Guido van Rossum <guido@python.org> parents: 9903 diff changeset	231
b6d3d17195dc Patch by Jim Fulton to document the new parse_qls(). Guido van Rossum <guido@python.org> parents: 9903 diff changeset	232 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	233 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	234 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	235 exception.
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	236 \end{funcdesc}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	237
7712 0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain, Fred Drake <fdrake@acm.org> parents: 7663 diff changeset	238 \begin{funcdesc}{parse_multipart}{fp, pdict}
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	239 Parse input of type \mimetype{multipart/form-data} (for
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	240 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	241 \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	242 the \mailheader{Content-Type} header.
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	243
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	244 Returns a dictionary just like \function{parse_qs()} keys are the
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	245 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	246 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	247 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	248 which is much more flexible.
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	249
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	250 Note that this does not parse nested multipart parts --- use
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	251 \class{FieldStorage} for that.
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	252 \end{funcdesc}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	253
6153 17a26f986007 Removed some colons that shouldn't be there (probably leftovers from Guido van Rossum <guido@python.org> parents: 5871 diff changeset	254 \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	255 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	256 value and a dictionary of parameters.
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	257 \end{funcdesc}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	258
6153 17a26f986007 Removed some colons that shouldn't be there (probably leftovers from Guido van Rossum <guido@python.org> parents: 5871 diff changeset	259 \begin{funcdesc}{test}{}
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	260 Robust test CGI script, usable as main program.
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	261 Writes minimal HTTP headers and formats all information provided to
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	262 the script in HTML form.
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	263 \end{funcdesc}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	264
6153 17a26f986007 Removed some colons that shouldn't be there (probably leftovers from Guido van Rossum <guido@python.org> parents: 5871 diff changeset	265 \begin{funcdesc}{print_environ}{}
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	266 Format the shell environment in HTML.
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	267 \end{funcdesc}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	268
6153 17a26f986007 Removed some colons that shouldn't be there (probably leftovers from Guido van Rossum <guido@python.org> parents: 5871 diff changeset	269 \begin{funcdesc}{print_form}{form}
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	270 Format a form in HTML.
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	271 \end{funcdesc}
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	272
6153 17a26f986007 Removed some colons that shouldn't be there (probably leftovers from Guido van Rossum <guido@python.org> parents: 5871 diff changeset	273 \begin{funcdesc}{print_directory}{}
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	274 Format the current directory in HTML.
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	275 \end{funcdesc}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	276
6153 17a26f986007 Removed some colons that shouldn't be there (probably leftovers from Guido van Rossum <guido@python.org> parents: 5871 diff changeset	277 \begin{funcdesc}{print_environ_usage}{}
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	278 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	279 HTML.
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	280 \end{funcdesc}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	281
7712 0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain, Fred Drake <fdrake@acm.org> parents: 7663 diff changeset	282 \begin{funcdesc}{escape}{s\optional{, quote}}
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	283 Convert the characters
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	284 \character{\&}, \character{<} and \character{>} in string \var{s} to
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	285 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	286 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	287 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	288 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	289 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	290 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	291 \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	292 module instead.
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	293 \end{funcdesc}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	294
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	295
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	296 \subsection{Caring about security}
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	297
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	298 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	299 \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	300 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	301 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	302 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	303 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	304 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	305 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	306
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	307 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	308 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	309 alphanumeric characters, dashes, underscores, and periods.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	310
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	311
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	312 \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	313
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	314 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	315 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	316 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	317
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	318 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	319 \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	320 \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	321 \code{\#!} starting in column 1 followed by the pathname of the Python
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	322 interpreter, for instance:
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	323
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 7086 diff changeset	324 \begin{verbatim}
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	325 #!/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	326 \end{verbatim}
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	327
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	328 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	329
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	330 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	331 readable or writable, respectively, by ``others'' --- their mode
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	332 should be \code{0644} for readable and \code{0666} for writable. This
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	333 is because, for security reasons, the HTTP server executes your script
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	334 as user ``nobody'', without any special privileges. It can only read
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	335 (write, execute) files that everybody can read (write, execute). The
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	336 current directory at execution time is also different (it is usually
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	337 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	338 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	339 count on the shell's search path for executables (\envvar{PATH}) or
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	340 the Python module search path (\envvar{PYTHONPATH}) to be set to
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	341 anything interesting.
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	342
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	343 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	344 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	345 before importing other modules. For example:
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	346
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 7086 diff changeset	347 \begin{verbatim}
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	348 import sys
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	349 sys.path.insert(0, "/usr/home/joe/lib/python")
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	350 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	351 \end{verbatim}
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	352
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	353 (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	354
7086 fcb2e3ee8995 Consistency: Fred Drake <fdrake@acm.org> parents: 6788 diff changeset	355 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	356 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	357
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	358
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	359 \subsection{Testing your CGI script}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	360
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	361 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	362 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	363 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	364 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	365 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	366 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	367 error to the client.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	368
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	369 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	370 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	371
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	372
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	373 \subsection{Debugging CGI scripts}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	374
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	375 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	376 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	377 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	378 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	379 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	380 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	381 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	382 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	383 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	384
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 7086 diff changeset	385 \begin{verbatim}
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	386 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	387 \end{verbatim}
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	388
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	389 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	390 -- 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	391 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	392 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	393 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	394 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	395 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	396 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	397 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	398
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	399 The next step could be to call the \module{cgi} module's
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	400 \function{test()} function from your script: replace its main code
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	401 with the single statement
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	402
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 7086 diff changeset	403 \begin{verbatim}
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	404 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	405 \end{verbatim}
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	406
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	407 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	408 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	409
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	410 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	411 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	412 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	413 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	414 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	415 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	416
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	417 Fortunately, once you have managed to get your script to execute
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	418 \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	419 to be printed. The \function{test()} function below in this module is
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	420 an example. Here are the rules:
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	421
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	422 \begin{enumerate}
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	423 \item Import the traceback module before entering the \keyword{try}
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	424 ... \keyword{except} statement
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	425
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	426 \item Assign \code{sys.stderr} to be \code{sys.stdout}
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	427
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	428 \item Make sure you finish printing the headers and the blank line
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	429 early
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	430
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	431 \item Wrap all remaining code in a \keyword{try} ... \keyword{except}
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	432 statement
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	433
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	434 \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	435 \end{enumerate}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	436
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	437 For example:
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	438
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 7086 diff changeset	439 \begin{verbatim}
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	440 import sys
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	441 import traceback
14196 41234ae95d2a Closing patch #101120 -- After everyone agreed. Moshe Zadka <moshez@math.huji.ac.il> parents: 13625 diff changeset	442 print "Content-Type: text/html"
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	443 print
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	444 sys.stderr = sys.stdout
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	445 try:
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	446 ...your code here...
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	447 except:
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	448 print "\n\n<PRE>"
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	449 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	450 \end{verbatim}
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	451
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	452 Notes: The assignment to \code{sys.stderr} is needed because the
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	453 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	454 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	455 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	456
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	457 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	458 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	459 built-in modules):
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	460
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 7086 diff changeset	461 \begin{verbatim}
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	462 import sys
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	463 sys.stderr = sys.stdout
14196 41234ae95d2a Closing patch #101120 -- After everyone agreed. Moshe Zadka <moshez@math.huji.ac.il> parents: 13625 diff changeset	464 print "Content-Type: text/plain"
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	465 print
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	466 ...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	467 \end{verbatim}
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	468
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	469 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	470 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	471 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	472 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	473 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	474 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	475 readable.
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	476
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	477
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	478 \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	479
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	480 \begin{itemize}
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	481 \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	482 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	483 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	484
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	485 \item Check the installation instructions above.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	486
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	487 \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	488 separate window may be useful!)
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	489
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	490 \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	491 like \samp{python script.py}.
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	492
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	493 \item When using any of the debugging techniques, don't forget to add
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	494 \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	495
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	496 \item When invoking external programs, make sure they can be found.
7663 acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	497 Usually, this means using absolute path names --- \envvar{PATH} is
acd393a93ed0 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	498 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	499
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	500 \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	501 or written by every user on the system.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	502
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	503 \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	504 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	505 \end{itemize}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	506

Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libcgi.tex @ 19283:b865cd5c1925 legacy-trunk