From 722e1011c937ee6adb3fbb37c00fc58315ba0918 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 5 Dec 2007 17:56:50 +0000 Subject: [PATCH] Add examples to csv, pprint and traceback docs. Written by Ross for GHOP. --- Doc/library/csv.rst | 19 +++++- Doc/library/pprint.rst | 69 +++++++++++++++------ Doc/library/traceback.rst | 125 +++++++++++++++++++++++++++++++++++++- 3 files changed, 189 insertions(+), 24 deletions(-) diff --git a/Doc/library/csv.rst b/Doc/library/csv.rst index a46c7ba1680..1d6308080cc 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 36301765c8d..e9cd1480927 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) [, @@ -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 d2ff1a81dd5..d446339c705 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 "", 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']