mirror of https://github.com/python/cpython
68 lines
3.0 KiB
TeX
68 lines
3.0 KiB
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. (It's 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}
|