Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libcgitb.tex @ 21467:4e35fa5d5708 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add documentation for the help() built-in; contributed by Ka-Ping Yee. This is part of SF patch #494622.
author Fred Drake <fdrake@acm.org>
date Tue, 18 Dec 2001 16:31:08 +0000
parents 3a93145b6a96
children a03b13be2f68
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
21204
f79e4719db96 Documentation for the "cgitb" module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1 \section{\module{cgitb} ---
f79e4719db96 Documentation for the "cgitb" module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
2 Traceback manager for CGI scripts}
f79e4719db96 Documentation for the "cgitb" module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
3
f79e4719db96 Documentation for the "cgitb" module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
4 \declaremodule{standard}{cgitb}
f79e4719db96 Documentation for the "cgitb" module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
5 \modulesynopsis{Configurable traceback handler for CGI scripts.}
21466
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
6 \moduleauthor{Ka-Ping Yee}{ping@lfw.org}
21204
f79e4719db96 Documentation for the "cgitb" module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
7 \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
f79e4719db96 Documentation for the "cgitb" module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
8
21466
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
9 \versionadded{2.2}
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
10 \index{CGI!exceptions}
21204
f79e4719db96 Documentation for the "cgitb" module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
11 \index{CGI!tracebacks}
21466
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
12 \index{exception!in CGI scripts}
21204
f79e4719db96 Documentation for the "cgitb" module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
13 \index{traceback!in CGI scripts}
f79e4719db96 Documentation for the "cgitb" module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
14
f79e4719db96 Documentation for the "cgitb" module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
15 The \module{cgitb} module provides a special exception handler for CGI
21466
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
16 scripts. After this module is activated using the \function{enable()}
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
17 function, if an uncaught exception occurs, a detailed, formatted
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
18 report will be sent to the Web browser. The report includes a
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
19 traceback showing excerpts of the source code for each level, as well
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
20 as the values of the arguments and local variables to currently
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
21 running functions, to help you debug the problem. Optionally, you can
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
22 save this information to a file instead of sending it to the browser.
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
23
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
24 To enable this feature, simply add one line to the top of your CGI script:
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
25
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
26 \begin{verbatim}
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
27 import cgitb; cgitb.enable()
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
28 \end{verbatim}
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
29
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
30 The options to the \function{enable()} function control whether the
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
31 report is displayed in the browser and whether the report is logged
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
32 to a file for later analysis.
21204
f79e4719db96 Documentation for the "cgitb" module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
33
f79e4719db96 Documentation for the "cgitb" module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
34
f79e4719db96 Documentation for the "cgitb" module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
35 \begin{funcdesc}{enable}{\optional{display\optional{, logdir\optional{,
f79e4719db96 Documentation for the "cgitb" module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
36 context}}}}
f79e4719db96 Documentation for the "cgitb" module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
37 This function causes the \module{cgitb} module to take over the
21466
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
38 interpreter's default handling for exceptions by setting the
21204
f79e4719db96 Documentation for the "cgitb" module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
39 value of \code{\refmodule{sys}.excepthook}.
21466
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
40 \withsubitem{(in module sys)}{\ttindex{excepthook()}}
21204
f79e4719db96 Documentation for the "cgitb" module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
41
21466
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
42 The optional argument \var{display} defaults to \code{1} and can be set
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
43 to \code{0} to suppress sending the traceback to the browser.
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
44 If the argument \var{logdir} is present, the traceback reports are
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
45 written to files. The value of \var{logdir} should be a directory
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
46 where these files will be placed.
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
47 The optional argument \var{context} is the number of lines of
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
48 context to display around the current line of source code in the
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
49 traceback; this defaults to \code{5}.
21204
f79e4719db96 Documentation for the "cgitb" module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
50 \end{funcdesc}
f79e4719db96 Documentation for the "cgitb" module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
51
f79e4719db96 Documentation for the "cgitb" module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
52 \begin{funcdesc}{handler}{\optional{info}}
21466
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
53 This function handles an exception using the default settings
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
54 (that is, show a report in the browser, but don't log to a file).
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
55 This can be used when you've caught an exception and want to
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
56 report it using \module{cgitb}. The optional \var{info} argument
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
57 should be a 3-tuple containing an exception type, exception
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
58 value, and traceback object, exactly like the tuple returned by
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
59 \code{\refmodule{sys}.exc_info()}. If the \var{info} argument
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
60 is not supplied, the current exception is obtained from
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
61 \code{\refmodule{sys}.exc_info()}.
21204
f79e4719db96 Documentation for the "cgitb" module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
62 \end{funcdesc}