Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libcgitb.tex @ 38664:7619216bbc19 2.4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Bug #1502728: Correctly link against librt library on HP-UX. (backport from rev. 46743)
author Georg Brandl <georg@python.org>
date Thu, 08 Jun 2006 12:54:16 +0000
parents 96d538488aee
children 06145fbc7ab9
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}
21504
a03b13be2f68 Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents: 21466
diff changeset
12 \index{exceptions!in CGI scripts}
a03b13be2f68 Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents: 21466
diff changeset
13 \index{tracebacks!in CGI scripts}
21204
f79e4719db96 Documentation for the "cgitb" module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
14
29511
d1acf89d1c49 SF Patch 569574 - enhancements to cgitb for plain text display
Skip Montanaro <skip@pobox.com>
parents: 21504
diff changeset
15 The \module{cgitb} module provides a special exception handler for Python
33297
96d538488aee Correct incorrect "it's" to "its".
Johannes Gijsbers <jlg@dds.nl>
parents: 29511
diff changeset
16 scripts. (Its name is a bit misleading. It was originally designed to
29511
d1acf89d1c49 SF Patch 569574 - enhancements to cgitb for plain text display
Skip Montanaro <skip@pobox.com>
parents: 21504
diff changeset
17 display extensive traceback information in HTML for CGI scripts. It was
d1acf89d1c49 SF Patch 569574 - enhancements to cgitb for plain text display
Skip Montanaro <skip@pobox.com>
parents: 21504
diff changeset
18 later generalized to also display this information in plain text.) After
d1acf89d1c49 SF Patch 569574 - enhancements to cgitb for plain text display
Skip Montanaro <skip@pobox.com>
parents: 21504
diff changeset
19 this module is activated, if an uncaught exception occurs, a detailed,
d1acf89d1c49 SF Patch 569574 - enhancements to cgitb for plain text display
Skip Montanaro <skip@pobox.com>
parents: 21504
diff changeset
20 formatted report will be displayed. The report
21504
a03b13be2f68 Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents: 21466
diff changeset
21 includes a traceback showing excerpts of the source code for each level,
a03b13be2f68 Re-commit Ping's patch to the cgi and cgitb documentation, using the
Fred Drake <fdrake@acm.org>
parents: 21466
diff changeset
22 as well as the values of the arguments and local variables to currently
21466
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
23 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
24 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
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 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
27
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
28 \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
29 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
30 \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
31
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
32 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
33 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
34 to a file for later analysis.
21204
f79e4719db96 Documentation for the "cgitb" module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
35
f79e4719db96 Documentation for the "cgitb" module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
36
f79e4719db96 Documentation for the "cgitb" module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
37 \begin{funcdesc}{enable}{\optional{display\optional{, logdir\optional{,
29511
d1acf89d1c49 SF Patch 569574 - enhancements to cgitb for plain text display
Skip Montanaro <skip@pobox.com>
parents: 21504
diff changeset
38 context\optional{, format}}}}}
21204
f79e4719db96 Documentation for the "cgitb" module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
39 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
40 interpreter's default handling for exceptions by setting the
21204
f79e4719db96 Documentation for the "cgitb" module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
41 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
42 \withsubitem{(in module sys)}{\ttindex{excepthook()}}
21204
f79e4719db96 Documentation for the "cgitb" module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
43
21466
3a93145b6a96 Merge in Ping's changes to the cgitb documentation, and add a version
Fred Drake <fdrake@acm.org>
parents: 21204
diff changeset
44 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
45 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
46 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
47 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
48 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
49 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
50 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
51 traceback; this defaults to \code{5}.
29511
d1acf89d1c49 SF Patch 569574 - enhancements to cgitb for plain text display
Skip Montanaro <skip@pobox.com>
parents: 21504
diff changeset
52 If the optional argument \var{format} is \code{"html"}, the output is
d1acf89d1c49 SF Patch 569574 - enhancements to cgitb for plain text display
Skip Montanaro <skip@pobox.com>
parents: 21504
diff changeset
53 formatted as HTML. Any other value forces plain text output. The default
d1acf89d1c49 SF Patch 569574 - enhancements to cgitb for plain text display
Skip Montanaro <skip@pobox.com>
parents: 21504
diff changeset
54 value is \code{"html"}.
21204
f79e4719db96 Documentation for the "cgitb" module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
55 \end{funcdesc}
f79e4719db96 Documentation for the "cgitb" module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
56
f79e4719db96 Documentation for the "cgitb" module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
57 \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
58 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
59 (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
60 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
61 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
62 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
63 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
64 \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
65 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
66 \code{\refmodule{sys}.exc_info()}.
21204
f79e4719db96 Documentation for the "cgitb" module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
67 \end{funcdesc}