traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Merge in Ping's changes to the cgitb documentation, and add a version 

annotation as well.
This closes SF patch #494582.
This commit is contained in:
Fred Drake 2001-12-18 15:51:55 +00:00
parent 6f4f8c7fe1
commit e088970ce0
1 changed files with 40 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
Doc/lib/libcgitb.tex
View File

@ -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}