# 3.6 `traceback` -- Print or retrieve a stack traceback.

This module provides a standard interface to extract, format and print stack traces of Python programs. It exactly mimics the behavior of the Python interpreter when it prints a stack trace. This is useful when you want to print stack traces under program control, e.g. in a ``wrapper'' around the interpreter.

The module uses traceback objects -- this is the object type that is stored in the variables `sys.exc_traceback` and `sys.last_traceback` and returned as the third item from `sys.exc_info()`.

The module defines the following functions:

`print_tb` (traceback[, limit[, file]])
  Print up to limit stack trace entries from traceback. If limit is omitted or `None`, all entries are printed. If file is omitted or `None`, the output goes to `sys.stderr`; otherwise it should be an open file or file-like object to receive the output.

`print_exception` (type, value, traceback[, limit[, file]])
  Print exception information and up to limit stack trace entries from traceback to file. This differs from `print_tb()` in the following ways: (1) if traceback is not `None`, it prints a header "`Traceback (innermost last):`"; (2) it prints the exception type and value after the stack trace; (3) if type is `SyntaxError` and value has the appropriate format, it prints the line where the syntax error occurred with a caret indicating the approximate position of the error.

`print_exc` ([limit[, file]])
  This is a shorthand for ``print_exception(sys.exc_type,``sys.exc_value,` `sys.exc_traceback,` limit`,`file`)`'. (In fact, it uses `sys.exc_info()` to retrieve the same information in a thread-safe way.)

`print_last` ([limit[, file]])
  This is a shorthand for ``print_exception(sys.last_type,``sys.last_value,` `sys.last_traceback,` limit`,`file`)`'.

`print_stack` ([f[, limit[, file]]])
  This function prints a stack trace from its invocation point. The optional f argument can be used to specify an alternate stack frame to start. The optional limit and file arguments have the same meaning as for `print_exception()`.

`extract_tb` (traceback[, limit])
  Return a list of up to limit ``pre-processed'' stack trace entries extracted from the traceback object traceback. It is useful for alternate formatting of stack traces. If limit is omitted or `None`, all entries are extracted. A ``pre-processed'' stack trace entry is a quadruple (filename, line number, function name, text) representing the information that is usually printed for a stack trace. The text is a string with leading and trailing whitespace stripped; if the source is not available it is `None`.

`extract_stack` ([f[, limit]])
  Extract the raw traceback from the current stack frame. The return value has the same format as for `extract_tb()`. The optional f and limit arguments have the same meaning as for `print_stack()`.

`format_list` (list)
  Given a list of tuples as returned by `extract_tb()` or `extract_stack()`, return a list of strings ready for printing. Each string in the resulting list corresponds to the item with the same index in the argument list. Each string ends in a newline; the strings may contain internal newlines as well, for those items whose source text line is not `None`.

`format_exception_only` (type, value)
  Format the exception part of a traceback. The arguments are the exception type and value such as given by `sys.last_type` and `sys.last_value`. The return value is a list of strings, each ending in a newline. Normally, the list contains a single string; however, for `SyntaxError` exceptions, it contains several lines that (when printed) display detailed information about where the syntax error occurred. The message indicating which exception occurred is the always last string in the list.

`format_exception` (type, value, tb[, limit])
  Format a stack trace and the exception information. The arguments have the same meaning as the corresponding arguments to `print_exception()`. The return value is a list of strings, each ending in a newline and some containing internal newlines. When these lines are contatenated and printed, exactly the same text is printed as does `print_exception()`.

`format_tb` (tb[, limit])
  A shorthand for `format_list(extract_tb(tb, limit))`.

`format_stack` ([f[, limit]])
  A shorthand for `format_list(extract_stack(f, limit))`.

`tb_lineno` (tb)
  This function returns the current line number set in the traceback object. This is normally the same as the `tb.tb_lineno`field of the object, but when optimization is used (the -O flag) this field is not updated correctly; this function calculates the correct value.

A simple example follows:

      import sys, traceback

      def run_user_code(envdir):
          source = raw_input(">>> ")
          try:
              exec source in envdir
          except:
              print "Exception in user code:"
              print '-'*60
              traceback.print_exc(file=sys.stdout)
              print '-'*60

      envdir = {}
      while 1:
          run_user_code(envdir)