11.1. Standard Module cgi

When a WWW server finds that a URL contains a reference to a file in a particular subdirectory (usually /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 <URL:http://hoohoo.ncsa.uiuc.edu/cgi/overview.html>. The cgi module was based on version 1.1 of the protocol and should also work with version 1.0.

The 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:

# 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...

The cgi module defines the following functions:

parse () -- function of module cgi

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 lists of the field values (since field name may be used multiple times in a single form). `%' escapes in the values are translated to their single-character equivalent using urllib.unquote(). As a side effect, this function sets environ['QUERY_STRING'] to the raw query string, if it isn't already set.

print_environ_usage () -- function of module cgi

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.

print_environ () -- function of module cgi

Print a piece of HTML text showing the entire contents of the shell environment. This is mainly useful when debugging a CGI script.

print_form (form) -- function of module cgi

Print a piece of HTML text showing the contents of the form (a dictionary, an instance of the FormContentDict class defined below, or a subclass thereof). This is mainly useful when debugging a CGI script.

escape (string) -- function of module cgi

Convert special characters in string to HTML escapes. In particular, ``&'' is replaced with ``&'', ``<'' is replaced with ``<'', and ``>'' is replaced with ``>''. This is useful when printing (almost) arbitrary text in an HTML context. Note that for inclusion in quoted tag attributes (e.g. <A HREF="...">), some additional characters would have to be converted --- in particular the string quote. There is currently no function that does this.

FormContentDict () -- function of module cgi

This class behaves like a (read-only) dictionary and has the same keys and values as the dictionary returned by parse() (i.e. each field name maps to a list of values). Additionally, it initializes its data member query_string to the raw query sent from the server.

SvFormContentDict () -- function of module cgi

This class, derived from 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 form[fieldname]), it will return the string value of that item if it is unique, or raise IndexError if the field was specified more than once in the form. (If the field wasn't specified at all, KeyError is raised.) To access fields that are specified multiple times, use form.getlist(fieldname). The values() and items() methods return mixed lists --- containing strings for singly-defined fields, and lists of strings for multiply-defined fields.

The module defines the following variable:

environ -- data of module cgi

The shell environment, exactly as received from the http server. See the CGI documentation for a description of the various fields.

Menu

CGI Example