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