mirror of https://github.com/python/cpython
90 lines
3.8 KiB
ReStructuredText
90 lines
3.8 KiB
ReStructuredText
:mod:`cgitb` --- Traceback manager for CGI scripts
|
|
==================================================
|
|
|
|
.. module:: cgitb
|
|
:synopsis: Configurable traceback handler for CGI scripts.
|
|
:deprecated:
|
|
|
|
.. moduleauthor:: Ka-Ping Yee <ping@lfw.org>
|
|
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
|
|
|
|
**Source code:** :source:`Lib/cgitb.py`
|
|
|
|
.. index::
|
|
single: CGI; exceptions
|
|
single: CGI; tracebacks
|
|
single: exceptions; in CGI scripts
|
|
single: tracebacks; in CGI scripts
|
|
|
|
.. deprecated-removed:: 3.11 3.13
|
|
The :mod:`cgitb` module is deprecated
|
|
(see :pep:`PEP 594 <594#cgitb>` for details).
|
|
|
|
--------------
|
|
|
|
The :mod:`cgitb` module provides a special exception handler for Python scripts.
|
|
(Its name is a bit misleading. It was originally designed to display extensive
|
|
traceback information in HTML for CGI scripts. It was later generalized to also
|
|
display this information in plain text.) After this module is activated, if an
|
|
uncaught exception occurs, a detailed, formatted report will be displayed. 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 this to the top of your CGI script::
|
|
|
|
import cgitb
|
|
cgitb.enable()
|
|
|
|
The options to the :func:`enable` function control whether the report is
|
|
displayed in the browser and whether the report is logged to a file for later
|
|
analysis.
|
|
|
|
|
|
.. function:: enable(display=1, logdir=None, context=5, format="html")
|
|
|
|
.. index:: single: excepthook() (in module sys)
|
|
|
|
This function causes the :mod:`cgitb` module to take over the interpreter's
|
|
default handling for exceptions by setting the value of :attr:`sys.excepthook`.
|
|
|
|
The optional argument *display* defaults to ``1`` and can be set to ``0`` to
|
|
suppress sending the traceback to the browser. If the argument *logdir* is
|
|
present, the traceback reports are written to files. The value of *logdir*
|
|
should be a directory where these files will be placed. The optional argument
|
|
*context* is the number of lines of context to display around the current line
|
|
of source code in the traceback; this defaults to ``5``. If the optional
|
|
argument *format* is ``"html"``, the output is formatted as HTML. Any other
|
|
value forces plain text output. The default value is ``"html"``.
|
|
|
|
|
|
.. function:: text(info, context=5)
|
|
|
|
This function handles the exception described by *info* (a 3-tuple containing
|
|
the result of :func:`sys.exc_info`), formatting its traceback as text and
|
|
returning the result as a string. The optional argument *context* is the
|
|
number of lines of context to display around the current line of source code
|
|
in the traceback; this defaults to ``5``.
|
|
|
|
|
|
.. function:: html(info, context=5)
|
|
|
|
This function handles the exception described by *info* (a 3-tuple containing
|
|
the result of :func:`sys.exc_info`), formatting its traceback as HTML and
|
|
returning the result as a string. The optional argument *context* is the
|
|
number of lines of context to display around the current line of source code
|
|
in the traceback; this defaults to ``5``.
|
|
|
|
|
|
.. function:: handler(info=None)
|
|
|
|
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 :mod:`cgitb`. The optional
|
|
*info* argument should be a 3-tuple containing an exception type, exception
|
|
value, and traceback object, exactly like the tuple returned by
|
|
:func:`sys.exc_info`. If the *info* argument is not supplied, the current
|
|
exception is obtained from :func:`sys.exc_info`.
|
|
|