| \section{Built-in module \sectcode{cgi}} |
| \stmodindex{cgi} |
| \indexii{WWW}{server} |
| \indexii{CGI}{protocol} |
| \indexii{HTTP}{protocol} |
| \indexii{MIME}{headers} |
| \index{URL} |
| |
| \renewcommand{\indexsubitem}{(in module cgi)} |
| |
| This module makes it easy to write Python scripts that run in a WWW |
| server using the Common Gateway Interface. It was written by Michael |
| McLay and subsequently modified by Steve Majewski and Guido van |
| Rossum. |
| |
| When a WWW server finds that a URL contains a reference to a file in a |
| particular subdirectory (usually \code{/cgibin}), it runs the file as |
| a subprocess. Information about the request such as the full URL, the |
| originating host etc., is passed to the subprocess in the shell |
| environment; additional input from the client may be read from |
| standard input. Standard output from the subprocess is sent back |
| across the network to the client as the response from the request. |
| The CGI protocol describes what the environment variables passed to |
| the subprocess mean and how the output should be formatted. The |
| official reference documentation for the CGI protocol can be found on |
| the World-Wide Web at |
| \code{<URL:http://hoohoo.ncsa.uiuc.edu/cgi/overview.html>}. The |
| \code{cgi} module was based on version 1.1 of the protocol and should |
| also work with version 1.0. |
| |
| The \code{cgi} module defines several classes that make it easy to |
| access the information passed to the subprocess from a Python script; |
| in particular, it knows how to parse the input sent by an HTML |
| ``form'' using either a POST or a GET request (these are alternatives |
| for submitting forms in the HTTP protocol). |
| |
| The formatting of the output is so trivial that no additional support |
| is needed. All you need to do is print a minimal set of MIME headers |
| describing the output format, followed by a blank line and your actual |
| output. E.g. if you want to generate HTML, your script could start as |
| follows: |
| |
| \begin{verbatim} |
| # Header -- one or more lines: |
| print "Content-type: text/html" |
| # Blank line separating header from body: |
| print |
| # Body, in HTML format: |
| print "<TITLE>The Amazing SPAM Homepage!</TITLE>" |
| # etc... |
| \end{verbatim} |
| |
| The server will add some header lines of its own, but it won't touch |
| the output following the header. |
| |
| The \code{cgi} module defines the following functions: |
| |
| \begin{funcdesc}{parse}{} |
| Read and parse the form submitted to the script and return a |
| dictionary containing the form's fields. This should be called at |
| most once per script invocation, as it may consume standard input (if |
| the form was submitted through a POST request). The keys in the |
| resulting dictionary are the field names used in the submission; the |
| values are {\em lists} of the field values (since field name may be |
| used multiple times in a single form). \samp{\%} escapes in the |
| values are translated to their single-character equivalent using |
| \code{urllib.unquote()}. As a side effect, this function sets |
| \code{environ['QUERY_STRING']} to the raw query string, if it isn't |
| already set. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{print_environ_usage}{} |
| Print a piece of HTML listing the environment variables that may be |
| set by the CGI protocol. |
| This is mainly useful when learning about writing CGI scripts. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{print_environ}{} |
| Print a piece of HTML text showing the entire contents of the shell |
| environment. This is mainly useful when debugging a CGI script. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{print_form}{form} |
| Print a piece of HTML text showing the contents of the \var{form} (a |
| dictionary, an instance of the \code{FormContentDict} class defined |
| below, or a subclass thereof). |
| This is mainly useful when debugging a CGI script. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{escape}{string} |
| Convert special characters in \var{string} to HTML escapes. In |
| particular, ``\code{\&}'' is replaced with ``\code{\&}'', |
| ``\code{<}'' is replaced with ``\code{\<}'', and ``\code{>}'' is |
| replaced with ``\code{\>}''. This is useful when printing (almost) |
| arbitrary text in an HTML context. Note that for inclusion in quoted |
| tag attributes (e.g. \code{<A HREF="...">}), some additional |
| characters would have to be converted --- in particular the string |
| quote. There is currently no function that does this. |
| \end{funcdesc} |
| |
| The module defines the following classes. Since the base class |
| initializes itself by calling \code{parse()}, at most one instance of |
| at most one of these classes should be created per script invocation: |
| |
| \begin{funcdesc}{FormContentDict}{} |
| This class behaves like a (read-only) dictionary and has the same keys |
| and values as the dictionary returned by \code{parse()} (i.e. each |
| field name maps to a list of values). Additionally, it initializes |
| its data member \code{query_string} to the raw query sent from the |
| server. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{SvFormContentDict}{} |
| This class, derived from \code{FormContentDict}, is a little more |
| user-friendly when you are expecting that each field name is only used |
| once in the form. When you access for a particular field (using |
| \code{form[fieldname]}), it will return the string value of that item |
| if it is unique, or raise \code{IndexError} if the field was specified |
| more than once in the form. (If the field wasn't specified at all, |
| \code{KeyError} is raised.) To access fields that are specified |
| multiple times, use \code{form.getlist(fieldname)}. The |
| \code{values()} and \code{items()} methods return mixed lists --- |
| containing strings for singly-defined fields, and lists of strings for |
| multiply-defined fields. |
| \end{funcdesc} |
| |
| (It currently defines some more classes, but these are experimental |
| and/or obsolescent, and are thus not documented --- see the source for |
| more informations.) |
| |
| The module defines the following variable: |
| |
| \begin{datadesc}{environ} |
| The shell environment, exactly as received from the http server. See |
| the CGI documentation for a description of the various fields. |
| \end{datadesc} |