Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame^] | 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} |