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

annotate Doc/lib/libcgi.tex @ 18830:fdb388f2df4e legacy-trunk

Don't "import *" from stat at all -- just import what's needed, and do it back in copy_file() (not at module level).

author	Greg Ward <gward@python.net>
date	Wed, 25 Jul 2001 19:48:03 +0000
parents	346dcafc878b
children	5d6b2c17ea2c

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

Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libcgi.tex @ 18830:fdb388f2df4e legacy-trunk