cgi module

Synopsis

The cgi module provides an object-oriented interface for
writing CGI and CGI-style programs. It provides an abstraction layer so that
the same code can be used with either standard CGI or replacement technologies
such as FastCGI.

Usage

Code to handle a request must subclass the abstract class
cgi.Handler. This class uses a single
method process which receives a
single parameter of type cgi.Request, which
is used to retrieve information about the request and to send the response.
Instances of this subclass will be created to handle requests.

When the standard CGI protocol is used, a new process is created to handle
each request, but with more complicated protocols such as
FastCGI, a process may handle more than one request
simultaneously in multiple threads. However, even in this situation, each
instance of the cgi.Handler subclass will
only be used to process one request at once. This means that the instance can
use self to store per-request data.

A subclass of cgi.Request is used to
to call the handler. Which subclass is used depends on the protocol used to
communicate with the web server. This module provides
cgi.CGIRequest which implements the
standard CGI protocol, and also
cgi.GZipCGIRequest which is the
same but uses zlib to compress
the response when the user's browser indicates it can do this.

Note: by default, output from the handler is buffered. If the output from
the script is going to be large (for example, if the output is not an HTML
file), then buffering should be disabled using
set_buffering.

Request objects provide information about a CGI request, as
well as methods to return a response. This class is not used directly, but
is subclassed depending on what protocol is being used to talk to the web
server.

Public Instance Variables

The params map contains the CGI form variables recovered
from the QUERY_STRING, and in the case of POST
requests, stdin. In the case of each
key, the name is a string and the type of the value depends on whether or not
the name has one of a number of special suffixes.

If the key has no special suffix, then the value is a string, or
None. (None occurs when a URL-encoded string contains
a name without a corresponding equals sign and value. If the string contains
a name and an equals sign but no value then this is represented as an empty
string.) If the key ends with the string "*" then the value is a
sequence containing one or more values, each of which is either a string or
None (to support multiple values with the same name, e.g. HTML
<select> input fields). If the key ends with the string
"!" then the value is a
mime.Entity
object (to support file uploads). If the key ends with the string
"!*" then the value is a sequence of one or more
mime.Entity objects.

If a form variable is found with a name ending in "!" or
"!*" but it did not arrive in the form of a MIME section then it
is ignored and is not placed into the map. If more than one value with the same
name is found and the name does not end in "*" or "!*"
then only one of the values will be entered into the map, and the others will
be discarded. This means that, even in the face of malicious input, the types
of the values are guaranteed to match that indicated by their key's suffix.

Note that the suffixes must be present in the CGI variables themselves. The
programmer does not indicate to the cgi module what CGI variables
he is expecting. Example:

If the aborted variable references a true value then the
request has been aborted (usually because the client has gone away). If the
request is aborted then all further output using the
write method will be discarded.
The programmer may inspect the aborted variable occasionally and
exit if the request has been aborted, but it is not necessary to do so.

Public Methods

Create new Request instance. Instances of
handler_type will be created to handle requests.

The array of HTTP headers will be initialised to contain a
Content-Type header with the value text/html;
charset=iso-8859-1. If this is not appropriate then the content type
should be overridden by specifying a new one with the
set_header method.

Retrieves a header from the array of HTTP headers (this is the array
of output headers the handler will be returning to the user agent,
not the input headers from the user agent). If there is more than
one header with the same name, the index parameter is used to
specify which one is required. If the named header was not found, or there
were not enough occurrences of it to satisfy the index requirement,
None is returned. Header names are matched case-insensitively.

Add a header to the array of HTTP headers. If a header or headers of the
same name already exist in the array, then they are deleted before the new
header is added. If the headers have already been output then a
cgi.SequencingError exception is
raised. Header names are matched case-insensitively.

Remove all headers with the name hdr from the array of HTTP
headers. If the headers have already been output then a
cgi.SequencingError exception is
raised. Header names are matched case-insensitively.

Specify whether or not client output sent using
write will be buffered. If buffering
is disabled when output has already been buffered then the existing buffer
will be flushed immediately. At the start of a new request, buffering defaults
to 'on'.

Flushes any buffered output to the client. If the HTTP headers array has not
already been sent then it will be sent before any other output. Generally
speaking, you do not need to call flush, even if buffering is
enabled, because it is automatically called when the
Handler.process method exits.

Calls flush and then closes the
output stream. It is essential that this method is called when the request is
complete, however in general you do not need to call it manually because it is
automatically called when the
Handler.process method exits.

This is a placeholder method that must be over-ridden by a subclass of the
Request class. It should log the string
parameter s somewhere on the server (e.g. in the
error_log). The string must not be output to
the client.

