Lib/cgitb.py

   1 """Handle exceptions in CGI scripts by formatting tracebacks into nice HTML.
   2
   3 To enable this module, do:
   4
   5     import cgitb; cgitb.enable()
   6
   7 at the top of your CGI script.  The optional arguments to enable() are:
   8
   9     display     - if true, tracebacks are displayed in the web browser
  10     logdir      - if set, tracebacks are written to files in this directory
  11     context     - number of lines of source code to show for each stack frame
  12
  13 By default, tracebacks are displayed but not saved, and context is 5.
  14
  15 Alternatively, if you have caught an exception and want cgitb to display it
  16 for you, call cgitb.handler().  The optional argument to handler() is a 3-item
  17 tuple (etype, evalue, etb) just like the value of sys.exc_info()."""
  18
  19 __author__ = 'Ka-Ping Yee'
  20 __version__ = '$Revision$'
  21
  22 import sys
  23
  24 def reset():
  25     """Return a string that resets the CGI and browser to a known state."""
  26     return '''<!--: spam
  27 Content-Type: text/html
  28
  29 <body bgcolor="#f0f0f8"><font color="#f0f0f8" size="-5"> -->
  30 <body bgcolor="#f0f0f8"><font color="#f0f0f8" size="-5"> --> -->
  31 </font> </font> </font> </script> </object> </blockquote> </pre>
  32 </table> </table> </table> </table> </table> </font> </font> </font>'''
  33
  34 __UNDEF__ = []                          # a special sentinel object
  35 def small(text): return '<small>' + text + '</small>'
  36 def strong(text): return '<strong>' + text + '</strong>'
  37 def grey(text): return '<font color="#909090">' + text + '</font>'
  38
  39 def lookup(name, frame, locals):
  40     """Find the value for a given name in the given environment."""
  41     if name in locals:
  42         return 'local', locals[name]
  43     if name in frame.f_globals:
  44         return 'global', frame.f_globals[name]
  45     if '__builtins__' in frame.f_globals:
  46         builtins = frame.f_globals['__builtins__']
  47         if type(builtins) is type({}):
  48             if name in builtins:
  49                 return 'builtin', builtins[name]
  50         else:
  51             if hasattr(builtins, name):
  52                 return 'builtin', getattr(builtins, name)
  53     return None, __UNDEF__
  54
  55 def scanvars(reader, frame, locals):
  56     """Scan one logical line of Python and look up values of variables used."""
  57     import tokenize, keyword
  58     vars, lasttoken, parent, prefix = [], None, None, ''
  59     for ttype, token, start, end, line in tokenize.generate_tokens(reader):
  60         if ttype == tokenize.NEWLINE: break
  61         if ttype == tokenize.NAME and token not in keyword.kwlist:
  62             if lasttoken == '.':
  63                 if parent is not __UNDEF__:
  64                     value = getattr(parent, token, __UNDEF__)
  65                     vars.append((prefix + token, prefix, value))
  66             else:
  67                 where, value = lookup(token, frame, locals)
  68                 vars.append((token, where, value))
  69         elif token == '.':
  70             prefix += lasttoken + '.'
  71             parent = value
  72         else:
  73             parent, prefix = None, ''
  74         lasttoken = token
  75     return vars
  76
  77 def html((etype, evalue, etb), context=5):
  78     """Return a nice HTML document describing a given traceback."""
  79     import os, types, time, traceback, linecache, inspect, pydoc
  80
  81     if type(etype) is types.ClassType:
  82         etype = etype.__name__
  83     pyver = 'Python ' + sys.version.split()[0] + ': ' + sys.executable
  84     date = time.ctime(time.time())
  85     head = '<body bgcolor="#f0f0f8">' + pydoc.html.heading(
  86         '<big><big><strong>%s</strong></big></big>' % str(etype),
  87         '#ffffff', '#6622aa', pyver + '<br>' + date) + '''
  88 <p>A problem occurred in a Python script.  Here is the sequence of
  89 function calls leading up to the error, in the order they occurred.'''
  90
  91     indent = '<tt>' + small('&nbsp;' * 5) + '&nbsp;</tt>'
  92     frames = []
  93     records = inspect.getinnerframes(etb, context)
  94     for frame, file, lnum, func, lines, index in records:
  95         file = file and os.path.abspath(file) or '?'
  96         link = '<a href="file://%s">%s</a>' % (file, pydoc.html.escape(file))
  97         args, varargs, varkw, locals = inspect.getargvalues(frame)
  98         call = ''
  99         if func != '?':
 100             call = 'in ' + strong(func) + \
 101                 inspect.formatargvalues(args, varargs, varkw, locals,
 102                     formatvalue=lambda value: '=' + pydoc.html.repr(value))
 103
 104         highlight = {}
 105         def reader(lnum=[lnum]):
 106             highlight[lnum[0]] = 1
 107             try: return linecache.getline(file, lnum[0])
 108             finally: lnum[0] += 1
 109         vars = scanvars(reader, frame, locals)
 110
 111         rows = ['<tr><td bgcolor="#d8bbff">%s%s %s</td></tr>' %
 112                 ('<big>&nbsp;</big>', link, call)]
 113         if index is not None:
 114             i = lnum - index
 115             for line in lines:
 116                 num = small('&nbsp;' * (5-len(str(i))) + str(i)) + '&nbsp;'
 117                 line = '<tt>%s%s</tt>' % (num, pydoc.html.preformat(line))
 118                 if i in highlight:
 119                     rows.append('<tr><td bgcolor="#ffccee">%s</td></tr>' % line)
 120                 else:
 121                     rows.append('<tr><td>%s</td></tr>' % grey(line))
 122                 i += 1
 123
 124         done, dump = {}, []
 125         for name, where, value in vars:
 126             if name in done: continue
 127             done[name] = 1
 128             if value is not __UNDEF__:
 129                 if where in ['global', 'builtin']:
 130                     name = ('<em>%s</em> ' % where) + strong(name)
 131                 elif where == 'local':
 132                     name = strong(name)
 133                 else:
 134                     name = where + strong(name.split('.')[-1])
 135                 dump.append('%s&nbsp;= %s' % (name, pydoc.html.repr(value)))
 136             else:
 137                 dump.append(name + ' <em>undefined</em>')
 138
 139         rows.append('<tr><td>%s</td></tr>' % small(grey(', '.join(dump))))
 140         frames.append('''<p>
 141 <table width="100%%" cellspacing=0 cellpadding=0 border=0>
 142 %s</table>''' % '\n'.join(rows))
 143
 144     exception = ['<p>%s: %s' % (strong(str(etype)), str(evalue))]
 145     if type(evalue) is types.InstanceType:
 146         for name in dir(evalue):
 147             if name[:1] == '_': continue
 148             value = pydoc.html.repr(getattr(evalue, name))
 149             exception.append('\n<br>%s%s&nbsp;=\n%s' % (indent, name, value))
 150
 151     import traceback
 152     return head + ''.join(frames) + ''.join(exception) + '''
 153
 154
 155 <!-- The above is a description of an error in a Python program, formatted
 156      for a Web browser because the 'cgitb' module was enabled.  In case you
 157      are not reading this in a Web browser, here is the original traceback:
 158
 159 %s
 160 -->
 161 ''' % ''.join(traceback.format_exception(etype, evalue, etb))
 162
 163 class Hook:
 164     """A hook to replace sys.excepthook that shows tracebacks in HTML."""
 165
 166     def __init__(self, display=1, logdir=None, context=5, file=None):
 167         self.display = display          # send tracebacks to browser if true
 168         self.logdir = logdir            # log tracebacks to files if not None
 169         self.context = context          # number of source code lines per frame
 170         self.file = file or sys.stdout  # place to send the output
 171
 172     def __call__(self, etype, evalue, etb):
 173         self.handle((etype, evalue, etb))
 174
 175     def handle(self, info=None):
 176         info = info or sys.exc_info()
 177         self.file.write(reset())
 178
 179         try:
 180             text, doc = 0, html(info, self.context)
 181         except:                         # just in case something goes wrong
 182             import traceback
 183             text, doc = 1, ''.join(traceback.format_exception(*info))
 184
 185         if self.display:
 186             if text:
 187                 doc = doc.replace('&', '&amp;').replace('<', '&lt;')
 188                 self.file.write('<pre>' + doc + '</pre>\n')
 189             else:
 190                 self.file.write(doc + '\n')
 191         else:
 192             self.file.write('<p>A problem occurred in a Python script.\n')
 193
 194         if self.logdir is not None:
 195             import os, tempfile
 196             (fd, path) = tempfile.mkstemp(suffix=['.html', '.txt'][text],
 197                                           dir=self.logdir)
 198             try:
 199                 file = os.fdopen(fd, 'w')
 200                 file.write(doc)
 201                 file.close()
 202                 msg = '<p> %s contains the description of this error.' % path
 203             except:
 204                 msg = '<p> Tried to save traceback to %s, but failed.' % path
 205             self.file.write(msg + '\n')
 206         try:
 207             self.file.flush()
 208         except: pass
 209
 210 handler = Hook().handle
 211 def enable(display=1, logdir=None, context=5):
 212     """Install an exception handler that formats tracebacks as HTML.
 213
 214     The optional argument 'display' can be set to 0 to suppress sending the
 215     traceback to the browser, and 'logdir' can be set to a directory to cause
 216     tracebacks to be written to files there."""
 217     sys.excepthook = Hook(display, logdir, context)