Lib/traceback.py

   1 """Extract, format and print information about Python stack traces."""
   2
   3 import linecache
   4 import sys
   5
   6 __all__ = ['extract_stack', 'extract_tb', 'format_exception',
   7            'format_exception_only', 'format_list', 'format_stack',
   8            'format_tb', 'print_exc', 'format_exc', 'print_exception',
   9            'print_last', 'print_stack', 'print_tb']
  10
  11 def _print(file, str='', terminator='\n'):
  12     file.write(str+terminator)
  13
  14
  15 def print_list(extracted_list, file=None):
  16     """Print the list of tuples as returned by extract_tb() or
  17     extract_stack() as a formatted stack trace to the given file."""
  18     if file is None:
  19         file = sys.stderr
  20     for filename, lineno, name, line in extracted_list:
  21         _print(file,
  22                '  File "%s", line %d, in %s' % (filename,lineno,name))
  23         if line:
  24             _print(file, '    %s' % line.strip())
  25
  26 def format_list(extracted_list):
  27     """Format a list of traceback entry tuples for printing.
  28
  29     Given a list of tuples as returned by extract_tb() or
  30     extract_stack(), return a list of strings ready for printing.
  31     Each string in the resulting list corresponds to the item with the
  32     same index in the argument list.  Each string ends in a newline;
  33     the strings may contain internal newlines as well, for those items
  34     whose source text line is not None.
  35     """
  36     list = []
  37     for filename, lineno, name, line in extracted_list:
  38         item = '  File "%s", line %d, in %s\n' % (filename,lineno,name)
  39         if line:
  40             item = item + '    %s\n' % line.strip()
  41         list.append(item)
  42     return list
  43
  44
  45 def print_tb(tb, limit=None, file=None):
  46     """Print up to 'limit' stack trace entries from the traceback 'tb'.
  47
  48     If 'limit' is omitted or None, all entries are printed.  If 'file'
  49     is omitted or None, the output goes to sys.stderr; otherwise
  50     'file' should be an open file or file-like object with a write()
  51     method.
  52     """
  53     if file is None:
  54         file = sys.stderr
  55     if limit is None:
  56         if hasattr(sys, 'tracebacklimit'):
  57             limit = sys.tracebacklimit
  58     n = 0
  59     while tb is not None and (limit is None or n < limit):
  60         f = tb.tb_frame
  61         lineno = tb.tb_lineno
  62         co = f.f_code
  63         filename = co.co_filename
  64         name = co.co_name
  65         _print(file,
  66                '  File "%s", line %d, in %s' % (filename, lineno, name))
  67         linecache.checkcache(filename)
  68         line = linecache.getline(filename, lineno, f.f_globals)
  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.tb_lineno
  96         co = f.f_code
  97         filename = co.co_filename
  98         name = co.co_name
  99         linecache.checkcache(filename)
 100         line = linecache.getline(filename, lineno, f.f_globals)
 101         if line: line = line.strip()
 102         else: line = None
 103         list.append((filename, lineno, name, line))
 104         tb = tb.tb_next
 105         n = n+1
 106     return list
 107
 108
 109 _cause_message = (
 110     "\nThe above exception was the direct cause "
 111     "of the following exception:\n")
 112
 113 _context_message = (
 114     "\nDuring handling of the above exception, "
 115     "another exception occurred:\n")
 116
 117 def _iter_chain(exc, custom_tb=None, seen=None):
 118     if seen is None:
 119         seen = set()
 120     seen.add(exc)
 121     its = []
 122     cause = exc.__cause__
 123     if cause is not None and cause not in seen:
 124         its.append(_iter_chain(cause, None, seen))
 125         its.append([(_cause_message, None)])
 126     else:
 127         context = exc.__context__
 128         if context is not None and context not in seen:
 129             its.append(_iter_chain(context, None, seen))
 130             its.append([(_context_message, None)])
 131     its.append([(exc, custom_tb or exc.__traceback__)])
 132     # itertools.chain is in an extension module and may be unavailable
 133     for it in its:
 134         for x in it:
 135             yield x
 136
 137
 138 def print_exception(etype, value, tb, limit=None, file=None, chain=True):
 139     """Print exception up to 'limit' stack trace entries from 'tb' to 'file'.
 140
 141     This differs from print_tb() in the following ways: (1) if
 142     traceback is not None, it prints a header "Traceback (most recent
 143     call last):"; (2) it prints the exception type and value after the
 144     stack trace; (3) if type is SyntaxError and value has the
 145     appropriate format, it prints the line where the syntax error
 146     occurred with a caret on the next line indicating the approximate
 147     position of the error.
 148     """
 149     if file is None:
 150         file = sys.stderr
 151     if chain:
 152         values = _iter_chain(value, tb)
 153     else:
 154         values = [(value, tb)]
 155     for value, tb in values:
 156         if isinstance(value, str):
 157             _print(file, value)
 158             continue
 159         if tb:
 160             _print(file, 'Traceback (most recent call last):')
 161             print_tb(tb, limit, file)
 162         lines = format_exception_only(type(value), value)
 163         for line in lines:
 164             _print(file, line, '')
 165
 166 def format_exception(etype, value, tb, limit=None, chain=True):
 167     """Format a stack trace and the exception information.
 168
 169     The arguments have the same meaning as the corresponding arguments
 170     to print_exception().  The return value is a list of strings, each
 171     ending in a newline and some containing internal newlines.  When
 172     these lines are concatenated and printed, exactly the same text is
 173     printed as does print_exception().
 174     """
 175     list = []
 176     if chain:
 177         values = _iter_chain(value, tb)
 178     else:
 179         values = [(value, tb)]
 180     for value, tb in values:
 181         if isinstance(value, str):
 182             list.append(value + '\n')
 183             continue
 184         if tb:
 185             list.append('Traceback (most recent call last):\n')
 186             list.extend(format_tb(tb, limit))
 187         list.extend(format_exception_only(type(value), value))
 188     return list
 189
 190 def format_exception_only(etype, value):
 191     """Format the exception part of a traceback.
 192
 193     The arguments are the exception type and value such as given by
 194     sys.last_type and sys.last_value. The return value is a list of
 195     strings, each ending in a newline.
 196
 197     Normally, the list contains a single string; however, for
 198     SyntaxError exceptions, it contains several lines that (when
 199     printed) display detailed information about where the syntax
 200     error occurred.
 201
 202     The message indicating which exception occurred is always the last
 203     string in the list.
 204
 205     """
 206     # Gracefully handle (the way Python 2.4 and earlier did) the case of
 207     # being called with (None, None).
 208     if etype is None:
 209         return [_format_final_exc_line(etype, value)]
 210
 211     stype = etype.__name__
 212     smod = etype.__module__
 213     if smod not in ("__main__", "builtins"):
 214         stype = smod + '.' + stype
 215
 216     if not issubclass(etype, SyntaxError):
 217         return [_format_final_exc_line(stype, value)]
 218
 219     # It was a syntax error; show exactly where the problem was found.
 220     lines = []
 221     filename = value.filename or "<string>"
 222     lineno = str(value.lineno) or '?'
 223     lines.append('  File "%s", line %s\n' % (filename, lineno))
 224     badline = value.text
 225     offset = value.offset
 226     if badline is not None:
 227         lines.append('    %s\n' % badline.strip())
 228         if offset is not None:
 229             caretspace = badline.rstrip('\n')[:offset].lstrip()
 230             # non-space whitespace (likes tabs) must be kept for alignment
 231             caretspace = ((c.isspace() and c or ' ') for c in caretspace)
 232             # only three spaces to account for offset1 == pos 0
 233             lines.append('   %s^\n' % ''.join(caretspace))
 234     msg = value.msg or "<no detail available>"
 235     lines.append("%s: %s\n" % (stype, msg))
 236     return lines
 237
 238 def _format_final_exc_line(etype, value):
 239     valuestr = _some_str(value)
 240     if value is None or not valuestr:
 241         line = "%s\n" % etype
 242     else:
 243         line = "%s: %s\n" % (etype, valuestr)
 244     return line
 245
 246 def _some_str(value):
 247     try:
 248         return str(value)
 249     except:
 250         return '<unprintable %s object>' % type(value).__name__
 251
 252
 253 def print_exc(limit=None, file=None, chain=True):
 254     """Shorthand for 'print_exception(*sys.exc_info(), limit, file)'."""
 255     if file is None:
 256         file = sys.stderr
 257     try:
 258         etype, value, tb = sys.exc_info()
 259         print_exception(etype, value, tb, limit, file, chain)
 260     finally:
 261         etype = value = tb = None
 262
 263
 264 def format_exc(limit=None, chain=True):
 265     """Like print_exc() but return a string."""
 266     try:
 267         etype, value, tb = sys.exc_info()
 268         return ''.join(
 269             format_exception(etype, value, tb, limit, chain))
 270     finally:
 271         etype = value = tb = None
 272
 273
 274 def print_last(limit=None, file=None, chain=True):
 275     """This is a shorthand for 'print_exception(sys.last_type,
 276     sys.last_value, sys.last_traceback, limit, file)'."""
 277     if not hasattr(sys, "last_type"):
 278         raise ValueError("no last exception")
 279     if file is None:
 280         file = sys.stderr
 281     print_exception(sys.last_type, sys.last_value, sys.last_traceback,
 282                     limit, file, chain)
 283
 284
 285 def print_stack(f=None, limit=None, file=None):
 286     """Print a stack trace from its invocation point.
 287
 288     The optional 'f' argument can be used to specify an alternate
 289     stack frame at which to start. The optional 'limit' and 'file'
 290     arguments have the same meaning as for print_exception().
 291     """
 292     if f is None:
 293         try:
 294             raise ZeroDivisionError
 295         except ZeroDivisionError:
 296             f = sys.exc_info()[2].tb_frame.f_back
 297     print_list(extract_stack(f, limit), file)
 298
 299 def format_stack(f=None, limit=None):
 300     """Shorthand for 'format_list(extract_stack(f, limit))'."""
 301     if f is None:
 302         try:
 303             raise ZeroDivisionError
 304         except ZeroDivisionError:
 305             f = sys.exc_info()[2].tb_frame.f_back
 306     return format_list(extract_stack(f, limit))
 307
 308 def extract_stack(f=None, limit=None):
 309     """Extract the raw traceback from the current stack frame.
 310
 311     The return value has the same format as for extract_tb().  The
 312     optional 'f' and 'limit' arguments have the same meaning as for
 313     print_stack().  Each item in the list is a quadruple (filename,
 314     line number, function name, text), and the entries are in order
 315     from oldest to newest stack frame.
 316     """
 317     if f is None:
 318         try:
 319             raise ZeroDivisionError
 320         except ZeroDivisionError:
 321             f = sys.exc_info()[2].tb_frame.f_back
 322     if limit is None:
 323         if hasattr(sys, 'tracebacklimit'):
 324             limit = sys.tracebacklimit
 325     list = []
 326     n = 0
 327     while f is not None and (limit is None or n < limit):
 328         lineno = f.f_lineno
 329         co = f.f_code
 330         filename = co.co_filename
 331         name = co.co_name
 332         linecache.checkcache(filename)
 333         line = linecache.getline(filename, lineno, f.f_globals)
 334         if line: line = line.strip()
 335         else: line = None
 336         list.append((filename, lineno, name, line))
 337         f = f.f_back
 338         n = n+1
 339     list.reverse()
 340     return list