/Lib/traceback.py

  1"""Extract, format and print information about Python stack traces."""
  2
  3import linecache
  4import sys
  5import types
  6
  7__all__ = ['extract_stack', 'extract_tb', 'format_exception',
  8           'format_exception_only', 'format_list', 'format_stack',
  9           'format_tb', 'print_exc', 'format_exc', 'print_exception',
 10           'print_last', 'print_stack', 'print_tb', 'tb_lineno']
 11
 12def _print(file, str='', terminator='\n'):
 13    file.write(str+terminator)
 14
 15
 16def 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
 27def 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
 46def 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        linecache.checkcache(filename)
 69        line = linecache.getline(filename, lineno, f.f_globals)
 70        if line: _print(file, '    ' + line.strip())
 71        tb = tb.tb_next
 72        n = n+1
 73
 74def format_tb(tb, limit = None):
 75    """A shorthand for 'format_list(extract_stack(f, limit))."""
 76    return format_list(extract_tb(tb, limit))
 77
 78def extract_tb(tb, limit = None):
 79    """Return list of up to limit pre-processed entries from traceback.
 80
 81    This is useful for alternate formatting of stack traces.  If
 82    'limit' is omitted or None, all entries are extracted.  A
 83    pre-processed stack trace entry is a quadruple (filename, line
 84    number, function name, text) representing the information that is
 85    usually printed for a stack trace.  The text is a string with
 86    leading and trailing whitespace stripped; if the source is not
 87    available it is None.
 88    """
 89    if limit is None:
 90        if hasattr(sys, 'tracebacklimit'):
 91            limit = sys.tracebacklimit
 92    list = []
 93    n = 0
 94    while tb is not None and (limit is None or n < limit):
 95        f = tb.tb_frame
 96        lineno = tb.tb_lineno
 97        co = f.f_code
 98        filename = co.co_filename
 99        name = co.co_name
