summaryrefslogtreecommitdiffstats
path: root/Doc/lib
diff options
context:
space:
mode:
authorFred Drake <fdrake@acm.org>2001-12-18 15:51:55 (GMT)
committerFred Drake <fdrake@acm.org>2001-12-18 15:51:55 (GMT)
commite088970ce02e8d225bd28d4e2cf13b4b9b5e107d (patch)
treef5a0672772788c350bd11b6011d4e419affce188 /Doc/lib
parent6f4f8c7fe1dbaabe117ff6a6bdcf6efd1cc08f48 (diff)
downloadcpython-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.tex58
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}