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     return None, __UNDEF__
  46
  47 def scanvars(reader, frame, locals):
  48     """Scan one logical line of Python and look up values of variables used."""
  49     import tokenize, keyword
  50     vars, lasttoken, parent, prefix = [], None, None, ''
  51     for ttype, token, start, end, line in tokenize.generate_tokens(reader):
  52         if ttype == tokenize.NEWLINE: break
  53         if ttype == tokenize.NAME and token not in keyword.kwlist:
  54             if lasttoken == '.':
  55                 if parent is not __UNDEF__:
  56                     value = getattr(parent, token, __UNDEF__)
  57                     vars.append((prefix + token, prefix, value))
  58             else:
  59                 where, value = lookup(token, frame, locals)
  60                 vars.append((token, where, value))
  61         elif token == '.':
  62             prefix += lasttoken + '.'
  63             parent = value
  64         else:
  65             parent, prefix = None, ''
  66         lasttoken = token
  67     return vars
  68
  69 def html((etype, evalue, etb), context=5):
  70     """Return a nice HTML document describing a given traceback."""
  71     import os, types, time, traceback, linecache, inspect, pydoc
  72
  73     if type(etype) is types.ClassType:
  74         etype = etype.__name__
  75     pyver = 'Python ' + sys.version.split()[0] + ': ' + sys.executable
  76     date = time.ctime(time.time())
  77     head = '<body bgcolor="#f0f0f8">' + pydoc.html.heading(
  78         '<big><big><strong>%s</strong></big></big>' % str(etype),
  79         '#ffffff', '#6622aa', pyver + '<br>' + date) + '''
  80 <p>A problem occurred in a Python script.  Here is the sequence of
  81 function calls leading up to the error, in the order they occurred.'''
  82
  83     indent = '<tt>' + small('&nbsp;' * 5) + '&nbsp;</tt>'
  84     frames = []
  85     records = inspect.getinnerframes(etb, context)
  86     for frame, file, lnum, func, lines, index in records:
  87         file = file and os.path.abspath(file) or '?'
  88         link = '<a href="file://%s">%s</a>' % (file, pydoc.html.escape(file))
  89         args, varargs, varkw, locals = inspect.getargvalues(frame)
  90         call = ''
  91         if func != '?':
  92             call = 'in ' + strong(func) + \
  93                 inspect.formatargvalues(args, varargs, varkw, locals,
  94                     formatvalue=lambda value: '=' + pydoc.html.repr(value))
  95
  96         highlight = {}
  97         def reader(lnum=[lnum]):
  98             highlight[lnum[0]] = 1
  99             try: return linecache.getline(file, lnum[0])
 100             finally: lnum[0] += 1
 101         vars = scanvars(reader, frame, locals)
 102
 103         rows = ['<tr><td bgcolor="#d8bbff">%s%s %s</td></tr>' %
 104                 ('<big>&nbsp;</big>', link, call)]
 105         if index is not None:
 106             i = lnum - index
 107             for line in lines:
 108                 num = small('&nbsp;' * (5-len(str(i))) + str(i)) + '&nbsp;'
 109                 line = '<tt>%s%s</tt>' % (num, pydoc.html.preformat(line))
 110                 if i in highlight:
 111                     rows.append('<tr><td bgcolor="#ffccee">%s</td></tr>' % line)
 112                 else:
 113                     rows.append('<tr><td>%s</td></tr>' % grey(line))
 114                 i += 1
 115
 116         done, dump = {}, []
 117         for name, where, value in vars:
 118             if name in done: continue
 119             done[name] = 1
 120             if value is not __UNDEF__:
 121                 if where == 'global': name = '<em>global</em> ' + strong(name)
 122                 elif where == 'local': name = strong(name)
 123                 else: name = where + strong(name.split('.')[-1])
 124                 dump.append('%s&nbsp;= %s' % (name, pydoc.html.repr(value)))
 125             else:
 126                 dump.append(name + ' <em>undefined</em>')
 127
 128         rows.append('<tr><td>%s</td></tr>' % small(grey(', '.join(dump))))
 129         frames.append('''<p>
 130 <table width="100%%" cellspacing=0 cellpadding=0 border=0>
 131 %s</table>''' % '\n'.join(rows))
 132
 133     exception = ['<p>%s: %s' % (strong(str(etype)), str(evalue))]
 134     if type(evalue) is types.InstanceType:
 135         for name in dir(evalue):
 136             value = pydoc.html.repr(getattr(evalue, name))
 137             exception.append('\n<br>%s%s&nbsp;=\n%s' % (indent, name, value))
 138
 139     import traceback
 140     return head + ''.join(frames) + ''.join(exception) + '''
 141
 142
 143 <!-- The above is a description of an error in a Python program, formatted
 144      for a Web browser because the 'cgitb' module was enabled.  In case you
 145      are not reading this in a Web browser, here is the original traceback:
 146
 147 %s
 148 -->
 149 ''' % ''.join(traceback.format_exception(etype, evalue, etb))
 150
 151 class Hook:
 152     """A hook to replace sys.excepthook that shows tracebacks in HTML."""
 153
 154     def __init__(self, display=1, logdir=None, context=5, file=None):
 155         self.display = display          # send tracebacks to browser if true
 156         self.logdir = logdir            # log tracebacks to files if not None
 157         self.context = context          # number of source code lines per frame
 158         self.file = file or sys.stdout  # place to send the output
 159
 160     def __call__(self, etype, evalue, etb):
 161         self.handle((etype, evalue, etb))
 162
 163     def handle(self, info=None):
 164         info = info or sys.exc_info()
 165         self.file.write(reset())
 166
 167         try:
 168             text, doc = 0, html(info, self.context)
 169         except:                         # just in case something goes wrong
 170             import traceback
 171             text, doc = 1, ''.join(traceback.format_exception(*info))
 172
 173         if self.display:
 174             if text:
 175                 doc = doc.replace('&', '&amp;').replace('<', '&lt;')
 176                 self.file.write('<pre>' + doc + '</pre>\n')
 177             else:
 178                 self.file.write(doc + '\n')
 179         else:
 180             self.file.write('<p>A problem occurred in a Python script.\n')
 181
 182         if self.logdir is not None:
 183             import os, tempfile
 184             name = tempfile.mktemp(['.html', '.txt'][text])
 185             path = os.path.join(self.logdir, os.path.basename(name))
 186             try:
 187                 file = open(path, 'w')
 188                 file.write(doc)
 189                 file.close()
 190                 msg = '<p> %s contains the description of this error.' % path
 191             except:
 192                 msg = '<p> Tried to save traceback to %s, but failed.' % path
 193             self.file.write(msg + '\n')
 194         try:
 195             self.file.flush()
 196         except: pass
 197
 198 handler = Hook().handle
 199 def enable(display=1, logdir=None, context=5):
 200     """Install an exception handler that formats tracebacks as HTML.
 201
 202     The optional argument 'display' can be set to 0 to suppress sending the
 203     traceback to the browser, and 'logdir' can be set to a directory to cause
 204     tracebacks to be written to files there."""
 205     sys.excepthook = Hook(display, logdir, context)