diff options
author | Fred Drake <fdrake@acm.org> | 2001-12-18 15:51:55 (GMT) |
---|---|---|
committer | Fred Drake <fdrake@acm.org> | 2001-12-18 15:51:55 (GMT) |
commit | e088970ce02e8d225bd28d4e2cf13b4b9b5e107d (patch) | |
tree | f5a0672772788c350bd11b6011d4e419affce188 /Doc/lib | |
parent | 6f4f8c7fe1dbaabe117ff6a6bdcf6efd1cc08f48 (diff) | |
download | cpython-e088970ce02e8d225bd28d4e2cf13b4b9b5e107d.zip cpython-e088970ce02e8d225bd28d4e2cf13b4b9b5e107d.tar.gz cpython-e088970ce02e8d225bd28d4e2cf13b4b9b5e107d.tar.bz2 |
Merge in Ping's changes to the cgitb documentation, and add a version
annotation as well.
This closes SF patch #494582.
Diffstat (limited to 'Doc/lib')
-rw-r--r-- | Doc/lib/libcgitb.tex | 58 |
1 files changed, 40 insertions, 18 deletions
diff --git a/Doc/lib/libcgitb.tex b/Doc/lib/libcgitb.tex index 0971429..621d325 100644 --- a/Doc/lib/libcgitb.tex +++ b/Doc/lib/libcgitb.tex @@ -3,38 +3,60 @@ \declaremodule{standard}{cgitb} \modulesynopsis{Configurable traceback handler for CGI scripts.} -\moduleauthor{Ka Ping Yee}{ping@lfw.org} +\moduleauthor{Ka-Ping Yee}{ping@lfw.org} \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} +\versionadded{2.2} +\index{CGI!exceptions} \index{CGI!tracebacks} +\index{exception!in CGI scripts} \index{traceback!in CGI scripts} The \module{cgitb} module provides a special exception handler for CGI -scripts. Using this module, an exception raised and left uncaught in -a CGI script can be presented as colorized HTML in the user's Web -browser. The options to the \function{enable()} function can be used -to control whether the colorized traceback is presented and whether -the traceback is logged to a file for later analysis. +scripts. After this module is activated using the \function{enable()} +function, if an uncaught exception occurs, a detailed, formatted +report will be sent to the Web browser. The report includes a +traceback showing excerpts of the source code for each level, as well +as the values of the arguments and local variables to currently +running functions, to help you debug the problem. Optionally, you can +save this information to a file instead of sending it to the browser. + +To enable this feature, simply add one line to the top of your CGI script: + +\begin{verbatim} +import cgitb; cgitb.enable() +\end{verbatim} + +The options to the \function{enable()} function control whether the +report is displayed in the browser and whether the report is logged +to a file for later analysis. \begin{funcdesc}{enable}{\optional{display\optional{, logdir\optional{, context}}}} This function causes the \module{cgitb} module to take over the - interpreters default handling for exceptions that propogate out of - the top level of a script. The causes \module{cgitb} to set the + interpreter's default handling for exceptions by setting the value of \code{\refmodule{sys}.excepthook}. + \withsubitem{(in module sys)}{\ttindex{excepthook()}} - The optional argument \var{display} defaults to true and can be set - to false to suppress sending the traceback to the browser. - \var{logdir}, if given, should be a directory to cause tracebacks to - be written to files there; by default tracebacks will not be written - to files. \var{context} is the number of lines of context around - the offending line in a traceback display; this defaults to - \code{5}. + The optional argument \var{display} defaults to \code{1} and can be set + to \code{0} to suppress sending the traceback to the browser. + If the argument \var{logdir} is present, the traceback reports are + written to files. The value of \var{logdir} should be a directory + where these files will be placed. + The optional argument \var{context} is the number of lines of + context to display around the current line of source code in the + traceback; this defaults to \code{5}. \end{funcdesc} \begin{funcdesc}{handler}{\optional{info}} - This function handles an exception using the default settings. This - can be used when you've caught an exception and want to report it - using \module{cgitb}, but need to continue processing. + This function handles an exception using the default settings + (that is, show a report in the browser, but don't log to a file). + This can be used when you've caught an exception and want to + report it using \module{cgitb}. The optional \var{info} argument + should be a 3-tuple containing an exception type, exception + value, and traceback object, exactly like the tuple returned by + \code{\refmodule{sys}.exc_info()}. If the \var{info} argument + is not supplied, the current exception is obtained from + \code{\refmodule{sys}.exc_info()}. \end{funcdesc} |