4. Writing your CGI script

Python's standard modules take care of a lot of the detail work associated with writing a CGI script. You don't have to worry about whether the script was launched from a form element or from a non-form link, or whether the form used method='GET' or method='POST'; the modules will handle all that for you.

All CGI scripts must write these three items to its standard output stream (sys.stdout) in sequence:

One or more header lines that tell the Web server what you want to do.
A blank line that tells the Web server you are done writing header lines.
The Web page you want to display, encoded as HTML.

There are a number of different headers, but typically you will write a Content-type header with this format, to tell the Web server you are going to send it a Web page:

Content-type: text/html

Be sure to remember to write a blank line after the header.

4.1. The `cgi` module

Python's standard cgi module has a number of useful features. You'll want to import it like this:

import cgi

Here are some of the features of this module that you'll probably find useful.

cgi.escape(s)

Given a string s, this function returns a string with the three special characters “<”, “>”, and “&” replaced by their escape sequences “<”, “>”, and “&”, respectively. Here's an interactive example:

>>> import cgi
>>> cgi.escape ( 'abc < def & ghi >' )
'abc &lt; def &amp; ghi &gt;'
>>>

cgi.FieldStorage()

This constructor returns a FieldStorage instance that contains all the name-value pairs provided as input to your script.

The constructor finds these inputs regardless of whether the sending page used method='GET' or method='POST', and regardless of whether the input came from a form or via the techniques described in Section 3.2, “Direct CGI links without use of a form”.

Suppose f is a FieldStorage instance. Here are the operations you can perform on it:

f.getvalue(cName, default=None)

If f has one value for control name cName, this method returns that value as a string. If there are multiple values, the method returns them as a list of strings.

If f has no values for control name cName, it returns the default value.

f.getfirst(cName, default=None)

If f has any values for control name cName, it returns the first value as a string, otherwise it returns default.

f.getlist(cName)

Returns a list of the values for control name cName. This list may be empty or contain one or more values as strings.

f.keys()

Returns a list of the control names that have values in f.

f.has_key(cName)

Returns True if f has any values for control name cName; otherwise returns False.

f[cName]

If f has one name-value pair for control name cName, this method returns an instance that represents that name-value pair:

If your form uses method='post' and enctype='multipart/form-data', this method will return an instance of class FieldStorage. For more information on retrieving uploaded files from “input type='file'” controls, see Section 4.1.1, “Special considerations for uploading files”.
Otherwise, the method will return an instance of class MiniFieldStorage. The actual control value will reside in the .value attribute of that instance.

If f has multiple values for control name cName, the method will return a list of MiniFieldStorage instances, each containing one control value in its .value attribute.

If f has no value for control cName, this method will raise a KeyError exception.

4.1.1. Special considerations for uploading files

If you want your form to allow the user to upload a file, include an “input type='file'” control with method='post' and enctype='multipart/form-data'.

Suppose your file control's name is 'file-con'. This code would set fileItem to a FieldStorage instance containing information about the file to be uploaded:

    form = cgi.FieldStorage()
    fileItem = form['file-con']

After this operation, fileItem.filename will contain the name of the uploaded file as a string. There are two ways to retrieve the contents of the file:

If the file is not too large, simply use fileItem.value, or form.getvalue('file-con'), either of which will return the file's entire contents as a single string.
You may instead simply read the file's contents from attribute fileItem.file, which is a readable Python file instance.

Dynamic Web content and forms processing in Python