annotate Doc/libcgi.tex @ 3216:d00a79ebb027 legacy-trunk

Added missing imgpbm and imgsgi modules
author Jack Jansen <jack.jansen@cwi.nl>
date Thu, 12 Oct 1995 10:23:27 +0000
parents 4d28b655b728
children 5830ede4086c
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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
2449
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
11 This module makes it easy to write Python scripts that run in a WWW
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
12 server using the Common Gateway Interface. It was written by Michael
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
13 McLay and subsequently modified by Steve Majewski and Guido van
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
14 Rossum.
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
15
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
16 When a WWW server finds that a URL contains a reference to a file in a
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
17 particular subdirectory (usually \code{/cgibin}), it runs the file as
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
18 a subprocess. Information about the request such as the full URL, the
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
19 originating host etc., is passed to the subprocess in the shell
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
20 environment; additional input from the client may be read from
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
21 standard input. Standard output from the subprocess is sent back
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
22 across the network to the client as the response from the request.
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
23 The CGI protocol describes what the environment variables passed to
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
24 the subprocess mean and how the output should be formatted. The
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
25 official reference documentation for the CGI protocol can be found on
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
26 the World-Wide Web at
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
27 \code{<URL:http://hoohoo.ncsa.uiuc.edu/cgi/overview.html>}. The
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
28 \code{cgi} module was based on version 1.1 of the protocol and should
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
29 also work with version 1.0.
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
30
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
31 The \code{cgi} module defines several classes that make it easy to
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
32 access the information passed to the subprocess from a Python script;
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
33 in particular, it knows how to parse the input sent by an HTML
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
34 ``form'' using either a POST or a GET request (these are alternatives
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
35 for submitting forms in the HTTP protocol).
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
36
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
37 The formatting of the output is so trivial that no additional support
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
38 is needed. All you need to do is print a minimal set of MIME headers
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
39 describing the output format, followed by a blank line and your actual
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
40 output. E.g. if you want to generate HTML, your script could start as
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
41 follows:
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
42
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
43 \begin{verbatim}
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
44 # Header -- one or more lines:
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
45 print "Content-type: text/html"
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
46 # Blank line separating header from body:
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
47 print
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
48 # Body, in HTML format:
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
49 print "<TITLE>The Amazing SPAM Homepage!</TITLE>"
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
50 # etc...
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
51 \end{verbatim}
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
52
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
53 The server will add some header lines of its own, but it won't touch
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
54 the output following the header.
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
55
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
56 The \code{cgi} module defines the following functions:
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
57
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
58 \begin{funcdesc}{parse}{}
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
59 Read and parse the form submitted to the script and return a
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
60 dictionary containing the form's fields. This should be called at
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
61 most once per script invocation, as it may consume standard input (if
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
62 the form was submitted through a POST request). The keys in the
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
63 resulting dictionary are the field names used in the submission; the
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
64 values are {\em lists} of the field values (since field name may be
2491
fb8e08ec88dd changes (suggested) by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
65 used multiple times in a single form). \samp{\%} escapes in the
fb8e08ec88dd changes (suggested) by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
66 values are translated to their single-character equivalent using
fb8e08ec88dd changes (suggested) by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
67 \code{urllib.unquote()}. As a side effect, this function sets
2449
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
68 \code{environ['QUERY_STRING']} to the raw query string, if it isn't
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
69 already set.
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
70 \end{funcdesc}
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
71
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
72 \begin{funcdesc}{print_environ_usage}{}
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
73 Print a piece of HTML listing the environment variables that may be
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
74 set by the CGI protocol.
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
75 This is mainly useful when learning about writing CGI scripts.
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
76 \end{funcdesc}
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
77
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
78 \begin{funcdesc}{print_environ}{}
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
79 Print a piece of HTML text showing the entire contents of the shell
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
80 environment. This is mainly useful when debugging a CGI script.
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
81 \end{funcdesc}
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
82
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
83 \begin{funcdesc}{print_form}{form}
2491
fb8e08ec88dd changes (suggested) by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
84 Print a piece of HTML text showing the contents of the \var{form} (a
fb8e08ec88dd changes (suggested) by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
85 dictionary, an instance of the \code{FormContentDict} class defined
fb8e08ec88dd changes (suggested) by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
86 below, or a subclass thereof).
2449
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
87 This is mainly useful when debugging a CGI script.
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
88 \end{funcdesc}
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
89
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
90 \begin{funcdesc}{escape}{string}
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
91 Convert special characters in \var{string} to HTML escapes. In
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
92 particular, ``\code{\&}'' is replaced with ``\code{\&amp;}'',
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
93 ``\code{<}'' is replaced with ``\code{\&lt;}'', and ``\code{>}'' is
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
94 replaced with ``\code{\&gt;}''. This is useful when printing (almost)
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
95 arbitrary text in an HTML context. Note that for inclusion in quoted
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
96 tag attributes (e.g. \code{<A HREF="...">}), some additional
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
97 characters would have to be converted --- in particular the string
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
98 quote. There is currently no function that does this.
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
99 \end{funcdesc}
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
100
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
101 The module defines the following classes. Since the base class
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
102 initializes itself by calling \code{parse()}, at most one instance of
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
103 at most one of these classes should be created per script invocation:
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
104
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
105 \begin{funcdesc}{FormContentDict}{}
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
106 This class behaves like a (read-only) dictionary and has the same keys
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
107 and values as the dictionary returned by \code{parse()} (i.e. each
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
108 field name maps to a list of values). Additionally, it initializes
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
109 its data member \code{query_string} to the raw query sent from the
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
110 server.
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
111 \end{funcdesc}
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
112
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
113 \begin{funcdesc}{SvFormContentDict}{}
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
114 This class, derived from \code{FormContentDict}, is a little more
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
115 user-friendly when you are expecting that each field name is only used
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
116 once in the form. When you access for a particular field (using
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
117 \code{form[fieldname]}), it will return the string value of that item
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
118 if it is unique, or raise \code{IndexError} if the field was specified
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
119 more than once in the form. (If the field wasn't specified at all,
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
120 \code{KeyError} is raised.) To access fields that are specified
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
121 multiple times, use \code{form.getlist(fieldname)}. The
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
122 \code{values()} and \code{items()} methods return mixed lists ---
2449
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
123 containing strings for singly-defined fields, and lists of strings for
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
124 multiply-defined fields.
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
125 \end{funcdesc}
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
126
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
127 (It currently defines some more classes, but these are experimental
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
128 and/or obsolescent, and are thus not documented --- see the source for
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
129 more informations.)
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
130
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
131 The module defines the following variable:
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
132
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
133 \begin{datadesc}{environ}
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
134 The shell environment, exactly as received from the http server. See
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
135 the CGI documentation for a description of the various fields.
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
136 \end{datadesc}
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
137
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
138 \subsection{Example}
2581
4d28b655b728 added nodename macro calls for new very long section names
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
139 \nodename{CGI Example}
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
140
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
141 This example assumes that you have a WWW server up and running,
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
142 e.g.\ NCSA's \code{httpd}.
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
143
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
144 Place the following file in a convenient spot in the WWW server's
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
145 directory tree. E.g., if you place it in the subdirectory \file{test}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
146 of the root directory and call it \file{test.html}, its URL will be
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
147 \file{http://\var{yourservername}/test/test.html}.
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
148
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
149 \begin{verbatim}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
150 <TITLE>Test Form Input</TITLE>
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
151 <H1>Test Form Input</H1>
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
152 <FORM METHOD="POST" ACTION="/cgi-bin/test.py">
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
153 <INPUT NAME=Name> (Name)<br>
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
154 <INPUT NAME=Address> (Address)<br>
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
155 <INPUT TYPE=SUBMIT>
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
156 </FORM>
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
157 \end{verbatim}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
158
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
159 Selecting this file's URL from a forms-capable browser such as Mosaic
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
160 or Netscape will bring up a simple form with two text input fields and
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
161 a ``submit'' button.
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
162
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
163 But wait. Before pressing ``submit'', a script that responds to the
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
164 form must also be installed. The test file as shown assumes that the
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
165 script is called \file{test.py} and lives in the server's
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
166 \code{cgi-bin} directory. Here's the test script:
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
167
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
168 \begin{verbatim}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
169 #!/usr/local/bin/python
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
170
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
171 import cgi
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
172
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
173 print "Content-type: text/html"
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
174 print # End of headers!
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
175 print "<TITLE>Test Form Output</TITLE>"
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
176 print "<H1>Test Form Output</H1>"
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
177
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
178 form = cgi.SvFormContentDict() # Load the form
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
179
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
180 name = addr = None # Default: no name and address
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
181
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
182 # Extract name and address from the form, if given
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
183
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
184 if form.has_key('Name'):
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
185 name = form['Name']
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
186 if form.has_key('Address'):
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
187 addr = form['Address']
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
188
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
189 # Print an unnumbered list of the name and address, if present
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
190
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
191 print "<UL>"
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
192 if name is not None:
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
193 print "<LI>Name:", cgi.escape(name)
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
194 if addr is not None:
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
195 print "<LI>Address:", cgi.escape(addr)
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
196 print "</UL>"
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
197 \end{verbatim}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
198
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
199 The script should be made executable (\samp{chmod +x \var{script}}).
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
200 If the Python interpreter is not located at
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
201 \file{/usr/local/bin/python} but somewhere else, the first line of the
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
202 script should be modified accordingly.
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
203
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
204 Now that everything is installed correctly, we can try out the form.
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
205 Bring up the test form in your WWW browser, fill in a name and address
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
206 in the form, and press the ``submit'' button. The script should now
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
207 run and its output is sent back to your browser. This should roughly
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
208 look as follows:
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
209
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
210 \strong{Test Form Output}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
211
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
212 \begin{itemize}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
213 \item Name: \var{the name you entered}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
214 \item Address: \var{the address you entered}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
215 \end{itemize}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
216
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
217 If you didn't enter a name or address, the corresponding line will be
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
218 missing (since the browser doesn't send empty form fields to the
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
219 server).