Mac/Tools/CGI/CGI_README.txt

   1 Python CGI under MacOS
   2
   3 This folder contains two tools that enable Python CGI scripts under
   4 Mac based web servers, like WebStar, Quid Quo Pro, NetPresentz or
   5 Apple's Personal Webserver.
   6
   7 Both tools emulate Unix style CGI's, allowing for cross platform
   8 CGI scripts. In short, this happens by converting an AppleEvent sent
   9 by the web server into os.environ dictionary entries. See below for more
  10 details.
  11
  12 Both tools serve slightly different purposes:
  13 - PythonCGISlave enables execution of Python scripts as plain *.py
  14   text files. The web server must be configured to handle .py requests
  15   over to PythonCGISlave. Not all web servers support that. Eg. WebStar
  16   does, but NetPresentz does not.
  17 - BuildCGIApplet wraps a Python CGI script in a compatibility layer, and
  18   creates a CGI Applet which can be executed by any web server.
  19
  20 The pros and cons of using PythonCGISlave are (+ is good, - is bad):
  21         + support plain .py files, no need to wrap each script
  22         - not supported b all servers, requires more complicated configuration
  23 The pros and cons of using BuildCGIApplet are:
  24         + supported by more servers
  25         + less configuration troubles
  26         - must wrap each script
  27
  28
  29 Using BuildCGIApplet
  30
  31 Drop your CGI script onto BuildCGIApplet. An applet called <script name>.cgi
  32 will be created. Move it to the appropriate location in the HTTP document tree.
  33 Make sure your web server is configured to handle .cgi applet files. Usually
  34 it is configured correctly by default, since .cgi is a standard extension.
  35 If your CGI applet starts up for the first time, a file <applet name>.errors
  36 is created. If your CGI script causes an exception, debug info will be written
  37 to that file.
  38
  39
  40 Using PythonCGISlave
  41
  42 Place the PythonCGISlave applet somewhere in the HTTP document tree. Configure
  43 your web server so it'll pass requests for .py files to PythonCGISlave. For
  44 Webstar, this goes roughly like this:
  45 - in the WebStar Admin app, create a new "action", call it PYTHON, click the
  46   "Choose" button and select our applet. Save the settings.
  47 - go to Suffix Mappings, create a new suffix .PY, type TEXT, creator *, and
  48   choose PYTHON in the actions popup. Save the settings.
  49
  50
  51 How it works
  52
  53 For each Python CGI request, the web server will send an AppleEvent to the
  54 CGI applet. Most relevant CGI parameters are taken from the AppleEvent and
  55 get stuffed into the os.environ dictionary. Then the script gets executed.
  56 This emulates Unix-style CGI as much as possible, so CGI scripts that are
  57 written portably should now also work under a Mac web server.
  58
  59 Since the applet does not quit after each request by default, there is hardly
  60 any startup overhead except the first time it starts up. If an exception occurs
  61 in the CGI script,  the applet will write a traceback to a file called
  62 <applet name>.errors, and then quit. The latter seems a good idea, just in case
  63 we leak memory. The applet will be restarted upon the next request.
  64
  65
  66 Please direct feedback to <just@letterror.com> and/or <pythonmac-sig@python.org>.