Sets the character encoding used for the response. The default encoding
is None, which means that no encoding is performed (in which case
you cannot send unicode objects to
write and normal strings are output
unchanged). If you specify an encoding other than None then you
can send unicode objects to
write and they will be encoded
correctly. Remember in this case you will probably want to call
set_header to update the
Content-Type header to indicate the character encoding you are
using.

inputencoding is only used if encoding is not
None. Normally if you pass a non-unicode object to
write then it will be assumed to
be in Python's default character encoding. If you specify a
non-Noneinputencoding then it will be assumed to
be in that character encoding instead.

Sends the string parameter s to the client. If buffering has
been enabled using
set_buffering then the string
will not be sent to the client immediately but will be buffered in memory.
If buffering has not been enabled and the HTTP headers array has not already
been sent then it will be sent before any other output.

If you wish to be able to output unicode objects using this function, then
you should first call
set_encoding to specify the
output character encoding.

This is a placeholder method that may be over-ridden by a subclass of the
Request class. If whatever mechanism the
subclass's implementation of _write
uses can result in data being buffered then this method should ensure that the
data is flushed to the client.

This is a utility method for the use of subclasses of the
Request class. The parameter
encoded must provide a file-like read
method which is then used to parse a MIME-encoded input stream.
contenttype should contain the value of the
Content-Type header for the stream (which should presumably
always indicate the multipart/form-data type). MIME sections
found with Content-Disposition: form-data are merged into the
self.params mapping.

This is a utility method for the use of subclasses of the
Request class. Examines the environment
strings contained in the map parameter environ as per the
standard CGI protocol. If the environ variable
QUERY_STRING is available then it is parsed using the
mergevars method. If the
environ variable REQUEST_METHOD is
POST then the inf parameter (which must provide a
file-like read method) is used to read an input
stream which is passed to either the
mergevars method or the
mergemime method depending
on the environ variable CONTENT_TYPE. Finally,
if the environ variable HTTP_COOKIE is available
then it is parsed into the
self.cookies instance variable.

GZipMixIn is a class that can be mixed-in to a sub-class of the
Request class to enable gzip compression
of responses to user agents that indicate they can accept it. Make sure you
specify the GZipMixIn class before the transport class
on the class line.

Example:

class GZipCGIRequest(cgi.GZipMixIn, cgi.CGIRequest):
pass

Public Methods

Specifies the compression level used by gzip for this request. The default
level if you do not call this method is 6. This method can also
be used to disable compression for a particular request by setting
level to 0 - for example if the
handler is returning an image file to the user then compression should be
disabled as images are already compressed. If the headers have already been
output then a cgi.SequencingError
exception is raised.

CGIRequest subclasses the
Request class to implement the standard
CGI protocol. Environment variables are read from os.environ,
input is read from sys.stdin, output goes to
sys.stdout and errors go to sys.stderr.

Public Methods

Initialises the instance ready for a new request by calling the
_init method, then reads the CGI
input and sets up the various instance variables. A
Handler object of the type passed to the
CGIRequest.__init__ method is
then instantiated and its process
method is called. If an exception is thrown by this method then the
traceback method is called to
display it.

Public Methods

This method must be overridden by subclasses. It is called to process a
request. The req parameter references the
Request object (actually, an instance of a
subclass of Request) which should be used
to inspect the request and to send the response.

Note that even in multithreaded situations such as
FastCGI, any individual instance of a
Handler subclass will only have one process method
executing at once.

This method may be overridden by subclasses. It is called to handle an
exception thrown by the process
method. The default implementation calls
Request.traceback to send a
traceback to the error log and output a generic error page to the browser.

class: DebugHandlerMixIn

This mix-in class provides a
traceback method that outputs
debug information to the browser as well as to the error log. This class may be
used during development to aid debugging but should never be used in a
production environment since it will leak private information to the
browser.

Example:

class Handler(cgi.DebugHandlerMixIn, wt.Handler):
pass

Public Methods

This method may be overridden by subclasses. It is called to handle an
exception thrown by the process
method. The default implementation calls
traceback to send a traceback to both the
error log and the browser.

Globals

Functions

HTML-encodes (using entities) characters that are special in HTML -
specifically at least all of &<>" and ' are
guaranteed to be encoded. raw is passed to str,
so almost any type can be passed in to this parameter.

URL-encodes (using %-escapes) characters that are special in URLs.
Characters that are special in HTML are guaranteed to be escaped, so the output
of this function is safe to embed directly in HTML without the need for a
further call to html_encode.
raw is passed to str(), so almost any type can be
passed in to this parameter.

This function should only be called while an exception is being handled
(i.e. in an except section). It emits a detailed traceback about
the exception to the server's error log. If html references a
true value then the traceback is also sent as HTML to the browser. If
html is false then the browser output is not altered in any way,
so it is up to the caller to arrange for suitable output to be sent.