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

annotate Doc/libcgi.tex @ 4566:6403c94de50d legacy-trunk

Added safeguard against failure in __del__.

author	Guido van Rossum <guido@python.org>
date	Wed, 27 Nov 1996 19:39:58 +0000
parents	e0c1bd0a74a9
children	b218f294b726

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}}
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	2 \stmodindex{cgi}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	3 \indexii{WWW}{server}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	4 \indexii{CGI}{protocol}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	5 \indexii{HTTP}{protocol}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	6 \indexii{MIME}{headers}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	7 \index{URL}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	8
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	9 \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	10
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	11 Support module for CGI (Common Gateway Interface) scripts.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	12
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	13 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	14 written in Python.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	15
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	16 \subsection{Introduction}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	17 \nodename{Introduction to the CGI module}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	18
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	19 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	20 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	21
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	22 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	23 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	24 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	25 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	26 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	27
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	28 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	29 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	30 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	31 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	32 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	33 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	34 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	35 Netscape 2.0 do).
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	36
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	37 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	38 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	39 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	40 generate a minimal header section looks like this:
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	41
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	42 \begin{verbatim}
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	43 print "Content-type: text/html" # HTML is following
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	44 print # blank line, end of headers
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	45 \end{verbatim}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	46
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	47 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	48 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	49 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	50
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	51 \begin{verbatim}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	52 print "<TITLE>CGI script output</TITLE>"
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	53 print "<H1>This is my first CGI script</H1>"
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	54 print "Hello, world!"
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	55 \end{verbatim}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	56
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	57 (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	58 standard, but any browser will understand it.)
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	59
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	60 \subsection{Using the cgi module}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	61 \nodename{Using the cgi module}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	62
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	63 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	64 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	65 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	66
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	67 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	68 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	69 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	70 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	71 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	72 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	73
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	74 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	75 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	76 \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	77 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	78
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	79 \begin{verbatim}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	80 form = cgi.FieldStorage()
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	81 form_ok = 0
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	82 if form.has_key("name") and form.has_key("addr"):
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	83 if form["name"].value != "" and form["addr"].value != "":
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	84 form_ok = 1
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	85 if not form_ok:
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	86 print "<H1>Error</H1>"
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	87 print "Please fill in the name and addr fields."
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	88 return
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	89 ...further form processing here...
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	90 \end{verbatim}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	91
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	92 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	93 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	94
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	95 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	96 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	97 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	98 (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	99 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	100 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	101 concatenates any number of username fields, separated by commas:
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	102
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	103 \begin{verbatim}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	104 username = form["username"]
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	105 if type(username) is type([]):
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	106 # Multiple username fields specified
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	107 usernames = ""
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	108 for item in username:
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	109 if usernames:
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	110 # Next item -- insert comma
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	111 usernames = usernames + "," + item.value
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	112 else:
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	113 # First item -- don't insert comma
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	114 usernames = item.value
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	115 else:
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	116 # Single username field specified
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	117 usernames = username.value
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	118 \end{verbatim}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	119
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	120 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	121 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	122 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	123 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	124 attribute:
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	125
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	126 \begin{verbatim}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	127 fileitem = form["userfile"]
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	128 if fileitem.file:
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	129 # It's an uploaded file; count lines
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	130 linecount = 0
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	131 while 1:
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	132 line = fileitem.file.readline()
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	133 if not line: break
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	134 linecount = linecount + 1
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	135 \end{verbatim}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	136
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	137 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	138 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	139 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	140 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	141 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	142 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	143 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	144
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	145 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	146 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	147 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	148 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	149
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	150
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	151 \subsection{Old classes}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	152
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	153 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	154 supported for backward compatibility. New applications should use the
e0c1bd0a74a9 Correct truncated paragraph. Guido van Rossum <guido@python.org> parents: 3856 diff changeset	155 FieldStorage class.
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	156
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	157 \code{SvFormContentDict}: single value form content as dictionary; assumes each
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	158 field name occurs in the form only once.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	159
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	160 \code{FormContentDict}: multiple value form content as dictionary (the form
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	161 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	162 fields with the same name.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	163
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	164 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	165 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	166 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	167 version of this module, drop me a note.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	168
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	169
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	170 \subsection{Functions}
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 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	173 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	174 circumstances.
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 \begin{funcdesc}{parse}{fp}: 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	177 \end{funcdesc}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	178
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	179 \begin{funcdesc}{parse_qs}{qs}: parse a query string given as a string argument (data of type
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	180 \code{application/x-www-form-urlencoded}).
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	181 \end{funcdesc}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	182
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	183 \begin{funcdesc}{parse_multipart}{fp\, pdict}: parse input of type \code{multipart/form-data} (for
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	184 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	185 \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	186
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	187 Returns a dictionary just like \code{parse_qs()}: keys are the field names, each
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	188 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	189 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	190 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	191 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	192 header.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	193
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	194 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	195 that.
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	196 \end{funcdesc}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	197
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	198 \begin{funcdesc}{parse_header}{string}: parse a header like \code{Content-type} into a main
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	199 content-type and a dictionary of parameters.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	200 \end{funcdesc}
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 \begin{funcdesc}{test}{}: robust test CGI script, usable as main program.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	203 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	204 the script in HTML form.
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	205 \end{funcdesc}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	206
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	207 \begin{funcdesc}{print_environ}{}: format the shell environment in HTML.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	208 \end{funcdesc}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	209
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	210 \begin{funcdesc}{print_form}{form}: format a form in HTML.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	211 \end{funcdesc}
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	212
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	213 \begin{funcdesc}{print_directory}{}: format the current directory in HTML.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	214 \end{funcdesc}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	215
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	216 \begin{funcdesc}{print_environ_usage}{}: print a list of useful (used by CGI) environment variables in
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	217 HTML.
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	218 \end{funcdesc}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	219
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	220 \begin{funcdesc}{escape}{}: convert the characters ``\code{\&}'', ``\code{<}'' and ``\code{>}'' to HTML-safe
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	221 sequences. Use this if you need to display text that might contain
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	222 such characters in HTML. To translate URLs for inclusion in the HREF
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	223 attribute of an \code{<A>} tag, use \code{urllib.quote()}.
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	224 \end{funcdesc}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	225
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	226
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	227 \subsection{Caring about security}
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	228
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	229 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	230 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	231 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	232 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	233 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	234 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	235 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	236
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	237 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	238 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	239 alphanumeric characters, dashes, underscores, and periods.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	240
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	241
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	242 \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	243
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	244 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	245 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	246 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	247
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	248 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	249 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	250 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	251 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	252
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	253 \begin{verbatim}
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	254 #!/usr/local/bin/python
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	255 \end{verbatim}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	256
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	257 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	258
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	259 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	260 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	261 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	262 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	263 ``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	264 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	265 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	266 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	267 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	268 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	269 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	270
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	271 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	272 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	273 before importing other modules, e.g.:
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	274
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	275 \begin{verbatim}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	276 import sys
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	277 sys.path.insert(0, "/usr/home/joe/lib/python")
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	278 sys.path.insert(0, "/usr/local/lib/python")
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	279 \end{verbatim}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	280
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	281 (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	282
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	283 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	284 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	285
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	286
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	287 \subsection{Testing your CGI script}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	288
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	289 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	290 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	291 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	292 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	293 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	294 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	295 error to the client.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	296
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	297 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	298 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	299
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	300
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	301 \subsection{Debugging 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 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	304 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	305 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	306 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	307 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	308 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	309 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	310 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	311 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	312
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	313 \begin{verbatim}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	314 http://yourhostname/cgi-bin/cgi.py?name=Joe+Blow&addr=At+Home
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	315 \end{verbatim}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	316
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	317 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	318 -- 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	319 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	320 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	321 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	322 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	323 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	324 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	325 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	326
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	327 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	328 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	329
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	330 \begin{verbatim}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	331 cgi.test()
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	332 \end{verbatim}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	333
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	334 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	335 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	336
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	337 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	338 (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	339 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	340 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	341 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	342 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	343
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	344 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	345 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	346 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	347 Here are the rules:
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	348
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	349 \begin{enumerate}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	350 \item Import the traceback module (before entering the
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	351 try-except!)
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 \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	354 line early
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 \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	357
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	358 \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	359
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	360 \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	361 \end{enumerate}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	362
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	363 For example:
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	364
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	365 \begin{verbatim}
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	366 import sys
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	367 import traceback
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	368 print "Content-type: text/html"
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	369 print
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	370 sys.stderr = sys.stdout
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	371 try:
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	372 ...your code here...
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	373 except:
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	374 print "\n\n<PRE>"
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	375 traceback.print_exc()
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	376 \end{verbatim}
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	377
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	378 Notes: The assignment to \code{sys.stderr} is needed because the traceback
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	379 prints to \code{sys.stderr}. The \code{print "$\backslash$n$\backslash$n<PRE>"} statement is necessary to
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	380 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	381
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	382 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	383 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	384 built-in modules):
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	385
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	386 \begin{verbatim}
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	387 import sys
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	388 sys.stderr = sys.stdout
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	389 print "Content-type: text/plain"
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	390 print
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	391 ...your code here...
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	392 \end{verbatim}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	393
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	394 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	395 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	396 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	397 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	398 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	399 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	400 readable.
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	401
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	402
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	403 \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	404
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	405 \begin{itemize}
3856 5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	406 \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	407 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	408 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	409
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	410 \item Check the installation instructions above.
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 \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	413 window may be useful!)
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	414
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	415 \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	416 like \code{python script.py}.
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	417
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	418 \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	419 \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	420
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	421 \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	422 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	423 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	424
5830ede4086c Document the new cgi.py Guido van Rossum <guido@python.org> parents: 2581 diff changeset	425 \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	426 or written by every user on the system.
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 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	429 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	430 \end{itemize}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	431

Mercurial > cpython-lru_cache-weakref

annotate Doc/libcgi.tex @ 4566:6403c94de50d legacy-trunk