1:mod:`cgitb` --- Traceback manager for CGI scripts
2==================================================
3
4.. module:: cgitb
5   :synopsis: Configurable traceback handler for CGI scripts.
6   :deprecated:
7
8.. moduleauthor:: Ka-Ping Yee <[email protected]>
9.. sectionauthor:: Fred L. Drake, Jr. <[email protected]>
10
11**Source code:** :source:`Lib/cgitb.py`
12
13.. index::
14   single: CGI; exceptions
15   single: CGI; tracebacks
16   single: exceptions; in CGI scripts
17   single: tracebacks; in CGI scripts
18
19.. deprecated-removed:: 3.11 3.13
20   The :mod:`cgitb` module is deprecated
21   (see :pep:`PEP 594 <594#cgitb>` for details).
22
23--------------
24
25The :mod:`cgitb` module provides a special exception handler for Python scripts.
26(Its name is a bit misleading.  It was originally designed to display extensive
27traceback information in HTML for CGI scripts.  It was later generalized to also
28display this information in plain text.)  After this module is activated, if an
29uncaught exception occurs, a detailed, formatted report will be displayed.  The
30report includes a traceback showing excerpts of the source code for each level,
31as well as the values of the arguments and local variables to currently running
32functions, to help you debug the problem.  Optionally, you can save this
33information to a file instead of sending it to the browser.
34
35To enable this feature, simply add this to the top of your CGI script::
36
37   import cgitb
38   cgitb.enable()
39
40The options to the :func:`enable` function control whether the report is
41displayed in the browser and whether the report is logged to a file for later
42analysis.
43
44
45.. function:: enable(display=1, logdir=None, context=5, format="html")
46
47   .. index:: single: excepthook() (in module sys)
48
49   This function causes the :mod:`cgitb` module to take over the interpreter's
50   default handling for exceptions by setting the value of :attr:`sys.excepthook`.
51
52   The optional argument *display* defaults to ``1`` and can be set to ``0`` to
53   suppress sending the traceback to the browser. If the argument *logdir* is
54   present, the traceback reports are written to files.  The value of *logdir*
55   should be a directory where these files will be placed. The optional argument
56   *context* is the number of lines of context to display around the current line
57   of source code in the traceback; this defaults to ``5``. If the optional
58   argument *format* is ``"html"``, the output is formatted as HTML.  Any other
59   value forces plain text output.  The default value is ``"html"``.
60
61
62.. function:: text(info, context=5)
63
64   This function handles the exception described by *info* (a 3-tuple containing
65   the result of :func:`sys.exc_info`), formatting its traceback as text and
66   returning the result as a string. The optional argument *context* is the
67   number of lines of context to display around the current line of source code
68   in the traceback; this defaults to ``5``.
69
70
71.. function:: html(info, context=5)
72
73   This function handles the exception described by *info* (a 3-tuple containing
74   the result of :func:`sys.exc_info`), formatting its traceback as HTML and
75   returning the result as a string. The optional argument *context* is the
76   number of lines of context to display around the current line of source code
77   in the traceback; this defaults to ``5``.
78
79
80.. function:: handler(info=None)
81
82   This function handles an exception using the default settings (that is, show a
83   report in the browser, but don't log to a file). This can be used when you've
84   caught an exception and want to report it using :mod:`cgitb`.  The optional
85   *info* argument should be a 3-tuple containing an exception type, exception
86   value, and traceback object, exactly like the tuple returned by
87   :func:`sys.exc_info`.  If the *info* argument is not supplied, the current
88   exception is obtained from :func:`sys.exc_info`.
89
90