Doc/library/cgihttpserver.rst

   1
   2 :mod:`CGIHTTPServer` --- CGI-capable HTTP request handler
   3 =========================================================
   4
   5 .. module:: CGIHTTPServer
   6    :synopsis: This module provides a request handler for HTTP servers which can run CGI
   7               scripts.
   8 .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
   9
  10
  11 The :mod:`CGIHTTPServer` module defines a request-handler class, interface
  12 compatible with :class:`BaseHTTPServer.BaseHTTPRequestHandler` and inherits
  13 behavior from :class:`SimpleHTTPServer.SimpleHTTPRequestHandler` but can also
  14 run CGI scripts.
  15
  16 .. note::
  17
  18    This module can run CGI scripts on Unix and Windows systems; on Mac OS it will
  19    only be able to run Python scripts within the same process as itself.
  20
  21 .. note::
  22
  23    CGI scripts run by the :class:`CGIHTTPRequestHandler` class cannot execute
  24    redirects (HTTP code 302), because code 200 (script output follows) is sent
  25    prior to execution of the CGI script.  This pre-empts the status code.
  26
  27 The :mod:`CGIHTTPServer` module defines the following class:
  28
  29
  30 .. class:: CGIHTTPRequestHandler(request, client_address, server)
  31
  32    This class is used to serve either files or output of CGI scripts from  the
  33    current directory and below. Note that mapping HTTP hierarchic structure to
  34    local directory structure is exactly as in
  35    :class:`SimpleHTTPServer.SimpleHTTPRequestHandler`.
  36
  37    The class will however, run the CGI script, instead of serving it as a file, if
  38    it guesses it to be a CGI script. Only directory-based CGI are used --- the
  39    other common server configuration is to treat special extensions as denoting CGI
  40    scripts.
  41
  42    The :func:`do_GET` and :func:`do_HEAD` functions are modified to run CGI scripts
  43    and serve the output, instead of serving files, if the request leads to
  44    somewhere below the ``cgi_directories`` path.
  45
  46 The :class:`CGIHTTPRequestHandler` defines the following data member:
  47
  48
  49 .. attribute:: CGIHTTPRequestHandler.cgi_directories
  50
  51    This defaults to ``['/cgi-bin', '/htbin']`` and describes directories to treat
  52    as containing CGI scripts.
  53
  54 The :class:`CGIHTTPRequestHandler` defines the following methods:
  55
  56
  57 .. method:: CGIHTTPRequestHandler.do_POST()
  58
  59    This method serves the ``'POST'`` request type, only allowed for CGI scripts.
  60    Error 501, "Can only POST to CGI scripts", is output when trying to POST to a
  61    non-CGI url.
  62
  63 Note that CGI scripts will be run with UID of user nobody, for security reasons.
  64 Problems with the CGI script will be translated to error 403.
  65
  66 For example usage, see the implementation of the :func:`test` function.
  67
  68
  69 .. seealso::
  70
  71    Module :mod:`BaseHTTPServer`
  72       Base class implementation for Web server and request handler.
  73