100        linecache.checkcache(filename)
101        line = linecache.getline(filename, lineno, f.f_globals)
102        if line: line = line.strip()
103        else: line = None
104        list.append((filename, lineno, name, line))
105        tb = tb.tb_next
106        n = n+1
107    return list
108
109
110def print_exception(etype, value, tb, limit=None, file=None):
111    """Print exception up to 'limit' stack trace entries from 'tb' to 'file'.
112
113    This differs from print_tb() in the following ways: (1) if
114    traceback is not None, it prints a header "Traceback (most recent
115    call last):"; (2) it prints the exception type and value after the
116    stack trace; (3) if type is SyntaxError and value has the
117    appropriate format, it prints the line where the syntax error
118    occurred with a caret on the next line indicating the approximate
119    position of the error.
120    """
121    if file is None:
122        file = sys.stderr
123    if tb:
124        _print(file, 'Traceback (most recent call last):')
125        print_tb(tb, limit, file)
126    lines = format_exception_only(etype, value)
127    for line in lines[:-1]:
128        _print(file, line, ' ')
129    _print(file, lines[-1], '')
130
131def format_exception(etype, value, tb, limit = None):
132    """Format a stack trace and the exception information.
133
134    The arguments have the same meaning as the corresponding arguments
135    to print_exception().  The return value is a list of strings, each
136    ending in a newline and some containing internal newlines.  When
137    these lines are concatenated and printed, exactly the same text is
138    printed as does print_exception().
139    """
140    if tb:
141        list = ['Traceback (most recent call last):\n']
142        list = list + format_tb(tb, limit)
143    else:
144        list = []
145    list = list + format_exception_only(etype, value)
146    return list
147
148def format_exception_only(etype, value):
149    """Format the exception part of a traceback.
150
151    The arguments are the exception type and value such as given by
152    sys.last_type and sys.last_value. The return value is a list of
153    strings, each ending in a newline.
154
155    Normally, the list contains a single string; however, for
156    SyntaxError exceptions, it contains several lines that (when
157    printed) display detailed information about where the syntax
158    error occurred.
159
160    The message indicating which exception occurred is always the last
161    string in the list.
162
163    """
164
165    # An instance should not have a meaningful value parameter, but
166    # sometimes does, particularly for string exceptions, such as
167    # >>> raise string1, string2  # deprecated
168    #
169    # Clear these out first because issubtype(string1, SyntaxError)
170    # would throw another exception and mask the original problem.
171    if (isinstance(etype, BaseException) or
172        isinstance(etype, types.InstanceType) or
173        etype is None or type(etype) is str):
174        return [_format_final_exc_line(etype, value)]
175
176    stype = etype.__name__
177
178    if not issubclass(etype, SyntaxError):
179        return [_format_final_exc_line(stype, value)]
180
181    # It was a syntax error; show exactly where the problem was found.
182    lines = []
183    try:
184        msg, (filename, lineno, offset, badline) = value.args
185    except Exception:
186        pass
187    else:
188        filename = filename or "<string>"
189        lines.append('  File "%s", line %d\n' % (filename, lineno))
190        if badline is not None:
191            lines.append('    %s\n' % badline.strip())
192            if offset is not None:
193                caretspace = badline[:offset].lstrip()
194                # non-space whitespace (likes tabs) must be kept for alignment
195                caretspace = ((c.isspace() and c or ' ') for c in caretspace)
196                # only three spaces to account for offset1 == pos 0
197                lines.append('   %s^\n' % ''.join(caretspace))
198            value = msg
199
200    lines.append(_format_final_exc_line(stype, value))
201    return lines
202
203def _format_final_exc_line(etype, value):
204    """Return a list of a single line -- normal case for format_exception_only"""
205    valuestr = _some_str(value)
206    if value is None or not valuestr:
207        line = "%s\n" % etype
208    else:
209        line = "%s: %s\n" % (etype, valuestr)
210    return line
211
212def _some_str(value):
213    try:
214        return str(value)
215    except:
216        return '<unprintable %s object>' % type(value).__name__
217
218
219def print_exc(limit=None, file=None):
220    """Shorthand for 'print_exception(sys.exc_type, sys.exc_value, sys.exc_traceback, limit, file)'.
221    (In fact, it uses sys.exc_info() to retrieve the same information
222    in a thread-safe way.)"""
223    if file is None:
224        file = sys.stderr
225    try:
226        etype, value, tb = sys.exc_info()
227        print_exception(etype, value, tb, limit, file)
228    finally:
229        etype = value = tb = None
230
231
232def format_exc(limit=None):
233    """Like print_exc() but return a string."""
234    try:
235        etype, value, tb = sys.exc_info()
236        return ''.join(format_exception(etype, value, tb, limit))
237    finally:
238        etype = value = tb = None
239
240
241def print_last(limit=None, file=None):
242    """This is a shorthand for 'print_exception(sys.last_type,
243    sys.last_value, sys.last_traceback, limit, file)'."""
244    if file is None:
245        file = sys.stderr
246    print_exception(sys.last_type, sys.last_value, sys.last_traceback,
247                    limit, file)
248
249
250def print_stack(f=None, limit=None, file=None):
251    """Print a stack trace from its invocation point.
252
253    The optional 'f' argument can be used to specify an alternate
254    stack frame at which to start. The optional 'limit' and 'file'
255    arguments have the same meaning as for print_exception().
256    """
257    if f is None:
258        try:
259            raise ZeroDivisionError
260        except ZeroDivisionError:
261            f = sys.exc_info()[2].tb_frame.f_back
262    print_list(extract_stack(f, limit), file)
263
264def format_stack(f=None, limit=None):
265    """Shorthand for 'format_list(extract_stack(f, limit))'."""
266    if f is None:
267        try:
268            raise ZeroDivisionError
269        except ZeroDivisionError:
270            f = sys.exc_info()[2].tb_frame.f_back
271    return format_list(extract_stack(f, limit))
272
273def extract_stack(f=None, limit = None):
274    """Extract the raw traceback from the current stack frame.
275
276    The return value has the same format as for extract_tb().  The
277    optional 'f' and 'limit' arguments have the same meaning as for
278    print_stack().  Each item in the list is a quadruple (filename,
279    line number, function name, text), and the entries are in order
280    from oldest to newest stack frame.
281    """
282    if f is None:
283        try:
284            raise ZeroDivisionError
285        except ZeroDivisionError:
286            f = sys.exc_info()[2].tb_frame.f_back
287    if limit is None:
288        if hasattr(sys, 'tracebacklimit'):
289            limit = sys.tracebacklimit
290    list = []
291    n = 0
292    while f is not None and (limit is None or n < limit):
293        lineno = f.f_lineno
294        co = f.f_code
295        filename = co.co_filename
296        name = co.co_name
297        linecache.checkcache(filename)
298        line = linecache.getline(filename, lineno, f.f_globals)
299        if line: line = line.strip()
300        else: line = None
301        list.append((filename, lineno, name, line))
302        f = f.f_back
303        n = n+1
304    list.reverse()
305    return list
306
307def tb_lineno(tb):
308    """Calculate correct line number of traceback given in tb.
309
310    Obsolete in 2.3.
311    """
312    return tb.tb_lineno