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 file is None:
  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 file is None:
  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.tb_lineno
  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.tb_lineno
  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 file is None:
 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                 if line is not None:
 175                     i = 0
 176                     while i < len(line) and line[i].isspace():
 177                         i = i+1
 178                     list.append('    %s\n' % line.strip())
 179                     if offset is not None:
 180                         s = '    '
 181                         for c in line[i:offset-1]:
 182                             if c.isspace():
 183                                 s = s + c
 184                             else:
 185                                 s = s + ' '
 186                         list.append('%s^\n' % s)
 187                     value = msg
 188         s = _some_str(value)
 189         if s:
 190             list.append('%s: %s\n' % (str(stype), s))
 191         else:
 192             list.append('%s\n' % str(stype))
 193     return list
 194
 195 def _some_str(value):
 196     try:
 197         return str(value)
 198     except:
 199         return '<unprintable %s object>' % type(value).__name__
 200
 201
 202 def print_exc(limit=None, file=None):
 203     """Shorthand for 'print_exception(sys.exc_type, sys.exc_value, sys.exc_traceback, limit, file)'.
 204     (In fact, it uses sys.exc_info() to retrieve the same information
 205     in a thread-safe way.)"""
 206     if file is None:
 207         file = sys.stderr
 208     try:
 209         etype, value, tb = sys.exc_info()
 210         print_exception(etype, value, tb, limit, file)
 211     finally:
 212         etype = value = tb = None
 213
 214 def print_last(limit=None, file=None):
 215     """This is a shorthand for 'print_exception(sys.last_type,
 216     sys.last_value, sys.last_traceback, limit, file)'."""
 217     if file is None:
 218         file = sys.stderr
 219     print_exception(sys.last_type, sys.last_value, sys.last_traceback,
 220                     limit, file)
 221
 222
 223 def print_stack(f=None, limit=None, file=None):
 224     """Print a stack trace from its invocation point.
 225
 226     The optional 'f' argument can be used to specify an alternate
 227     stack frame at which to start. The optional 'limit' and 'file'
 228     arguments have the same meaning as for print_exception().
 229     """
 230     if f is None:
 231         try:
 232             raise ZeroDivisionError
 233         except ZeroDivisionError:
 234             f = sys.exc_info()[2].tb_frame.f_back
 235     print_list(extract_stack(f, limit), file)
 236
 237 def format_stack(f=None, limit=None):
 238     """Shorthand for 'format_list(extract_stack(f, limit))'."""
 239     if f is None:
 240         try:
 241             raise ZeroDivisionError
 242         except ZeroDivisionError:
 243             f = sys.exc_info()[2].tb_frame.f_back
 244     return format_list(extract_stack(f, limit))
 245
 246 def extract_stack(f=None, limit = None):
 247     """Extract the raw traceback from the current stack frame.
 248
 249     The return value has the same format as for extract_tb().  The
 250     optional 'f' and 'limit' arguments have the same meaning as for
 251     print_stack().  Each item in the list is a quadruple (filename,
 252     line number, function name, text), and the entries are in order
 253     from oldest to newest stack frame.
 254     """
 255     if f is None:
 256         try:
 257             raise ZeroDivisionError
 258         except ZeroDivisionError:
 259             f = sys.exc_info()[2].tb_frame.f_back
 260     if limit is None:
 261         if hasattr(sys, 'tracebacklimit'):
 262             limit = sys.tracebacklimit
 263     list = []
 264     n = 0
 265     while f is not None and (limit is None or n < limit):
 266         lineno = f.f_lineno
 267         co = f.f_code
 268         filename = co.co_filename
 269         name = co.co_name
 270         line = linecache.getline(filename, lineno)
 271         if line: line = line.strip()
 272         else: line = None
 273         list.append((filename, lineno, name, line))
 274         f = f.f_back
 275         n = n+1
 276     list.reverse()
 277     return list
 278
 279 def tb_lineno(tb):
 280     """Calculate correct line number of traceback given in tb.
 281
 282     Obsolete in 2.3.
 283     """
 284     return tb.tb_lineno