| 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 Python
|
|---|
| 16 | scripts. (Its name is a bit misleading. It was originally designed to
|
|---|
| 17 | display extensive traceback information in HTML for CGI scripts. It was
|
|---|
| 18 | later generalized to also display this information in plain text.) After
|
|---|
| 19 | this module is activated, if an uncaught exception occurs, a detailed,
|
|---|
| 20 | formatted report will be displayed. The report
|
|---|
| 21 | includes a traceback showing excerpts of the source code for each level,
|
|---|
| 22 | as well as the values of the arguments and local variables to currently
|
|---|
| 23 | running functions, to help you debug the problem. Optionally, you can
|
|---|
| 24 | save this information to a file instead of sending it to the browser.
|
|---|
| 25 |
|
|---|
| 26 | To enable this feature, simply add one line to the top of your CGI script:
|
|---|
| 27 |
|
|---|
| 28 | \begin{verbatim}
|
|---|
| 29 | import cgitb; cgitb.enable()
|
|---|
| 30 | \end{verbatim}
|
|---|
| 31 |
|
|---|
| 32 | The options to the \function{enable()} function control whether the
|
|---|
| 33 | report is displayed in the browser and whether the report is logged
|
|---|
| 34 | to a file for later analysis.
|
|---|
| 35 |
|
|---|
| 36 |
|
|---|
| 37 | \begin{funcdesc}{enable}{\optional{display\optional{, logdir\optional{,
|
|---|
| 38 | context\optional{, format}}}}}
|
|---|
| 39 | This function causes the \module{cgitb} module to take over the
|
|---|
| 40 | interpreter's default handling for exceptions by setting the
|
|---|
| 41 | value of \code{\refmodule{sys}.excepthook}.
|
|---|
| 42 | \withsubitem{(in module sys)}{\ttindex{excepthook()}}
|
|---|
| 43 |
|
|---|
| 44 | The optional argument \var{display} defaults to \code{1} and can be set
|
|---|
| 45 | to \code{0} to suppress sending the traceback to the browser.
|
|---|
| 46 | If the argument \var{logdir} is present, the traceback reports are
|
|---|
| 47 | written to files. The value of \var{logdir} should be a directory
|
|---|
| 48 | where these files will be placed.
|
|---|
| 49 | The optional argument \var{context} is the number of lines of
|
|---|
| 50 | context to display around the current line of source code in the
|
|---|
| 51 | traceback; this defaults to \code{5}.
|
|---|
| 52 | If the optional argument \var{format} is \code{"html"}, the output is
|
|---|
| 53 | formatted as HTML. Any other value forces plain text output. The default
|
|---|
| 54 | value is \code{"html"}.
|
|---|
| 55 | \end{funcdesc}
|
|---|
| 56 |
|
|---|
| 57 | \begin{funcdesc}{handler}{\optional{info}}
|
|---|
| 58 | This function handles an exception using the default settings
|
|---|
| 59 | (that is, show a report in the browser, but don't log to a file).
|
|---|
| 60 | This can be used when you've caught an exception and want to
|
|---|
| 61 | report it using \module{cgitb}. The optional \var{info} argument
|
|---|
| 62 | should be a 3-tuple containing an exception type, exception
|
|---|
| 63 | value, and traceback object, exactly like the tuple returned by
|
|---|
| 64 | \code{\refmodule{sys}.exc_info()}. If the \var{info} argument
|
|---|
| 65 | is not supplied, the current exception is obtained from
|
|---|
| 66 | \code{\refmodule{sys}.exc_info()}.
|
|---|
| 67 | \end{funcdesc}
|
|---|
