diff -r ffa851df0825 -r 2fb8b9db1c86 symbian-qemu-0.9.1-12/python-2.6.1/Doc/library/traceback.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/symbian-qemu-0.9.1-12/python-2.6.1/Doc/library/traceback.rst Fri Jul 31 15:01:17 2009 +0100 @@ -0,0 +1,284 @@ + +:mod:`traceback` --- Print or retrieve a stack traceback +======================================================== + +.. module:: traceback + :synopsis: 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, such as in a "wrapper" around the +interpreter. + +.. index:: object: traceback + +The module uses traceback objects --- this is the object type that is stored in +the variables ``sys.exc_traceback`` (deprecated) and ``sys.last_traceback`` and +returned as the third item from :func:`sys.exc_info`. + +The module defines the following functions: + + +.. function:: 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. + + +.. function:: print_exception(type, value, traceback[, limit[, file]]) + + Print exception information and up to *limit* stack trace entries from + *traceback* to *file*. This differs from :func:`print_tb` in the following ways: + (1) if *traceback* is not ``None``, it prints a header ``Traceback (most recent + call last):``; (2) it prints the exception *type* and *value* after the stack + trace; (3) if *type* is :exc:`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. + + +.. function:: 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 :func:`sys.exc_info` to + retrieve the same information in a thread-safe way instead of using the + deprecated variables.) + + +.. function:: format_exc([limit]) + + This is like ``print_exc(limit)`` but returns a string instead of printing to a + file. + + .. versionadded:: 2.4 + + +.. function:: print_last([limit[, file]]) + + This is a shorthand for ``print_exception(sys.last_type, sys.last_value, + sys.last_traceback, limit, file)``. + + +.. function:: 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 + :func:`print_exception`. + + +.. function:: 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``. + + +.. function:: extract_stack([f[, limit]]) + + Extract the raw traceback from the current stack frame. The return value has + the same format as for :func:`extract_tb`. The optional *f* and *limit* + arguments have the same meaning as for :func:`print_stack`. + + +.. function:: format_list(list) + + Given a list of tuples as returned by :func:`extract_tb` or + :func:`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``. + + +.. function:: 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 :exc:`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. + + +.. function:: 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 :func:`print_exception`. The + return value is a list of strings, each ending in a newline and some containing + internal newlines. When these lines are concatenated and printed, exactly the + same text is printed as does :func:`print_exception`. + + +.. function:: format_tb(tb[, limit]) + + A shorthand for ``format_list(extract_tb(tb, limit))``. + + +.. function:: format_stack([f[, limit]]) + + A shorthand for ``format_list(extract_stack(f, limit))``. + + +.. function:: tb_lineno(tb) + + This function returns the current line number set in the traceback object. This + function was necessary because in versions of Python prior to 2.3 when the + :option:`-O` flag was passed to Python the ``tb.tb_lineno`` was not updated + correctly. This function has no use in versions past 2.3. + + +.. _traceback-example: + +Traceback Examples +------------------ + +This simple example implements a basic read-eval-print loop, similar to (but +less useful than) the standard Python interactive interpreter loop. For a more +complete implementation of the interpreter loop, refer to the :mod:`code` +module. :: + + 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) + + +The following example demonstrates the different ways to print and format the +exception and traceback:: + + import sys, traceback + + def lumberjack(): + bright_side_of_death() + + def bright_side_of_death(): + return tuple()[0] + + try: + lumberjack() + except: + exceptionType, exceptionValue, exceptionTraceback = sys.exc_info() + print "*** print_tb:" + traceback.print_tb(exceptionTraceback, limit=1, file=sys.stdout) + print "*** print_exception:" + traceback.print_exception(exceptionType, exceptionValue, exceptionTraceback, + limit=2, file=sys.stdout) + print "*** print_exc:" + traceback.print_exc() + print "*** format_exc, first and last line:" + formatted_lines = traceback.format_exc().splitlines() + print formatted_lines[0] + print formatted_lines[-1] + print "*** format_exception:" + print repr(traceback.format_exception(exceptionType, exceptionValue, + exceptionTraceback)) + print "*** extract_tb:" + print repr(traceback.extract_tb(exceptionTraceback)) + print "*** format_tb:" + print repr(traceback.format_tb(exceptionTraceback)) + print "*** tb_lineno:", traceback.tb_lineno(exceptionTraceback) + print "*** print_last:" + traceback.print_last() + + +The output for the example would look similar to this:: + + *** print_tb: + File "", line 9, in + lumberjack() + *** print_exception: + Traceback (most recent call last): + File "", line 9, in + lumberjack() + File "", line 3, in lumberjack + bright_side_of_death() + IndexError: tuple index out of range + *** print_exc: + Traceback (most recent call last): + File "", line 9, in + lumberjack() + File "", line 3, in lumberjack + bright_side_of_death() + IndexError: tuple index out of range + *** format_exc, first and last line: + Traceback (most recent call last): + IndexError: tuple index out of range + *** format_exception: + ['Traceback (most recent call last):\n', + ' File "", line 9, in \n lumberjack()\n', + ' File "", line 3, in lumberjack\n bright_side_of_death()\n', + ' File "", line 6, in bright_side_of_death\n return tuple()[0]\n', + 'IndexError: tuple index out of range\n'] + *** extract_tb: + [('', 9, '', 'lumberjack()'), + ('', 3, 'lumberjack', 'bright_side_of_death()'), + ('', 6, 'bright_side_of_death', 'return tuple()[0]')] + *** format_tb: + [' File "", line 9, in \n lumberjack()\n', + ' File "", line 3, in lumberjack\n bright_side_of_death()\n', + ' File "", line 6, in bright_side_of_death\n return tuple()[0]\n'] + *** tb_lineno: 2 + *** print_last: + Traceback (most recent call last): + File "", line 9, in + lumberjack() + File "", line 3, in lumberjack + bright_side_of_death() + IndexError: tuple index out of range + + +The following example shows the different ways to print and format the stack:: + + >>> import traceback + >>> def another_function(): + ... lumberstack() + ... + >>> def lumberstack(): + ... traceback.print_stack() + ... print repr(traceback.extract_stack()) + ... print repr(traceback.format_stack()) + ... + >>> another_function() + File "", line 10, in + another_function() + File "", line 3, in another_function + lumberstack() + File "", line 6, in lumberstack + traceback.print_stack() + [('', 10, '', 'another_function()'), + ('', 3, 'another_function', 'lumberstack()'), + ('', 7, 'lumberstack', 'print repr(traceback.extract_stack())')] + [' File "", line 10, in \n another_function()\n', + ' File "", line 3, in another_function\n lumberstack()\n', + ' File "", line 8, in lumberstack\n print repr(traceback.format_stack())\n'] + + +This last example demonstrates the final few formatting functions:: + + >>> import traceback + >>> format_list([('spam.py', 3, '', 'spam.eggs()'), + ... ('eggs.py', 42, 'eggs', 'return "bacon"')]) + [' File "spam.py", line 3, in \n spam.eggs()\n', + ' File "eggs.py", line 42, in eggs\n return "bacon"\n'] + >>> theError = IndexError('tuple indx out of range') + >>> traceback.format_exception_only(type(theError), theError) + ['IndexError: tuple index out of range\n']