Add examples to csv, pprint and traceback docs.

Written by Ross for GHOP.

3 files changed, 189 insertions, 24 deletions

diff --git a/Doc/library/csv.rst b/Doc/library/csv.rst
index a46c7ba..1d63080 100644
--- a/Doc/library/csv.rst
+++ b/Doc/library/csv.rst
@@ -45,8 +45,6 @@ using the :class:`DictReader` and :class:`DictWriter` classes.
 
 .. seealso::
 
-   .. % \seemodule{array}{Arrays of uniformly types numeric values.}
-
    :pep:`305` - CSV File API
       The Python Enhancement Proposal which proposed this addition to Python.
 
@@ -77,6 +75,15 @@ The :mod:`csv` module defines the following functions:
    All data read are returned as strings.  No automatic data type conversion is
    performed.
 
+   A short usage example::
+ 
+      >>> import csv
+      >>> spamReader = csv.reader(open('eggs.csv'), delimiter=' ', quotechar='|')
+      >>> for row in spamReader:
+      ...     print ', '.join(row)
+      Spam, Spam, Spam, Spam, Spam, Baked Beans
+      Spam, Lovely Spam, Wonderful Spam
+
    .. versionchanged:: 2.5
       The parser is now stricter with respect to multi-line quoted fields. Previously,
       if a line ended within a quoted field without a terminating newline character, a
@@ -106,6 +113,14 @@ The :mod:`csv` module defines the following functions:
    CSV files without preprocessing the data returned from a ``cursor.fetch*`` call.
    All other non-string data are stringified with :func:`str` before being written.
 
+   A short usage example::
+
+      >>> import csv
+      >>> spamWriter = csv.writer(open('eggs.csv', 'w'), delimiter=' ',
+      ...                         quotechar='|', quoting=QUOTE_MINIMAL)
+      >>> spamWriter.writerow(['Spam'] * 5 + ['Baked Beans'])
+      >>> spamWriter.writerow(['Spam', 'Lovely Spam', 'Wonderful Spam'])
+
 
 .. function:: register_dialect(name[, dialect][, fmtparam])
 
diff --git a/Doc/library/pprint.rst b/Doc/library/pprint.rst
index 3630176..e9cd148 100644
--- a/Doc/library/pprint.rst
+++ b/Doc/library/pprint.rst
@@ -48,30 +48,23 @@ The :mod:`pprint` module defines one class:
    structure cannot be formatted within the constrained width, a best effort will
    be made. ::
 
-      >>> import pprint, sys
-      >>> stuff = sys.path[:]
+      >>> import pprint
+      >>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
       >>> stuff.insert(0, stuff[:])
       >>> pp = pprint.PrettyPrinter(indent=4)
       >>> pp.pprint(stuff)
-      [   [   '',
-              '/usr/local/lib/python1.5',
-              '/usr/local/lib/python1.5/test',
-              '/usr/local/lib/python1.5/sunos5',
-              '/usr/local/lib/python1.5/sharedmodules',
-              '/usr/local/lib/python1.5/tkinter'],
-          '',
-          '/usr/local/lib/python1.5',
-          '/usr/local/lib/python1.5/test',
-          '/usr/local/lib/python1.5/sunos5',
-          '/usr/local/lib/python1.5/sharedmodules',
-          '/usr/local/lib/python1.5/tkinter']
-      >>>
-      >>> import parser
-      >>> tup = parser.ast2tuple(
-      ...     parser.suite(open('pprint.py').read()))[1][1][1]
+      [   ['spam', 'eggs', 'lumberjack', 'knights', 'ni'],
+          'spam',
+          'eggs',
+          'lumberjack',
+          'knights',
+          'ni']
+      >>> tup = ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead',
+      ... ('parrot', ('fresh fruit',))))))))
       >>> pp = pprint.PrettyPrinter(depth=6)
       >>> pp.pprint(tup)
-      (266, (267, (307, (287, (288, (...))))))
+      ('spam',
+       ('eggs', ('lumberjack', ('knights', ('ni', ('dead', ('parrot', (...,))))))))
 
 The :class:`PrettyPrinter` class supports several derivative functions:
 
@@ -96,7 +89,8 @@ The :class:`PrettyPrinter` class supports several derivative functions:
    inspecting values.    *indent*, *width* and *depth* will be passed to the
    :class:`PrettyPrinter` constructor as formatting parameters. ::
 
-      >>> stuff = sys.path[:]
+      >>> import pprint
+      >>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
       >>> stuff.insert(0, stuff)
       >>> pprint.pprint(stuff)
       [<Recursion on list with id=869440>,
@@ -211,3 +205,38 @@ are converted to strings.  The default implementation uses the internals of the
 
    .. versionadded:: 2.3
 
+.. _pprint-example:
+
+pprint Example
+--------------
+
+This example demonstrates several uses of the :func:`pprint` function and its parameters.
+
+   >>> import pprint
+   >>> tup = ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead',
+   ... ('parrot', ('fresh fruit',))))))))
+   >>> stuff = ['a' * 10, tup, ['a' * 30, 'b' * 30], ['c' * 20, 'd' * 20]]
+   >>> pprint.pprint(stuff)
+   ['aaaaaaaaaa',
+    ('spam',
+     ('eggs',
+      ('lumberjack',
+       ('knights', ('ni', ('dead', ('parrot', ('fresh fruit',)))))))),
+    ['aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa', 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'],
+    ['cccccccccccccccccccc', 'dddddddddddddddddddd']]
+   >>> pprint.pprint(stuff, depth=3)
+   ['aaaaaaaaaa',
+    ('spam', ('eggs', ('lumberjack', (...)))),
+    ['aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa', 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'],
+    ['cccccccccccccccccccc', 'dddddddddddddddddddd']]
+   >>> pprint.pprint(stuff, width=60)
+   ['aaaaaaaaaa',
+    ('spam',
+     ('eggs',
+      ('lumberjack',
+       ('knights',
+        ('ni', ('dead', ('parrot', ('fresh fruit',)))))))),
+    ['aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
+     'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'],
+    ['cccccccccccccccccccc', 'dddddddddddddddddddd']]
+
diff --git a/Doc/library/traceback.rst b/Doc/library/traceback.rst
index d2ff1a8..d446339 100644
--- a/Doc/library/traceback.rst
+++ b/Doc/library/traceback.rst
@@ -137,8 +137,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
@@ -161,3 +161,124 @@ module. ::
    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 "<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']