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

annotate Doc/libcgi.tex @ 6719:faebc1940432 legacy-trunk

Understand -Xlinker option.

author	Guido van Rossum <guido@python.org>
date	Tue, 02 Dec 1997 20:38:11 +0000
parents	e8681eda0854
children	ceabd50317e3

rev	line source
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	1 \section{Standard Module \sectcode{cgi}}
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	2 \label{module-cgi}
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	3 \stmodindex{cgi}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	4 \indexii{WWW}{server}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	5 \indexii{CGI}{protocol}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	6 \indexii{HTTP}{protocol}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	7 \indexii{MIME}{headers}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	8 \index{URL}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	9
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	10 \renewcommand{\indexsubitem}{(in module cgi)}
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	11
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	12 Support module for CGI (Common Gateway Interface) scripts.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	13
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	14 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	15 written in Python.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	16
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	17 \subsection{Introduction}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	18 \nodename{Introduction to the CGI module}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	19
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	20 A CGI script is invoked by an HTTP server, usually to process user
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	21 input submitted through an HTML \code{<FORM>} or \code{<ISINPUT>} element.
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	22
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	23 Most often, CGI scripts live in the server's special \code{cgi-bin}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	24 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	25 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	26 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	27 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	28
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	29 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	30 form data is read this way; at other times the form data is passed via
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	31 the ``query string'' part of the URL. This module (\code{cgi.py}) is intended
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	32 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	33 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	34 in debugging scripts, and the latest addition is support for file
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	35 uploads from a form (if your browser supports it -- Grail 0.3 and
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	36 Netscape 2.0 do).
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	37
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	38 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	39 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	40 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	41 generate a minimal header section looks like this:
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	42
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	43 \bcode\begin{verbatim}
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	44 print "Content-type: text/html" # HTML is following
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	45 print # blank line, end of headers
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	46 \end{verbatim}\ecode
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	47 %
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	48 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	49 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	50 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	51
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	52 \bcode\begin{verbatim}
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	53 print "<TITLE>CGI script output</TITLE>"
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	54 print "<H1>This is my first CGI script</H1>"
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	55 print "Hello, world!"
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	56 \end{verbatim}\ecode
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	57 %
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	58 (It may not be fully legal HTML according to the letter of the
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	59 standard, but any browser will understand it.)
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	60
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	61 \subsection{Using the cgi module}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	62 \nodename{Using the cgi module}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	63
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	64 Begin by writing \code{import cgi}. Don't use \code{from cgi import *} -- the
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	65 module defines all sorts of names for its own use or for backward
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	66 compatibility that you don't want in your namespace.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	67
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	68 It's best to use the \code{FieldStorage} class. The other classes define in this
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	69 module are provided mostly for backward compatibility. Instantiate it
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	70 exactly once, without arguments. This reads the form contents from
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	71 standard input or the environment (depending on the value of various
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	72 environment variables set according to the CGI standard). Since it may
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	73 consume standard input, it should be instantiated only once.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	74
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	75 The \code{FieldStorage} instance can be accessed as if it were a Python
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	76 dictionary. For instance, the following code (which assumes that the
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	77 \code{Content-type} header and blank line have already been printed) checks that
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	78 the fields \code{name} and \code{addr} are both set to a non-empty string:
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	79
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	80 \bcode\begin{verbatim}
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	81 form = cgi.FieldStorage()
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	82 form_ok = 0
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	83 if form.has_key("name") and form.has_key("addr"):
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	84 if form["name"].value != "" and form["addr"].value != "":
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	85 form_ok = 1
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	86 if not form_ok:
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	87 print "<H1>Error</H1>"
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	88 print "Please fill in the name and addr fields."
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	89 return
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	90 ...further form processing here...
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	91 \end{verbatim}\ecode
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	92 %
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	93 Here the fields, accessed through \code{form[key]}, are themselves instances
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	94 of \code{FieldStorage} (or \code{MiniFieldStorage}, depending on the form encoding).
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	95
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	96 If the submitted form data contains more than one field with the same
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	97 name, the object retrieved by \code{form[key]} is not a \code{(Mini)FieldStorage}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	98 instance but a list of such instances. If you expect this possibility
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	99 (i.e., when your HTML form comtains multiple fields with the same
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	100 name), use the \code{type()} function to determine whether you have a single
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	101 instance or a list of instances. For example, here's code that
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	102 concatenates any number of username fields, separated by commas:
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	103
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	104 \bcode\begin{verbatim}
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	105 username = form["username"]
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	106 if type(username) is type([]):
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	107 # Multiple username fields specified
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	108 usernames = ""
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	109 for item in username:
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	110 if usernames:
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	111 # Next item -- insert comma
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	112 usernames = usernames + "," + item.value
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	113 else:
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	114 # First item -- don't insert comma
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	115 usernames = item.value
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	116 else:
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	117 # Single username field specified
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	118 usernames = username.value
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	119 \end{verbatim}\ecode
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	120 %
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	121 If a field represents an uploaded file, the value attribute reads the
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	122 entire file in memory as a string. This may not be what you want. You can
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	123 test for an uploaded file by testing either the filename attribute or the
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	124 file attribute. You can then read the data at leasure from the file
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	125 attribute:
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	126
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	127 \bcode\begin{verbatim}
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	128 fileitem = form["userfile"]
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	129 if fileitem.file:
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	130 # It's an uploaded file; count lines
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	131 linecount = 0
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	132 while 1:
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	133 line = fileitem.file.readline()
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	134 if not line: break
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	135 linecount = linecount + 1
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	136 \end{verbatim}\ecode
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	137 %
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	138 The file upload draft standard entertains the possibility of uploading
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	139 multiple files from one field (using a recursive \code{multipart/*}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	140 encoding). When this occurs, the item will be a dictionary-like
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	141 FieldStorage item. This can be determined by testing its type
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	142 attribute, which should have the value \code{multipart/form-data} (or
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	143 perhaps another string beginning with \code{multipart/} It this case, it
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	144 can be iterated over recursively just like the top-level form object.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	145
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	146 When a form is submitted in the ``old'' format (as the query string or as a
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	147 single data part of type \code{application/x-www-form-urlencoded}), the items
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	148 will actually be instances of the class \code{MiniFieldStorage}. In this case,
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	149 the list, file and filename attributes are always \code{None}.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	150
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	151
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	152 \subsection{Old classes}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	153
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	154 These classes, present in earlier versions of the \code{cgi} module, are still
4487 e0c1bd0a74a9 Correct truncated paragraph. Guido van Rossum <guido@python.org> parents: 3856 diff changeset	155 supported for backward compatibility. New applications should use the
e0c1bd0a74a9 Correct truncated paragraph. Guido van Rossum <guido@python.org> parents: 3856 diff changeset	156 FieldStorage class.
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	157
6153 17a26f986007 Removed some colons that shouldn't be there (probably leftovers from Guido van Rossum <guido@python.org> parents: 5871 diff changeset	158 \code{SvFormContentDict}
17a26f986007 Removed some colons that shouldn't be there (probably leftovers from Guido van Rossum <guido@python.org> parents: 5871 diff changeset	159 single value form content as dictionary; assumes each
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	160 field name occurs in the form only once.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	161
6153 17a26f986007 Removed some colons that shouldn't be there (probably leftovers from Guido van Rossum <guido@python.org> parents: 5871 diff changeset	162 \code{FormContentDict}
17a26f986007 Removed some colons that shouldn't be there (probably leftovers from Guido van Rossum <guido@python.org> parents: 5871 diff changeset	163 multiple value form content as dictionary (the form
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	164 items are lists of values). Useful if your form contains multiple
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	165 fields with the same name.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	166
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	167 Other classes (\code{FormContent}, \code{InterpFormContentDict}) are present for
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	168 backwards compatibility with really old applications only. If you still
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	169 use these and would be inconvenienced when they disappeared from a next
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	170 version of this module, drop me a note.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	171
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	172
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	173 \subsection{Functions}
4728 b218f294b726 (lib<all sorts of stuff>.tex): Fred Drake <fdrake@acm.org> parents: 4487 diff changeset	174 \nodename{Functions in cgi module}
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	175
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	176 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	177 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	178 circumstances.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	179
6153 17a26f986007 Removed some colons that shouldn't be there (probably leftovers from Guido van Rossum <guido@python.org> parents: 5871 diff changeset	180 \begin{funcdesc}{parse}{fp}
17a26f986007 Removed some colons that shouldn't be there (probably leftovers from Guido van Rossum <guido@python.org> parents: 5871 diff changeset	181 Parse a query in the environment or from a file (default \code{sys.stdin}).
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	182 \end{funcdesc}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	183
6153 17a26f986007 Removed some colons that shouldn't be there (probably leftovers from Guido van Rossum <guido@python.org> parents: 5871 diff changeset	184 \begin{funcdesc}{parse_qs}{qs}
17a26f986007 Removed some colons that shouldn't be there (probably leftovers from Guido van Rossum <guido@python.org> parents: 5871 diff changeset	185 parse a query string given as a string argument (data of type
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	186 \code{application/x-www-form-urlencoded}).
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	187 \end{funcdesc}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	188
6153 17a26f986007 Removed some colons that shouldn't be there (probably leftovers from Guido van Rossum <guido@python.org> parents: 5871 diff changeset	189 \begin{funcdesc}{parse_multipart}{fp\, pdict}
17a26f986007 Removed some colons that shouldn't be there (probably leftovers from Guido van Rossum <guido@python.org> parents: 5871 diff changeset	190 parse input of type \code{multipart/form-data} (for
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	191 file uploads). Arguments are \code{fp} for the input file and
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	192 \code{pdict} for the dictionary containing other parameters of \code{content-type} header
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 Returns a dictionary just like \code{parse_qs()}
17a26f986007 Removed some colons that shouldn't be there (probably leftovers from Guido van Rossum <guido@python.org> parents: 5871 diff changeset	195 keys are the field names, each
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	196 value is a list of values for that field. This is easy to use but not
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	197 much good if you are expecting megabytes to be uploaded -- in that case,
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	198 use the \code{FieldStorage} class instead which is much more flexible. Note
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	199 that \code{content-type} is the raw, unparsed contents of the \code{content-type}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	200 header.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	201
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	202 Note that this does not parse nested multipart parts -- use \code{FieldStorage} for
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	203 that.
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	204 \end{funcdesc}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	205
6153 17a26f986007 Removed some colons that shouldn't be there (probably leftovers from Guido van Rossum <guido@python.org> parents: 5871 diff changeset	206 \begin{funcdesc}{parse_header}{string}
17a26f986007 Removed some colons that shouldn't be there (probably leftovers from Guido van Rossum <guido@python.org> parents: 5871 diff changeset	207 parse a header like \code{Content-type} into a main
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	208 content-type and a dictionary of parameters.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	209 \end{funcdesc}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	210
6153 17a26f986007 Removed some colons that shouldn't be there (probably leftovers from Guido van Rossum <guido@python.org> parents: 5871 diff changeset	211 \begin{funcdesc}{test}{}
17a26f986007 Removed some colons that shouldn't be there (probably leftovers from Guido van Rossum <guido@python.org> parents: 5871 diff changeset	212 robust test CGI script, usable as main program.
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	213 Writes minimal HTTP headers and formats all information provided to
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	214 the script in HTML form.
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	215 \end{funcdesc}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	216
6153 17a26f986007 Removed some colons that shouldn't be there (probably leftovers from Guido van Rossum <guido@python.org> parents: 5871 diff changeset	217 \begin{funcdesc}{print_environ}{}
17a26f986007 Removed some colons that shouldn't be there (probably leftovers from Guido van Rossum <guido@python.org> parents: 5871 diff changeset	218 format the shell environment in HTML.
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	219 \end{funcdesc}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	220
6153 17a26f986007 Removed some colons that shouldn't be there (probably leftovers from Guido van Rossum <guido@python.org> parents: 5871 diff changeset	221 \begin{funcdesc}{print_form}{form}
17a26f986007 Removed some colons that shouldn't be there (probably leftovers from Guido van Rossum <guido@python.org> parents: 5871 diff changeset	222 format a form in HTML.
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	223 \end{funcdesc}
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	224
6153 17a26f986007 Removed some colons that shouldn't be there (probably leftovers from Guido van Rossum <guido@python.org> parents: 5871 diff changeset	225 \begin{funcdesc}{print_directory}{}
17a26f986007 Removed some colons that shouldn't be there (probably leftovers from Guido van Rossum <guido@python.org> parents: 5871 diff changeset	226 format the current directory in HTML.
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	227 \end{funcdesc}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	228
6153 17a26f986007 Removed some colons that shouldn't be there (probably leftovers from Guido van Rossum <guido@python.org> parents: 5871 diff changeset	229 \begin{funcdesc}{print_environ_usage}{}
17a26f986007 Removed some colons that shouldn't be there (probably leftovers from Guido van Rossum <guido@python.org> parents: 5871 diff changeset	230 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	231 HTML.
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	232 \end{funcdesc}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	233
6153 17a26f986007 Removed some colons that shouldn't be there (probably leftovers from Guido van Rossum <guido@python.org> parents: 5871 diff changeset	234 \begin{funcdesc}{escape}{s\optional{\, quote}}
17a26f986007 Removed some colons that shouldn't be there (probably leftovers from Guido van Rossum <guido@python.org> parents: 5871 diff changeset	235 convert the characters
5871 ed91cb7d3876 Document new 'quote' flag to cgi.escape(). Guido van Rossum <guido@python.org> parents: 5818 diff changeset	236 ``\code{\&}'', ``\code{<}'' and ``\code{>}'' in string \var{s} to HTML-safe
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	237 sequences. Use this if you need to display text that might contain
5871 ed91cb7d3876 Document new 'quote' flag to cgi.escape(). Guido van Rossum <guido@python.org> parents: 5818 diff changeset	238 such characters in HTML. If the optional flag \var{quote} is true,
ed91cb7d3876 Document new 'quote' flag to cgi.escape(). Guido van Rossum <guido@python.org> parents: 5818 diff changeset	239 the double quote character (\code{"}) is also translated; this helps
ed91cb7d3876 Document new 'quote' flag to cgi.escape(). Guido van Rossum <guido@python.org> parents: 5818 diff changeset	240 for inclusion in an HTML attribute value, e.g. in ``\code{<A HREF="...">}''.
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	241 \end{funcdesc}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	242
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	243
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	244 \subsection{Caring about security}
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	245
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	246 There's one important rule: if you invoke an external program (e.g.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	247 via the \code{os.system()} or \code{os.popen()} functions), make very sure you don't
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	248 pass arbitrary strings received from the client to the shell. This is
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	249 a well-known security hole whereby clever hackers anywhere on the web
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	250 can exploit a gullible CGI script to invoke arbitrary shell commands.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	251 Even parts of the URL or field names cannot be trusted, since the
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	252 request doesn't 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	253
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	254 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	255 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	256 alphanumeric characters, dashes, underscores, and periods.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	257
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	258
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	259 \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	260
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	261 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	262 system administrator to find the directory where CGI scripts should be
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	263 installed; usually this is in a directory \code{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	264
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	265 Make sure that your script is readable and executable by ``others''; the
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	266 Unix file mode should be 755 (use \code{chmod 755 filename}). Make sure
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	267 that the first line of the script contains \code{\#!} starting in column 1
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	268 followed by the pathname of the Python interpreter, for instance:
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	269
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	270 \bcode\begin{verbatim}
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	271 #!/usr/local/bin/python
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	272 \end{verbatim}\ecode
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	273 %
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	274 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	275
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	276 Make sure that any files your script needs to read or write are
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	277 readable or writable, respectively, by ``others'' -- their mode should
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	278 be 644 for readable and 666 for writable. This is because, for
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	279 security reasons, the HTTP server executes your script as user
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	280 ``nobody'', without any special privileges. It can only read (write,
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	281 execute) files that everybody can read (write, execute). The current
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	282 directory at execution time is also different (it is usually the
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	283 server's cgi-bin directory) and the set of environment variables is
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	284 also different from what you get at login. in particular, don't count
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	285 on the shell's search path for executables (\code{\$PATH}) or the Python
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	286 module search path (\code{\$PYTHONPATH}) to be set to anything interesting.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	287
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	288 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	289 default module search path, you can change the path in your script,
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	290 before importing other modules, e.g.:
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	291
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	292 \bcode\begin{verbatim}
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	293 import sys
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	294 sys.path.insert(0, "/usr/home/joe/lib/python")
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	295 sys.path.insert(0, "/usr/local/lib/python")
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	296 \end{verbatim}\ecode
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	297 %
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	298 (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	299
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	300 Instructions for non-Unix systems will vary; check your HTTP server's
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	301 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	302
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	303
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	304 \subsection{Testing your CGI script}
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 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	307 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	308 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	309 one reason why you should still test your script from the command
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	310 line: if it contains a syntax error, the python interpreter won't
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	311 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	312 error to the client.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	313
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	314 Assuming your script has no syntax errors, yet it does not work, you
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	315 have no choice but to read the next section:
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	316
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	317
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	318 \subsection{Debugging CGI scripts}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	319
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	320 First of all, check for trivial installation errors -- reading the
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	321 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	322 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	323 installation procedure correctly, try installing a copy of this module
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	324 file (\code{cgi.py}) as a CGI script. When invoked as a script, the file
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	325 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	326 Give it the right mode etc, and send it a request. If it's installed
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	327 in the standard \code{cgi-bin} directory, it should be possible to send it a
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	328 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	329
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	330 \bcode\begin{verbatim}
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	331 http://yourhostname/cgi-bin/cgi.py?name=Joe+Blow&addr=At+Home
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	332 \end{verbatim}\ecode
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	333 %
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	334 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	335 -- perhaps you need to install it in a different directory. If it
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	336 gives another error (e.g. 500), there's an installation problem that
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	337 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	338 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	339 example, the fields should be listed as ``addr'' with value ``At Home''
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	340 and ``name'' with value ``Joe Blow''), the \code{cgi.py} script has been
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	341 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	342 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	343
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	344 The next step could be to call the \code{cgi} module's test() function from
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	345 your script: replace its main code with the single statement
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	346
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	347 \bcode\begin{verbatim}
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	348 cgi.test()
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	349 \end{verbatim}\ecode
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	350 %
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	351 This should produce the same results as those gotten from installing
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	352 the \code{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	353
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	354 When an ordinary Python script raises an unhandled exception
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	355 (e.g. because of a typo in a module name, a file that can't be opened,
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	356 etc.), the Python interpreter prints a nice traceback and exits.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	357 While the Python interpreter will still do this when your CGI script
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	358 raises an exception, most likely the traceback will end up in one of
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	359 the HTTP server's log file, or be discarded altogether.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	360
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	361 Fortunately, once you have managed to get your script to execute
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	362 some code, it is easy to catch exceptions and cause a traceback to
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	363 be printed. The \code{test()} function below in this module is an example.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	364 Here are the rules:
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	365
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	366 \begin{enumerate}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	367 \item Import the traceback module (before entering the
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	368 try-except!)
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	369
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	370 \item Make sure you finish printing the headers and the blank
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	371 line early
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 \item Assign \code{sys.stderr} to \code{sys.stdout}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	374
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	375 \item Wrap all remaining code in a try-except statement
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	376
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	377 \item In the except clause, call \code{traceback.print_exc()}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	378 \end{enumerate}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	379
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	380 For example:
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	381
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	382 \bcode\begin{verbatim}
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	383 import sys
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	384 import traceback
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	385 print "Content-type: text/html"
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	386 print
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	387 sys.stderr = sys.stdout
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	388 try:
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	389 ...your code here...
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	390 except:
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	391 print "\n\n<PRE>"
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	392 traceback.print_exc()
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	393 \end{verbatim}\ecode
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	394 %
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	395 Notes: The assignment to \code{sys.stderr} is needed because the traceback
6645 e8681eda0854 Remove strange use of $math$ mode to produce a backslash. Guido van Rossum <guido@python.org> parents: 6153 diff changeset	396 prints to \code{sys.stderr}.
e8681eda0854 Remove strange use of $math$ mode to produce a backslash. Guido van Rossum <guido@python.org> parents: 6153 diff changeset	397 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	398 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	399
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	400 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	401 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	402 built-in modules):
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	403
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	404 \bcode\begin{verbatim}
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	405 import sys
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	406 sys.stderr = sys.stdout
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	407 print "Content-type: text/plain"
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	408 print
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	409 ...your code here...
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	410 \end{verbatim}\ecode
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5158 diff changeset	411 %
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	412 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	413 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	414 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	415 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	416 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	417 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	418 readable.
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	419
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	420
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	421 \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	422
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	423 \begin{itemize}
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	424 \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	425 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	426 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	427
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	428 \item Check the installation instructions above.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	429
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	430 \item Check the HTTP server's log files. (\code{tail -f logfile} in a separate
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	431 window may be useful!)
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	432
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	433 \item Always check a script for syntax errors first, by doing something
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	434 like \code{python script.py}.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	435
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	436 \item When using any of the debugging techniques, don't forget to add
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	437 \code{import sys} to the top of the script.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	438
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	439 \item When invoking external programs, make sure they can be found.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	440 Usually, this means using absolute path names -- \code{\$PATH} is usually not
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	441 set to a very useful value in a CGI script.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	442
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	443 \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	444 or written by every user on the system.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	445
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	446 \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	447 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	448 \end{itemize}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	449

Mercurial > cpython-lru_cache-weakref

annotate Doc/libcgi.tex @ 6719:faebc1940432 legacy-trunk