< BACKMake Note | BookmarkCONTINUE >
152015024128143245168232148039199167010047123209178152124239215162148040135189253149095235

The cgi Module

The cgi module accepts sys.stdin and environment variables set by the server as input sources. The output is sent directly to sys.stdout, carrying an HTTP header and the data itself.

A very simple header example would be

					
print "Content-type: text/html"
print

				

Note that it is necessary to have a new line at the end of the header information. In most cases, the previous line is all you will use in your scripts.

The FieldStorage class, which is implemented by this module, is able to read both the standard input (for POST calls) and the query string (for GET calls). In order to parse the contents of an HTML Form, you need to create an instance of this class.

This instance carries the following attributes:

  • fs.name— This is the field's name.

  • fs.value—This is the field's value.

  • fs.filename—This client-side filename is used in uploads.

  • fs.file—This is a file-like object from which data can be read.

  • fs.type—This is the content type.

  • fs.type_options—This dictionary of options is specified on the content-type line of the HTTP request.

  • fs.disposition—This is the "content-disposition" field, None if not specified.

  • fs.disposition_option—This is the dictionary of disposition options.

  • fs.headers—This is a dictionary-like object containing all HTTP headers contents.

Each individual form field is defined as an instance of the MiniFieldStorage class, whereas on the contrary, multipart data (such as uploaded files) is defined as an instance of the FieldStorage class itself. Each instance is accessed as a dictionary whose keys are the Form's field names, and the values are their contents. These dictionaries also implement methods such as .keys() and .has_key(). If a specific form field has multiple values (for example, a selection list), a list of multiple MiniFieldStorage instances is generated and assigned to the appropriate key value in the dictionary. The use of MiniFieldStorage is pretty much transparent when using CGI, thus, you don't have to worry about these implementation details.

Note that uploaded files are read directly to the memory by accessing the value attribute of the class instance.

Also note that Python 2.0 provides a new method called getvalue() to the objects of the FieldStorage class, that implements the same functionality of a dictionary's get() method by returning the value attribute of the given object.

Functions

The following list shows some general functions exposed by the cgi module.

cgi.escape(string [,quote])— Translates "<", "&", ">" to "&lt;", "&amp;", "&gt;". If you want to convert the double-quote character, you must set the quote flag to true.

cgi.parse_qs(string, keep_blank_values=0)—Parses a query string such as "country=USA&state=PA" to a dictionary-like format, for example, {"country": ["USA"], "state": ["PA"],…}

cgi.parse([file], …)—Parses query strings from default file locations (such as, multiple file objects) from which data can be read, and generates a dictionary. The default behavior is to map the input to stdin.

For CGI debugging, the following functions are available:

cgi.print_environ()—Formats the shell environment in HTML.

cgi.print_environ_usage()—Prints a list of environment variables, used by CGI, in HTML.

cgi.print_form(form)—Formats a form in HTML.

cgi.print_directory()— Formats the current directory in HTML.

cgi.test()— Tests CGI script. It writes minimal HTTP headers and formats all information provided to the script in HTML form.

The following functions are not part of the CGI module, but they are very useful for CGI processing too.

urllib.quote(string), urllib.unquote(string)—These functions do and undo convertions between literals (that are used in CGI applications) and their special translation codes, which are required when transporting the literals to URL format (for example, becomes " %20 ").

urllib.urlencode(dictionary)—Converts a dictionary { "country":"USA", "state":"PA",…} to query string format (for example, "country=USA&state=PA"). Note that this function has the opposite functionality of the cgi.parse_qs() function.


Last updated on 1/30/2002
Python Developer's Handbook, © 2002 Sams Publishing

< BACKMake Note | BookmarkCONTINUE >

Index terms contained in this section

attributes
      fs.disposition
      fs.disposition_option
      fs.file
      fs.filename
      fs.headers
      fs.name
      fs.type
      fs.type_options
      fs.value
      value
CGI (Common Gateway Interface) scripts
      cgi module 2nd 3rd
cgi module 2nd 3rd
cgi.escape(string [,quote]) method
cgi.parse([file], …) method
cgi.parse_qs(string, keep blank values=0) method
cgi.print_directory() method
cgi.print_environ() method
cgi.print_environ_usage() method
cgi.print_form(form) method
cgi.test() method
classes
      FieldStorage
      MiniFieldStorage
classs
      FieldStorage
Common Gateway Interface (CGI) scripts
      cgi module 2nd 3rd
debugging
      CGI scripts, functions
FieldStorage class 2nd
fs.disposition attribute
fs.disposition_option attribute
fs.file attribute
fs.filename attribute
fs.headers attribute
fs.name attribute
fs.type attribute
fs.type_options attribute
fs.value attribute
get() method
getvalue() method
headers
      HTTP
HTTP headers
methods
      cgi.escape(string [,quote])
      cgi.parse([file], …)
      cgi.parse_qs(string, keep blank values=0)
      cgi.print_directory()
      cgi.print_environ()
      cgi.print_environ_usage()
      cgi.print_form(form)
      cgi.test()
      get()
      getvalue()
      urllib.quote(string)
      urllib.unquote(string)
      urllib.urlencode(dictionary)
MiniFieldStorage class
modules
      cgi 2nd 3rd
scripts
     Common Gateway Interface (CGI)
            cgi module 2nd 3rd
urllib.quote(string) method
urllib.unquote(string) method
urllib.urlencode(dictionary) method
value attribute

© 2002, O'Reilly & Associates, Inc.