Doc/lib/libcgitb.tex

   1 \section{\module{cgitb} ---
   2          Traceback manager for CGI scripts}
   3
   4 \declaremodule{standard}{cgitb}
   5 \modulesynopsis{Configurable traceback handler for CGI scripts.}
   6 \moduleauthor{Ka-Ping Yee}{ping@lfw.org}
   7 \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
   8
   9 \versionadded{2.2}
  10 \index{CGI!exceptions}
  11 \index{CGI!tracebacks}
  12 \index{exceptions!in CGI scripts}
  13 \index{tracebacks!in CGI scripts}
  14
  15 The \module{cgitb} module provides a special exception handler for CGI
  16 scripts.  After this module is activated, if an uncaught exception occurs,
  17 a detailed, formatted report will be sent to the Web browser.  The report
  18 includes a traceback showing excerpts of the source code for each level,
  19 as well as the values of the arguments and local variables to currently
  20 running functions, to help you debug the problem.  Optionally, you can
  21 save this information to a file instead of sending it to the browser.
  22
  23 To enable this feature, simply add one line to the top of your CGI script:
  24
  25 \begin{verbatim}
  26 import cgitb; cgitb.enable()
  27 \end{verbatim}
  28
  29 The options to the \function{enable()} function control whether the
  30 report is displayed in the browser and whether the report is logged
  31 to a file for later analysis.
  32
  33
  34 \begin{funcdesc}{enable}{\optional{display\optional{, logdir\optional{,
  35                          context}}}}
  36   This function causes the \module{cgitb} module to take over the
  37   interpreter's default handling for exceptions by setting the
  38   value of \code{\refmodule{sys}.excepthook}.
  39   \withsubitem{(in module sys)}{\ttindex{excepthook()}}
  40
  41   The optional argument \var{display} defaults to \code{1} and can be set
  42   to \code{0} to suppress sending the traceback to the browser.
  43   If the argument \var{logdir} is present, the traceback reports are
  44   written to files.  The value of \var{logdir} should be a directory
  45   where these files will be placed.
  46   The optional argument \var{context} is the number of lines of
  47   context to display around the current line of source code in the
  48   traceback; this defaults to \code{5}.
  49 \end{funcdesc}
  50
  51 \begin{funcdesc}{handler}{\optional{info}}
  52   This function handles an exception using the default settings
  53   (that is, show a report in the browser, but don't log to a file).
  54   This can be used when you've caught an exception and want to
  55   report it using \module{cgitb}.  The optional \var{info} argument
  56   should be a 3-tuple containing an exception type, exception
  57   value, and traceback object, exactly like the tuple returned by
  58   \code{\refmodule{sys}.exc_info()}.  If the \var{info} argument
  59   is not supplied, the current exception is obtained from
  60   \code{\refmodule{sys}.exc_info()}.
  61 \end{funcdesc}