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