home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / p / python / !ibrowse / files / pylibi-6 (.txt) < prev    next >
GNU Info File  |  1996-11-14  |  51KB  |  907 lines
  1. This is Info file pylibi, produced by Makeinfo-1.55 from the input file
  2. lib.texi.
  3. This file describes the built-in types, exceptions and functions and the
  4. standard modules that come with the Python system.  It assumes basic
  5. knowledge about the Python language.  For an informal introduction to
  6. the language, see the Python Tutorial.  The Python Reference Manual
  7. gives a more formal definition of the language.  (These manuals are not
  8. yet available in INFO or Texinfo format.)
  9. Copyright 1991-1995 by Stichting Mathematisch Centrum, Amsterdam, The
  10. Netherlands.
  11. All Rights Reserved
  12. Permission to use, copy, modify, and distribute this software and its
  13. documentation for any purpose and without fee is hereby granted,
  14. provided that the above copyright notice appear in all copies and that
  15. both that copyright notice and this permission notice appear in
  16. supporting documentation, and that the names of Stichting Mathematisch
  17. Centrum or CWI or Corporation for National Research Initiatives or CNRI
  18. not be used in advertising or publicity pertaining to distribution of
  19. the software without specific, written prior permission.
  20. While CWI is the initial source for this software, a modified version
  21. is made available by the Corporation for National Research Initiatives
  22. (CNRI) at the Internet address ftp://ftp.python.org.
  23. STICHTING MATHEMATISCH CENTRUM AND CNRI DISCLAIM ALL WARRANTIES WITH
  24. REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF
  25. MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH
  26. CENTRUM OR CNRI BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL
  27. DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
  28. PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
  29. ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
  30. THIS SOFTWARE.
  31. File: pylibi,  Node: Installing your CGI script on a Unix system,  Next: Testing your CGI script,  Prev: Caring about security,  Up: cgi
  32. Installing your CGI script on a Unix system
  33. -------------------------------------------
  34. Read the documentation for your HTTP server and check with your local
  35. system administrator to find the directory where CGI scripts should be
  36. installed; usually this is in a directory `cgi-bin' in the server tree.
  37. Make sure that your script is readable and executable by "others"; the
  38. Unix file mode should be 755 (use `chmod 755 filename').  Make sure
  39. that the first line of the script contains `#!' starting in column 1
  40. followed by the pathname of the Python interpreter, for instance:
  41.          #!/usr/local/bin/python
  42. Make sure the Python interpreter exists and is executable by "others".
  43. Make sure that any files your script needs to read or write are
  44. readable or writable, respectively, by "others" - their mode should be
  45. 644 for readable and 666 for writable.  This is because, for security
  46. reasons, the HTTP server executes your script as user "nobody", without
  47. any special privileges.  It can only read (write, execute) files that
  48. everybody can read (write, execute).  The current directory at
  49. execution time is also different (it is usually the server's cgi-bin
  50. directory) and the set of environment variables is also different from
  51. what you get at login.  in particular, don't count on the shell's
  52. search path for executables (`$PATH') or the Python module search path
  53. (`$PYTHONPATH') to be set to anything interesting.
  54. If you need to load modules from a directory which is not on Python's
  55. default module search path, you can change the path in your script,
  56. before importing other modules, e.g.:
  57.          import sys
  58.          sys.path.insert(0, "/usr/home/joe/lib/python")
  59.          sys.path.insert(0, "/usr/local/lib/python")
  60. (This way, the directory inserted last will be searched first!)
  61. Instructions for non-Unix systems will vary; check your HTTP server's
  62. documentation (it will usually have a section on CGI scripts).
  63. File: pylibi,  Node: Testing your CGI script,  Next: Debugging CGI scripts,  Prev: Installing your CGI script on a Unix system,  Up: cgi
  64. Testing your CGI script
  65. -----------------------
  66. Unfortunately, a CGI script will generally not run when you try it from
  67. the command line, and a script that works perfectly from the command
  68. line may fail mysteriously when run from the server.  There's one
  69. reason why you should still test your script from the command line: if
  70. it contains a syntax error, the python interpreter won't execute it at
  71. all, and the HTTP server will most likely send a cryptic error to the
  72. client.
  73. Assuming your script has no syntax errors, yet it does not work, you
  74. have no choice but to read the next section:
  75. File: pylibi,  Node: Debugging CGI scripts,  Next: Common problems and solutions,  Prev: Testing your CGI script,  Up: cgi
  76. Debugging CGI scripts
  77. ---------------------
  78. First of all, check for trivial installation errors - reading the
  79. section above on installing your CGI script carefully can save you a
  80. lot of time.  If you wonder whether you have understood the
  81. installation procedure correctly, try installing a copy of this module
  82. file (`cgi.py') as a CGI script.  When invoked as a script, the file
  83. will dump its environment and the contents of the form in HTML form.
  84. Give it the right mode etc, and send it a request.  If it's installed
  85. in the standard `cgi-bin' directory, it should be possible to send it a
  86. request by entering a URL into your browser of the form:
  87.          http://yourhostname/cgi-bin/cgi.py?name=Joe+Blow&addr=At+Home
  88. If this gives an error of type 404, the server cannot find the script -
  89. perhaps you need to install it in a different directory.  If it gives
  90. another error (e.g.  500), there's an installation problem that you
  91. should fix before trying to go any further.  If you get a nicely
  92. formatted listing of the environment and form content (in this example,
  93. the fields should be listed as "addr" with value "At Home" and "name"
  94. with value "Joe Blow"), the `cgi.py' script has been installed
  95. correctly.  If you follow the same procedure for your own script, you
  96. should now be able to debug it.
  97. The next step could be to call the `cgi' module's test() function from
  98. your script: replace its main code with the single statement
  99.          cgi.test()
  100. This should produce the same results as those gotten from installing
  101. the `cgi.py' file itself.
  102. When an ordinary Python script raises an unhandled exception (e.g.
  103. because of a typo in a module name, a file that can't be opened, etc.),
  104. the Python interpreter prints a nice traceback and exits.  While the
  105. Python interpreter will still do this when your CGI script raises an
  106. exception, most likely the traceback will end up in one of the HTTP
  107. server's log file, or be discarded altogether.
  108. Fortunately, once you have managed to get your script to execute *some*
  109. code, it is easy to catch exceptions and cause a traceback to be
  110. printed.  The `test()' function below in this module is an example.
  111. Here are the rules:
  112.   1. Import the traceback module (before entering the try-except!)
  113.   2. Make sure you finish printing the headers and the blank line early
  114.   3. Assign `sys.stderr' to `sys.stdout'
  115.   4. Wrap all remaining code in a try-except statement
  116.   5. In the except clause, call `traceback.print_exc()'
  117. For example:
  118.          import sys
  119.          import traceback
  120.          print "Content-type: text/html"
  121.          print
  122.          sys.stderr = sys.stdout
  123.          try:
  124.              ...your code here...
  125.          except:
  126.              print "\n\n<PRE>"
  127.              traceback.print_exc()
  128. Notes: The assignment to `sys.stderr' is needed because the traceback
  129. prints to `sys.stderr'.  The `print "nn<PRE>"' statement is necessary to
  130. disable the word wrapping in HTML.
  131. If you suspect that there may be a problem in importing the traceback
  132. module, you can use an even more robust approach (which only uses
  133. built-in modules):
  134.          import sys
  135.          sys.stderr = sys.stdout
  136.          print "Content-type: text/plain"
  137.          print
  138.          ...your code here...
  139. This relies on the Python interpreter to print the traceback.  The
  140. content type of the output is set to plain text, which disables all
  141. HTML processing.  If your script works, the raw HTML will be displayed
  142. by your client.  If it raises an exception, most likely after the first
  143. two lines have been printed, a traceback will be displayed.  Bec