|
| 1 | +\section{Built-in module \sectcode{cgi}} |
| 2 | +\stmodindex{cgi} |
| 3 | +\indexii{WWW}{server} |
| 4 | +\indexii{CGI}{protocol} |
| 5 | +\indexii{HTTP}{protocol} |
| 6 | +\indexii{MIME}{headers} |
| 7 | +\index{URL} |
| 8 | + |
| 9 | +This module makes it easy to write Python scripts that run in a WWW |
| 10 | +server using the Common Gateway Interface. It was written by Michael |
| 11 | +McLay and subsequently modified by Steve Majewski and Guido van |
| 12 | +Rossum. |
| 13 | + |
| 14 | +When a WWW server finds that a URL contains a reference to a file in a |
| 15 | +particular subdirectory (usually \code{/cgibin}), it runs the file as |
| 16 | +a subprocess. Information about the request such as the full URL, the |
| 17 | +originating host etc., is passed to the subprocess in the shell |
| 18 | +environment; additional input from the client may be read from |
| 19 | +standard input. Standard output from the subprocess is sent back |
| 20 | +across the network to the client as the response from the request. |
| 21 | +The CGI protocol describes what the environment variables passed to |
| 22 | +the subprocess mean and how the output should be formatted. The |
| 23 | +official reference documentation for the CGI protocol can be found on |
| 24 | +the World-Wide Web at |
| 25 | +\code{<URL:http://hoohoo.ncsa.uiuc.edu/cgi/overview.html>}. The |
| 26 | +\code{cgi} module was based on version 1.1 of the protocol and should |
| 27 | +also work with version 1.0. |
| 28 | + |
| 29 | +The \code{cgi} module defines several classes that make it easy to |
| 30 | +access the information passed to the subprocess from a Python script; |
| 31 | +in particular, it knows how to parse the input sent by an HTML |
| 32 | +``form'' using either a POST or a GET request (these are alternatives |
| 33 | +for submitting forms in the HTTP protocol). |
| 34 | + |
| 35 | +The formatting of the output is so trivial that no additional support |
| 36 | +is needed. All you need to do is print a minimal set of MIME headers |
| 37 | +describing the output format, followed by a blank line and your actual |
| 38 | +output. E.g. if you want to generate HTML, your script could start as |
| 39 | +follows: |
| 40 | + |
| 41 | +\begin{verbatim} |
| 42 | +# Header -- one or more lines: |
| 43 | +print "Content-type: text/html" |
| 44 | +# Blank line separating header from body: |
| 45 | +print |
| 46 | +# Body, in HTML format: |
| 47 | +print "<TITLE>The Amazing SPAM Homepage!</TITLE>" |
| 48 | +# etc... |
| 49 | +\end{verbatim} |
| 50 | + |
| 51 | +The server will add some header lines of its own, but it won't touch |
| 52 | +the output following the header. |
| 53 | + |
| 54 | +The \code{cgi} module defines the following functions: |
| 55 | + |
| 56 | +\begin{funcdesc}{parse}{} |
| 57 | +Read and parse the form submitted to the script and return a |
| 58 | +dictionary containing the form's fields. This should be called at |
| 59 | +most once per script invocation, as it may consume standard input (if |
| 60 | +the form was submitted through a POST request). The keys in the |
| 61 | +resulting dictionary are the field names used in the submission; the |
| 62 | +values are {\em lists} of the field values (since field name may be |
| 63 | +used multiple times in a single form). As a side effect, it sets |
| 64 | +\code{environ['QUERY_STRING']} to the raw query string, if it isn't |
| 65 | +already set. |
| 66 | +\end{funcdesc} |
| 67 | + |
| 68 | +\begin{funcdesc}{print_environ_usage}{} |
| 69 | +Print a piece of HTML listing the environment variables that may be |
| 70 | +set by the CGI protocol. |
| 71 | +This is mainly useful when learning about writing CGI scripts. |
| 72 | +\end{funcdesc} |
| 73 | + |
| 74 | +\begin{funcdesc}{print_environ}{} |
| 75 | +Print a piece of HTML text showing the entire contents of the shell |
| 76 | +environment. This is mainly useful when debugging a CGI script. |
| 77 | +\end{funcdesc} |
| 78 | + |
| 79 | +\begin{funcdesc}{print_form}{form} |
| 80 | +Print a piece of HTML text showing the contents of the \var{form}. |
| 81 | +This is mainly useful when debugging a CGI script. |
| 82 | +\end{funcdesc} |
| 83 | + |
| 84 | +\begin{funcdesc}{escape}{string} |
| 85 | +Convert special characters in \var{string} to HTML escapes. In |
| 86 | +particular, ``\code{\&}'' is replaced with ``\code{\&}'', |
| 87 | +``\code{<}'' is replaced with ``\code{\<}'', and ``\code{>}'' is |
| 88 | +replaced with ``\code{\>}''. This is useful when printing (almost) |
| 89 | +arbitrary text in an HTML context. Note that for inclusion in quoted |
| 90 | +tag attributes (e.g. \code{<A HREF="... ">}), some additional |
| 91 | +characters would have to be converted --- in particular the string |
| 92 | +quote. There is currently no function that does this. |
| 93 | +\end{funcdesc} |
| 94 | +
|
| 95 | +The module defines the following classes. Since the base class |
| 96 | +initializes itself by calling \code{parse()}, at most one instance of |
| 97 | +at most one of these classes should be created per script invocation: |
| 98 | +
|
| 99 | +\begin{funcdesc}{FormContentDict}{} |
| 100 | +This class behaves like a (read-only) dictionary and has the same keys |
| 101 | +and values as the dictionary returned by \code{parse()} (i.e. each |
| 102 | +field name maps to a list of values). Additionally, it initializes |
| 103 | +its data member \code{query_string} to the raw query sent from the |
| 104 | +server. |
| 105 | +\end{funcdesc} |
| 106 | +
|
| 107 | +\begin{funcdesc}{SvFormContentDict}{} |
| 108 | +This class, derived from \code{FormContentDict}, is a little more |
| 109 | +user-friendly when you are expecting that each field name is only used |
| 110 | +once in the form. When you access for a particular field (using |
| 111 | +\code{form[fieldname]}), it will return the string value of that item |
| 112 | +if it is unique, or raise \code{IndexError} if the field was specified |
| 113 | +more than once in the form. (If the field wasn't specified at all, |
| 114 | +\code{KeyError} is raised.) To access fields that are specified |
| 115 | +multiple times, use \code{form.getlist(fieldname)}. The |
| 116 | +\code{values()} and \code{items()} methods return mixed lists -- |
| 117 | +containing strings for singly-defined fields, and lists of strings for |
| 118 | +multiply-defined fields. |
| 119 | +\end{funcdesc} |
| 120 | +
|
| 121 | +(It currently defines some more classes, but these are experimental |
| 122 | +and/or obsolescent, and are thus not documented --- see the source for |
| 123 | +more informations.) |
| 124 | +
|
| 125 | +The module defines the following variable: |
| 126 | +
|
| 127 | +\begin{datadesc}{environ} |
| 128 | +The shell environment, exactly as received from the http server. See |
| 129 | +the CGI documentation for a description of the various fields. |
| 130 | +\end{datadesc} |
0 commit comments