Merged revisions 59333-59370 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r59343 | georg.brandl | 2007-12-05 08:02:47 +0100 (Wed, 05 Dec 2007) | 2 lines

  Fix typo.
........
  r59347 | christian.heimes | 2007-12-05 13:31:44 +0100 (Wed, 05 Dec 2007) | 1 line

  Fixed quoting and paths in the sqlite project file
........
  r59348 | christian.heimes | 2007-12-05 13:45:11 +0100 (Wed, 05 Dec 2007) | 1 line

  Fixed error in regrtest. I must have missed the spot.
........
  r59350 | christian.heimes | 2007-12-05 13:49:14 +0100 (Wed, 05 Dec 2007) | 1 line

  merge -r59315:59316 from py3k: Fix issue #1553: An errornous __length_hint__ can make list() raise a SystemError
........
  r59352 | christian.heimes | 2007-12-05 13:52:34 +0100 (Wed, 05 Dec 2007) | 1 line

  Added msg to Misc/NEWS
........
  r59354 | andrew.kuchling | 2007-12-05 14:27:20 +0100 (Wed, 05 Dec 2007) | 1 line

  Spelling fix
........
  r59356 | georg.brandl | 2007-12-05 18:56:50 +0100 (Wed, 05 Dec 2007) | 3 lines

  Add examples to csv, pprint and traceback docs.
  Written by Ross for GHOP.
........
  r59358 | raymond.hettinger | 2007-12-05 19:11:08 +0100 (Wed, 05 Dec 2007) | 1 line

  Error checking was too aggressive (reported by Chris Tismer)
........
  r59359 | georg.brandl | 2007-12-05 19:30:48 +0100 (Wed, 05 Dec 2007) | 2 lines

  Add examples to re docs. Written for GHOP by Dan Finnie.
........
  r59366 | georg.brandl | 2007-12-05 20:49:21 +0100 (Wed, 05 Dec 2007) | 2 lines

  Fix markup.
........
  r59367 | christian.heimes | 2007-12-05 20:57:54 +0100 (Wed, 05 Dec 2007) | 1 line

  Updated documentation and build_tkinter.py script
........
  r59368 | georg.brandl | 2007-12-05 21:03:57 +0100 (Wed, 05 Dec 2007) | 2 lines

  Another markup fix.
........
  r59369 | ronald.oussoren | 2007-12-05 21:07:36 +0100 (Wed, 05 Dec 2007) | 7 lines

  This "fixes" compilation issues for the Carbon._OSA module on OSX Leopard
  by purging bindings to OSA's debug API's. Those APIs we're completely
  unsupported on OSX 10.4 and are no longer available on OSX 10.5.

  Note that this patches a generated file. This is somewhat acceptable because
  regenerating the file is non-trivial and wouldn't use system headers anyway.
........
  r59370 | christian.heimes | 2007-12-05 21:10:38 +0100 (Wed, 05 Dec 2007) | 1 line

  Fixed bug #1557 by using popen.communicate() before popen.wait()
........

1 files changed, 123 insertions, 2 deletions

diff --git a/Doc/library/traceback.rst b/Doc/library/traceback.rst
index ca8aea3..179e04e 100644
--- a/Doc/library/traceback.rst
+++ b/Doc/library/traceback.rst
@@ -132,8 +132,8 @@ The module defines the following functions:
 
 .. _traceback-example:
 
-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
@@ -156,3 +156,124 @@ module. ::
    while True:
        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 "<doctest>", line 9, in <module>
+       lumberjack()
+   *** print_exception:
+   Traceback (most recent call last):
+     File "<doctest>", line 9, in <module>
+       lumberjack()
+     File "<doctest>", line 3, in lumberjack
+       bright_side_of_death()
+   IndexError: tuple index out of range
+   *** print_exc:
+   Traceback (most recent call last):
+     File "<doctest>", line 9, in <module>
+       lumberjack()
+     File "<doctest>", 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 "<doctest>", line 9, in <module>\n    lumberjack()\n',
+    '  File "<doctest>", line 3, in lumberjack\n    bright_side_of_death()\n',
+    '  File "<doctest>", line 6, in bright_side_of_death\n    return tuple()[0]\n',
+    'IndexError: tuple index out of range\n']
+   *** extract_tb:
+   [('<doctest>', 9, '<module>', 'lumberjack()'),
+    ('<doctest>', 3, 'lumberjack', 'bright_side_of_death()'),
+    ('<doctest>', 6, 'bright_side_of_death', 'return tuple()[0]')]
+   *** format_tb:
+   ['  File "<doctest>", line 9, in <module>\n    lumberjack()\n',
+    '  File "<doctest>", line 3, in lumberjack\n    bright_side_of_death()\n',
+    '  File "<doctest>", line 6, in bright_side_of_death\n    return tuple()[0]\n']
+   *** tb_lineno: 2
+   *** print_last:
+   Traceback (most recent call last):
+     File "<doctest>", line 9, in <module>
+       lumberjack()
+     File "<doctest>", 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 "<doctest>", line 10, in <module>
+       another_function()
+     File "<doctest>", line 3, in another_function
+       lumberstack()
+     File "<doctest>", line 6, in lumberstack
+       traceback.print_stack()
+   [('<doctest>', 10, '<module>', 'another_function()'),
+    ('<doctest>', 3, 'another_function', 'lumberstack()'),
+    ('<doctest>', 7, 'lumberstack', 'print repr(traceback.extract_stack())')]
+   ['  File "<doctest>", line 10, in <module>\n    another_function()\n',
+    '  File "<doctest>", line 3, in another_function\n    lumberstack()\n',
+    '  File "<doctest>", 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, '<module>', 'spam.eggs()'),
+   ...              ('eggs.py', 42, 'eggs', 'return "bacon"')])
+   ['  File "spam.py", line 3, in <module>\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']