cpython-lru_cache-weakref: Doc/library/traceback.rst annotate

annotate Doc/library/traceback.rst @ 54294:dba767bc3155 legacy-trunk

remove mention of old ctypes version

author	Benjamin Peterson <benjamin@python.org>
date	Sat, 23 May 2009 20:59:09 +0000
parents	9dc34ef22735
children	5dcc3619d6d1

rev	line source
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1 :mod:`traceback` --- Print or retrieve a stack traceback
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2 ========================================================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	4 .. module:: traceback
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	5 :synopsis: Print or retrieve a stack traceback.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	6
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	7
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	8 This module provides a standard interface to extract, format and print stack
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	9 traces of Python programs. It exactly mimics the behavior of the Python
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	10 interpreter when it prints a stack trace. This is useful when you want to print
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	11 stack traces under program control, such as in a "wrapper" around the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	12 interpreter.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	13
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	14 .. index:: object: traceback
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	15
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	16 The module uses traceback objects --- this is the object type that is stored in
53537 5d75203c8713 Make sys.xxx variable references into links, note that print_last only R. David Murray <rdmurray@bitdance.com> parents: 53506 diff changeset	17 the variables :data:`sys.exc_traceback` (deprecated) and :data:`sys.last_traceback` and
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	18 returned as the third item from :func:`sys.exc_info`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	19
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	20 The module defines the following functions:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	21
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	22
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	23 .. function:: print_tb(traceback[, limit[, file]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	24
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	25 Print up to limit stack trace entries from traceback. If limit is omitted
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	26 or ``None``, all entries are printed. If file is omitted or ``None``, the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	27 output goes to ``sys.stderr``; otherwise it should be an open file or file-like
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	28 object to receive the output.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	29
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	30
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	31 .. function:: print_exception(type, value, traceback[, limit[, file]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	32
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	33 Print exception information and up to limit stack trace entries from
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	34 traceback to file. This differs from :func:`print_tb` in the following ways:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	35 (1) if traceback is not ``None``, it prints a header ``Traceback (most recent
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	36 call last):``; (2) it prints the exception type and value after the stack
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	37 trace; (3) if type is :exc:`SyntaxError` and value has the appropriate
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	38 format, it prints the line where the syntax error occurred with a caret
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	39 indicating the approximate position of the error.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	40
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	41
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	42 .. function:: print_exc([limit[, file]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	43
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	44 This is a shorthand for ``print_exception(sys.exc_type, sys.exc_value,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	45 sys.exc_traceback, limit, file)``. (In fact, it uses :func:`sys.exc_info` to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	46 retrieve the same information in a thread-safe way instead of using the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	47 deprecated variables.)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	48
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	49
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	50 .. function:: format_exc([limit])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	51
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	52 This is like ``print_exc(limit)`` but returns a string instead of printing to a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	53 file.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	54
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	55 .. versionadded:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	56
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	57
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	58 .. function:: print_last([limit[, file]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	59
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	60 This is a shorthand for ``print_exception(sys.last_type, sys.last_value,
53537 5d75203c8713 Make sys.xxx variable references into links, note that print_last only R. David Murray <rdmurray@bitdance.com> parents: 53506 diff changeset	61 sys.last_traceback, limit, file)``. In general it will work only after
5d75203c8713 Make sys.xxx variable references into links, note that print_last only R. David Murray <rdmurray@bitdance.com> parents: 53506 diff changeset	62 an exception has reached an interactive prompt (see :data:`sys.last_type`).
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	63
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	64
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	65 .. function:: print_stack([f[, limit[, file]]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	66
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	67 This function prints a stack trace from its invocation point. The optional f
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	68 argument can be used to specify an alternate stack frame to start. The optional
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	69 limit and file arguments have the same meaning as for
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	70 :func:`print_exception`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	71
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	72
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	73 .. function:: extract_tb(traceback[, limit])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	74
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	75 Return a list of up to limit "pre-processed" stack trace entries extracted
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	76 from the traceback object traceback. It is useful for alternate formatting of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	77 stack traces. If limit is omitted or ``None``, all entries are extracted. A
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	78 "pre-processed" stack trace entry is a quadruple (filename, line number,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	79 function name, text) representing the information that is usually printed
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	80 for a stack trace. The text is a string with leading and trailing whitespace
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	81 stripped; if the source is not available it is ``None``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	82
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	83
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	84 .. function:: extract_stack([f[, limit]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	85
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	86 Extract the raw traceback from the current stack frame. The return value has
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	87 the same format as for :func:`extract_tb`. The optional f and limit
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	88 arguments have the same meaning as for :func:`print_stack`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	89
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	90
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	91 .. function:: format_list(list)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	92
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	93 Given a list of tuples as returned by :func:`extract_tb` or
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	94 :func:`extract_stack`, return a list of strings ready for printing. Each string
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	95 in the resulting list corresponds to the item with the same index in the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	96 argument list. Each string ends in a newline; the strings may contain internal
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	97 newlines as well, for those items whose source text line is not ``None``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	98
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	99
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	100 .. function:: format_exception_only(type, value)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	101
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	102 Format the exception part of a traceback. The arguments are the exception type
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	103 and value such as given by ``sys.last_type`` and ``sys.last_value``. The return
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	104 value is a list of strings, each ending in a newline. Normally, the list
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	105 contains a single string; however, for :exc:`SyntaxError` exceptions, it
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	106 contains several lines that (when printed) display detailed information about
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	107 where the syntax error occurred. The message indicating which exception
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	108 occurred is the always last string in the list.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	109
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	110
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	111 .. function:: format_exception(type, value, tb[, limit])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	112
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	113 Format a stack trace and the exception information. The arguments have the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	114 same meaning as the corresponding arguments to :func:`print_exception`. The
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	115 return value is a list of strings, each ending in a newline and some containing
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	116 internal newlines. When these lines are concatenated and printed, exactly the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	117 same text is printed as does :func:`print_exception`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	118
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	119
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	120 .. function:: format_tb(tb[, limit])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	121
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	122 A shorthand for ``format_list(extract_tb(tb, limit))``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	123
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	124
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	125 .. function:: format_stack([f[, limit]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	126
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	127 A shorthand for ``format_list(extract_stack(f, limit))``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	128
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	129
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	130 .. function:: tb_lineno(tb)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	131
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	132 This function returns the current line number set in the traceback object. This
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	133 function was necessary because in versions of Python prior to 2.3 when the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	134 :option:`-O` flag was passed to Python the ``tb.tb_lineno`` was not updated
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	135 correctly. This function has no use in versions past 2.3.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	136
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	137
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	138 .. _traceback-example:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	139
44176 40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	140 Traceback Examples
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	141 ------------------
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	142
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	143 This simple example implements a basic read-eval-print loop, similar to (but
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	144 less useful than) the standard Python interactive interpreter loop. For a more
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	145 complete implementation of the interpreter loop, refer to the :mod:`code`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	146 module. ::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	147
51745 9815da43a1ce revert r69777 since all the experts agree that extra import lines distract from the code Benjamin Peterson <benjamin@python.org> parents: 51742 diff changeset	148 import sys, traceback
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	149
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	150 def run_user_code(envdir):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	151 source = raw_input(">>> ")
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	152 try:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	153 exec source in envdir
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	154 except:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	155 print "Exception in user code:"
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	156 print '-'*60
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	157 traceback.print_exc(file=sys.stdout)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	158 print '-'*60
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	159
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	160 envdir = {}
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	161 while 1:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	162 run_user_code(envdir)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	163
44176 40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	164
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	165 The following example demonstrates the different ways to print and format the
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	166 exception and traceback::
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	167
51745 9815da43a1ce revert r69777 since all the experts agree that extra import lines distract from the code Benjamin Peterson <benjamin@python.org> parents: 51742 diff changeset	168 import sys, traceback
44176 40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	169
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	170 def lumberjack():
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	171 bright_side_of_death()
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 44176 diff changeset	172
44176 40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	173 def bright_side_of_death():
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	174 return tuple()[0]
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 44176 diff changeset	175
44176 40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	176 try:
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	177 lumberjack()
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	178 except:
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	179 exceptionType, exceptionValue, exceptionTraceback = sys.exc_info()
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	180 print "*** print_tb:"
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	181 traceback.print_tb(exceptionTraceback, limit=1, file=sys.stdout)
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	182 print "*** print_exception:"
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	183 traceback.print_exception(exceptionType, exceptionValue, exceptionTraceback,
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	184 limit=2, file=sys.stdout)
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	185 print "*** print_exc:"
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	186 traceback.print_exc()
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	187 print "*** format_exc, first and last line:"
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	188 formatted_lines = traceback.format_exc().splitlines()
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	189 print formatted_lines[0]
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	190 print formatted_lines[-1]
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	191 print "*** format_exception:"
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	192 print repr(traceback.format_exception(exceptionType, exceptionValue,
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	193 exceptionTraceback))
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	194 print "*** extract_tb:"
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	195 print repr(traceback.extract_tb(exceptionTraceback))
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	196 print "*** format_tb:"
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	197 print repr(traceback.format_tb(exceptionTraceback))
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	198 print "*** tb_lineno:", traceback.tb_lineno(exceptionTraceback)
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	199
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	200
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	201 The output for the example would look similar to this::
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	202
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	203 *** print_tb:
53537 5d75203c8713 Make sys.xxx variable references into links, note that print_last only R. David Murray <rdmurray@bitdance.com> parents: 53506 diff changeset	204 File "<doctest...>", line 10, in <module>
44176 40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	205 lumberjack()
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	206 *** print_exception:
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	207 Traceback (most recent call last):
53537 5d75203c8713 Make sys.xxx variable references into links, note that print_last only R. David Murray <rdmurray@bitdance.com> parents: 53506 diff changeset	208 File "<doctest...>", line 10, in <module>
44176 40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	209 lumberjack()
53537 5d75203c8713 Make sys.xxx variable references into links, note that print_last only R. David Murray <rdmurray@bitdance.com> parents: 53506 diff changeset	210 File "<doctest...>", line 4, in lumberjack
44176 40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	211 bright_side_of_death()
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	212 IndexError: tuple index out of range
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	213 *** print_exc:
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	214 Traceback (most recent call last):
53537 5d75203c8713 Make sys.xxx variable references into links, note that print_last only R. David Murray <rdmurray@bitdance.com> parents: 53506 diff changeset	215 File "<doctest...>", line 10, in <module>
44176 40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	216 lumberjack()
53537 5d75203c8713 Make sys.xxx variable references into links, note that print_last only R. David Murray <rdmurray@bitdance.com> parents: 53506 diff changeset	217 File "<doctest...>", line 4, in lumberjack
44176 40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	218 bright_side_of_death()
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	219 IndexError: tuple index out of range
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	220 *** format_exc, first and last line:
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	221 Traceback (most recent call last):
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	222 IndexError: tuple index out of range
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	223 *** format_exception:
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	224 ['Traceback (most recent call last):\n',
53537 5d75203c8713 Make sys.xxx variable references into links, note that print_last only R. David Murray <rdmurray@bitdance.com> parents: 53506 diff changeset	225 ' File "<doctest...>", line 10, in <module>\n lumberjack()\n',
5d75203c8713 Make sys.xxx variable references into links, note that print_last only R. David Murray <rdmurray@bitdance.com> parents: 53506 diff changeset	226 ' File "<doctest...>", line 4, in lumberjack\n bright_side_of_death()\n',
5d75203c8713 Make sys.xxx variable references into links, note that print_last only R. David Murray <rdmurray@bitdance.com> parents: 53506 diff changeset	227 ' File "<doctest...>", line 7, in bright_side_of_death\n return tuple()[0]\n',
44176 40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	228 'IndexError: tuple index out of range\n']
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	229 *** extract_tb:
53537 5d75203c8713 Make sys.xxx variable references into links, note that print_last only R. David Murray <rdmurray@bitdance.com> parents: 53506 diff changeset	230 [('<doctest...>', 10, '<module>', 'lumberjack()'),
5d75203c8713 Make sys.xxx variable references into links, note that print_last only R. David Murray <rdmurray@bitdance.com> parents: 53506 diff changeset	231 ('<doctest...>', 4, 'lumberjack', 'bright_side_of_death()'),
53577 9dc34ef22735 Remove spurious 'u'. R. David Murray <rdmurray@bitdance.com> parents: 53537 diff changeset	232 ('<doctest...>', 7, 'bright_side_of_death', 'return tuple()[0]')]
44176 40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	233 *** format_tb:
53537 5d75203c8713 Make sys.xxx variable references into links, note that print_last only R. David Murray <rdmurray@bitdance.com> parents: 53506 diff changeset	234 [' File "<doctest...>", line 10, in <module>\n lumberjack()\n',
5d75203c8713 Make sys.xxx variable references into links, note that print_last only R. David Murray <rdmurray@bitdance.com> parents: 53506 diff changeset	235 ' File "<doctest...>", line 4, in lumberjack\n bright_side_of_death()\n',
5d75203c8713 Make sys.xxx variable references into links, note that print_last only R. David Murray <rdmurray@bitdance.com> parents: 53506 diff changeset	236 ' File "<doctest...>", line 7, in bright_side_of_death\n return tuple()[0]\n']
5d75203c8713 Make sys.xxx variable references into links, note that print_last only R. David Murray <rdmurray@bitdance.com> parents: 53506 diff changeset	237 *** tb_lineno: 10
44176 40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	238
53577 9dc34ef22735 Remove spurious 'u'. R. David Murray <rdmurray@bitdance.com> parents: 53537 diff changeset	239
44176 40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	240 The following example shows the different ways to print and format the stack::
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	241
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	242 >>> import traceback
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	243 >>> def another_function():
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	244 ... lumberstack()
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 44176 diff changeset	245 ...
44176 40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	246 >>> def lumberstack():
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	247 ... traceback.print_stack()
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	248 ... print repr(traceback.extract_stack())
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	249 ... print repr(traceback.format_stack())
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 44176 diff changeset	250 ...
44176 40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	251 >>> another_function()
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	252 File "<doctest>", line 10, in <module>
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	253 another_function()
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	254 File "<doctest>", line 3, in another_function
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	255 lumberstack()
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	256 File "<doctest>", line 6, in lumberstack
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	257 traceback.print_stack()
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	258 [('<doctest>', 10, '<module>', 'another_function()'),
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	259 ('<doctest>', 3, 'another_function', 'lumberstack()'),
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	260 ('<doctest>', 7, 'lumberstack', 'print repr(traceback.extract_stack())')]
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	261 [' File "<doctest>", line 10, in <module>\n another_function()\n',
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	262 ' File "<doctest>", line 3, in another_function\n lumberstack()\n',
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	263 ' File "<doctest>", line 8, in lumberstack\n print repr(traceback.format_stack())\n']
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	264
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	265
53537 5d75203c8713 Make sys.xxx variable references into links, note that print_last only R. David Murray <rdmurray@bitdance.com> parents: 53506 diff changeset	266 This last example demonstrates the final few formatting functions:
5d75203c8713 Make sys.xxx variable references into links, note that print_last only R. David Murray <rdmurray@bitdance.com> parents: 53506 diff changeset	267
5d75203c8713 Make sys.xxx variable references into links, note that print_last only R. David Murray <rdmurray@bitdance.com> parents: 53506 diff changeset	268 .. doctest::
5d75203c8713 Make sys.xxx variable references into links, note that print_last only R. David Murray <rdmurray@bitdance.com> parents: 53506 diff changeset	269 :options: +NORMALIZE_WHITESPACE
44176 40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	270
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	271 >>> import traceback
53506 d05134a4f02c #5856: fix typo s in traceback example. Georg Brandl <georg@python.org> parents: 51745 diff changeset	272 >>> traceback.format_list([('spam.py', 3, '<module>', 'spam.eggs()'),
d05134a4f02c #5856: fix typo s in traceback example. Georg Brandl <georg@python.org> parents: 51745 diff changeset	273 ... ('eggs.py', 42, 'eggs', 'return "bacon"')])
44176 40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	274 [' File "spam.py", line 3, in <module>\n spam.eggs()\n',
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	275 ' File "eggs.py", line 42, in eggs\n return "bacon"\n']
53506 d05134a4f02c #5856: fix typo s in traceback example. Georg Brandl <georg@python.org> parents: 51745 diff changeset	276 >>> an_error = IndexError('tuple index out of range')
d05134a4f02c #5856: fix typo s in traceback example. Georg Brandl <georg@python.org> parents: 51745 diff changeset	277 >>> traceback.format_exception_only(type(an_error), an_error)
44176 40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42603 diff changeset	278 ['IndexError: tuple index out of range\n']

Mercurial > cpython-lru_cache-weakref

annotate Doc/library/traceback.rst @ 54294:dba767bc3155 legacy-trunk