1 

     2 :mod:`cgitb` --- Traceback manager for CGI scripts

     3 ==================================================

     4 

     5 .. module:: cgitb

     6    :synopsis: Configurable traceback handler for CGI scripts.

     7 .. moduleauthor:: Ka-Ping Yee <ping@lfw.org>

     8 .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>

     9 

    10 

    11 .. versionadded:: 2.2

    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 The :mod:`cgitb` module provides a special exception handler for Python scripts.

    20 (Its name is a bit misleading.  It was originally designed to display extensive

    21 traceback information in HTML for CGI scripts.  It was later generalized to also

    22 display this information in plain text.)  After this module is activated, if an

    23 uncaught exception occurs, a detailed, formatted report will be displayed.  The

    24 report includes a traceback showing excerpts of the source code for each level,

    25 as well as the values of the arguments and local variables to currently running

    26 functions, to help you debug the problem.  Optionally, you can save this

    27 information to a file instead of sending it to the browser.

    28 

    29 To enable this feature, simply add one line to the top of your CGI script::

    30 

    31    import cgitb; cgitb.enable()

    32 

    33 The options to the :func:`enable` function control whether the report is

    34 displayed in the browser and whether the report is logged to a file for later

    35 analysis.

    36 

    37 

    38 .. function:: enable([display[, logdir[, context[, format]]]])

    39 

    40    .. index:: single: excepthook() (in module sys)

    41 

    42    This function causes the :mod:`cgitb` module to take over the interpreter's

    43    default handling for exceptions by setting the value of :attr:`sys.excepthook`.

    44 

    45    The optional argument *display* defaults to ``1`` and can be set to ``0`` to

    46    suppress sending the traceback to the browser. If the argument *logdir* is

    47    present, the traceback reports are written to files.  The value of *logdir*

    48    should be a directory where these files will be placed. The optional argument

    49    *context* is the number of lines of context to display around the current line

    50    of source code in the traceback; this defaults to ``5``. If the optional

    51    argument *format* is ``"html"``, the output is formatted as HTML.  Any other

    52    value forces plain text output.  The default value is ``"html"``.

    53 

    54 

    55 .. function:: handler([info])

    56 

    57    This function handles an exception using the default settings (that is, show a

    58    report in the browser, but don't log to a file). This can be used when you've

    59    caught an exception and want to report it using :mod:`cgitb`.  The optional

    60    *info* argument should be a 3-tuple containing an exception type, exception

    61    value, and traceback object, exactly like the tuple returned by

    62    :func:`sys.exc_info`.  If the *info* argument is not supplied, the current

    63    exception is obtained from :func:`sys.exc_info`.

    64