Lib/traceback.py

   1 """Extract, format and print information about Python stack traces."""
   2
   3 import linecache
   4 import sys
   5 import types
   6
   7 __all__ = ['extract_stack', 'extract_tb', 'format_exception',
   8            'format_exception_only', 'format_list', 'format_stack',
   9            'format_tb', 'print_exc', 'print_exception', 'print_last',
  10            'print_stack', 'print_tb', 'tb_lineno']
  11
  12 def _print(file, str='', terminator='\n'):
  13     file.write(str+terminator)
  14
  15
  16 def print_list(extracted_list, file=None):
  17     """Print the list of tuples as returned by extract_tb() or
  18     extract_stack() as a formatted stack trace to the given file."""
  19     if not file:
  20         file = sys.stderr
  21     for filename, lineno, name, line in extracted_list:
  22         _print(file,
  23                '  File "%s", line %d, in %s' % (filename,lineno,name))
  24         if line:
  25             _print(file, '    %s' % line.strip())
  26
  27 def format_list(extracted_list):
  28     """Format a list of traceback entry tuples for printing.
  29
  30     Given a list of tuples as returned by extract_tb() or
  31     extract_stack(), return a list of strings ready for printing.
  32     Each string in the resulting list corresponds to the item with the
  33     same index in the argument list.  Each string ends in a newline;
  34     the strings may contain internal newlines as well, for those items
  35     whose source text line is not None.
  36     """
  37     list = []
  38     for filename, lineno, name, line in extracted_list:
  39         item = '  File "%s", line %d, in %s\n' % (filename,lineno,name)
  40         if line:
  41             item = item + '    %s\n' % line.strip()
  42         list.append(item)
  43     return list
  44
  45
  46 def print_tb(tb, limit=None, file=None):
  47     """Print up to 'limit' stack trace entries from the traceback 'tb'.
  48
  49     If 'limit' is omitted or None, all entries are printed.  If 'file'
  50     is omitted or None, the output goes to sys.stderr; otherwise
  51     'file' should be an open file or file-like object with a write()
  52     method.
  53     """
  54     if not file:
  55         file = sys.stderr
  56     if limit is None:
  57         if hasattr(sys, 'tracebacklimit'):
  58             limit = sys.tracebacklimit
  59     n = 0
  60     while tb is not None and (limit is None or n < limit):
  61         f = tb.tb_frame
  62         lineno = tb_lineno(tb)
  63         co = f.f_code
  64         filename = co.co_filename
  65         name = co.co_name
  66         _print(file,
  67                '  File "%s", line %d, in %s' % (filename,lineno,name))
  68         line = linecache.getline(filename, lineno)
  69         if line: _print(file, '    ' + line.strip())
  70         tb = tb.tb_next
  71         n = n+1
  72
  73 def format_tb(tb, limit = None):
  74     """A shorthand for 'format_list(extract_stack(f, limit))."""
  75     return format_list(extract_tb(tb, limit))
  76
  77 def extract_tb(tb, limit = None):
  78     """Return list of up to limit pre-processed entries from traceback.
  79
  80     This is useful for alternate formatting of stack traces.  If
  81     'limit' is omitted or None, all entries are extracted.  A
  82     pre-processed stack trace entry is a quadruple (filename, line
  83     number, function name, text) representing the information that is
  84     usually printed for a stack trace.  The text is a string with
  85     leading and trailing whitespace stripped; if the source is not
  86     available it is None.
  87     """
  88     if limit is None:
  89         if hasattr(sys, 'tracebacklimit'):
  90             limit = sys.tracebacklimit
  91     list = []
  92     n = 0
  93     while tb is not None and (limit is None or n < limit):
  94         f = tb.tb_frame
  95         lineno = tb_lineno(tb)
  96         co = f.f_code
  97         filename = co.co_filename
  98         name = co.co_name
  99         line = linecache.getline(filename, lineno)
 100         if line: line = line.strip()
 101         else: line = None
 102         list.append((filename, lineno, name, line))
 103         tb = tb.tb_next
 104         n = n+1
 105     return list
 106
 107
 108 def print_exception(etype, value, tb, limit=None, file=None):
 109     """Print exception up to 'limit' stack trace entries from 'tb' to 'file'.
 110
 111     This differs from print_tb() in the following ways: (1) if
 112     traceback is not None, it prints a header "Traceback (most recent
 113     call last):"; (2) it prints the exception type and value after the
 114     stack trace; (3) if type is SyntaxError and value has the
 115     appropriate format, it prints the line where the syntax error
 116     occurred with a caret on the next line indicating the approximate
 117     position of the error.
 118     """
 119     if not file:
 120         file = sys.stderr
 121     if tb:
 122         _print(file, 'Traceback (most recent call last):')
 123         print_tb(tb, limit, file)
 124     lines = format_exception_only(etype, value)
 125     for line in lines[:-1]:
 126         _print(file, line, ' ')
 127     _print(file, lines[-1], '')
 128
 129 def format_exception(etype, value, tb, limit = None):
 130     """Format a stack trace and the exception information.
 131
 132     The arguments have the same meaning as the corresponding arguments
 133     to print_exception().  The return value is a list of strings, each
 134     ending in a newline and some containing internal newlines.  When
 135     these lines are concatenated and printed, exactly the same text is
 136     printed as does print_exception().
 137     """
 138     if tb:
 139         list = ['Traceback (most recent call last):\n']
 140         list = list + format_tb(tb, limit)
 141     else:
 142         list = []
 143     list = list + format_exception_only(etype, value)
 144     return list
 145
 146 def format_exception_only(etype, value):
 147     """Format the exception part of a traceback.
 148
 149     The arguments are the exception type and value such as given by
 150     sys.last_type and sys.last_value. The return value is a list of
 151     strings, each ending in a newline.  Normally, the list contains a
 152     single string; however, for SyntaxError exceptions, it contains
 153     several lines that (when printed) display detailed information
 154     about where the syntax error occurred.  The message indicating
 155     which exception occurred is the always last string in the list.
 156     """
 157     list = []
 158     if type(etype) == types.ClassType:
 159         stype = etype.__name__
 160     else:
 161         stype = etype
 162     if value is None:
 163         list.append(str(stype) + '\n')
 164     else:
 165         if etype is SyntaxError:
 166             try:
 167                 msg, (filename, lineno, offset, line) = value
 168             except:
 169                 pass
 170             else:
 171                 if not filename: filename = "<string>"
 172                 list.append('  File "%s", line %d\n' %
 173                             (filename, lineno))
 174                 i = 0
 175                 while i < len(line) and line[i].isspace():
 176                     i = i+1
 177                 list.append('    %s\n' % line.strip())
 178                 if offset is not None:
 179                     s = '    '
 180                     for c in line[i:offset-1]:
 181                         if c.isspace():
 182                             s = s + c
 183                         else:
 184                             s = s + ' '
 185                     list.append('%s^\n' % s)
 186                 value = msg
 187         s = _some_str(value)
 188         if s:
 189             list.append('%s: %s\n' % (str(stype), s))
 190         else:
 191             list.append('%s\n' % str(stype))
 192     return list
 193
 194 def _some_str(value):
 195     try:
 196         return str(value)
 197     except:
 198         return '<unprintable %s object>' % type(value).__name__
 199
 200
 201 def print_exc(limit=None, file=None):
 202     """Shorthand for 'print_exception(sys.exc_type, sys.exc_value, sys.exc_traceback, limit, file)'.
 203     (In fact, it uses sys.exc_info() to retrieve the same information
 204     in a thread-safe way.)"""
 205     if not file:
 206         file = sys.stderr
 207     try:
 208         etype, value, tb = sys.exc_info()
 209         print_exception(etype, value, tb, limit, file)
 210     finally:
 211         etype = value = tb = None
 212
 213 def print_last(limit=None, file=None):
 214     """This is a shorthand for 'print_exception(sys.last_type,
 215     sys.last_value, sys.last_traceback, limit, file)'."""
 216     if not file:
 217         file = sys.stderr
 218     print_exception(sys.last_type, sys.last_value, sys.last_traceback,
 219                     limit, file)
 220
 221
 222 def print_stack(f=None, limit=None, file=None):
 223     """Print a stack trace from its invocation point.
 224
 225     The optional 'f' argument can be used to specify an alternate
 226     stack frame at which to start. The optional 'limit' and 'file'
 227     arguments have the same meaning as for print_exception().
 228     """
 229     if f is None:
 230         try:
 231             raise ZeroDivisionError
 232         except ZeroDivisionError:
 233             f = sys.exc_info()[2].tb_frame.f_back
 234     print_list(extract_stack(f, limit), file)
 235
 236 def format_stack(f=None, limit=None):
 237     """Shorthand for 'format_list(extract_stack(f, limit))'."""
 238     if f is None:
 239         try:
 240             raise ZeroDivisionError
 241         except ZeroDivisionError:
 242             f = sys.exc_info()[2].tb_frame.f_back
 243     return format_list(extract_stack(f, limit))
 244
 245 def extract_stack(f=None, limit = None):
 246     """Extract the raw traceback from the current stack frame.
 247
 248     The return value has the same format as for extract_tb().  The
 249     optional 'f' and 'limit' arguments have the same meaning as for
 250     print_stack().  Each item in the list is a quadruple (filename,
 251     line number, function name, text), and the entries are in order
 252     from oldest to newest stack frame.
 253     """
 254     if f is None:
 255         try:
 256             raise ZeroDivisionError
 257         except ZeroDivisionError:
 258             f = sys.exc_info()[2].tb_frame.f_back
 259     if limit is None:
 260         if hasattr(sys, 'tracebacklimit'):
 261             limit = sys.tracebacklimit
 262     list = []
 263     n = 0
 264     while f is not None and (limit is None or n < limit):
 265         lineno = f.f_lineno     # XXX Too bad if -O is used
 266         co = f.f_code
 267         filename = co.co_filename
 268         name = co.co_name
 269         line = linecache.getline(filename, lineno)
 270         if line: line = line.strip()
 271         else: line = None
 272         list.append((filename, lineno, name, line))
 273         f = f.f_back
 274         n = n+1
 275     list.reverse()
 276     return list
 277
 278 def tb_lineno(tb):
 279     """Calculate correct line number of traceback given in tb.
 280
 281     Even works with -O on.
 282     """
 283     # Coded by Marc-Andre Lemburg from the example of PyCode_Addr2Line()
 284     # in compile.c.
 285     # Revised version by Jim Hugunin to work with JPython too.
 286
 287     c = tb.tb_frame.f_code
 288     if not hasattr(c, 'co_lnotab'):
 289         return tb.tb_lineno
 290
 291     tab = c.co_lnotab
 292     line = c.co_firstlineno
 293     stopat = tb.tb_lasti
 294     addr = 0
 295     for i in range(0, len(tab), 2):
 296         addr = addr + ord(tab[i])
 297         if addr > stopat:
 298             break
 299         line = line + ord(tab[i+1])
 300     return line