ref: 4bcd247b909898766d549c3990c230cbeb3d17a3
dir: /sys/src/cmd/python/Doc/lib/libcgitb.tex/
\section{\module{cgitb} ---
Traceback manager for CGI scripts}
\declaremodule{standard}{cgitb}
\modulesynopsis{Configurable traceback handler for CGI scripts.}
\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{exceptions!in CGI scripts}
\index{tracebacks!in CGI scripts}
The \module{cgitb} module provides a special exception handler for Python
scripts. (Its name is a bit misleading. It was originally designed to
display extensive traceback information in HTML for CGI scripts. It was
later generalized to also display this information in plain text.) After
this module is activated, if an uncaught exception occurs, a detailed,
formatted report will be displayed. 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\optional{, format}}}}}
This function causes the \module{cgitb} module to take over 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 \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}.
If the optional argument \var{format} is \code{"html"}, the output is
formatted as HTML. Any other value forces plain text output. The default
value is \code{"html"}.
\end{funcdesc}
\begin{funcdesc}{handler}{\optional{info}}
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}