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

annotate Doc/library/pprint.rst @ 58925:eecf1bef052d 2.6

Merged revisions 78207 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r78207 | ezio.melotti | 2010-02-17 01:26:09 +0200 (Wed, 17 Feb 2010) | 1 line #7930: fix stripid ........

author	Ezio Melotti <ezio.melotti@gmail.com>
date	Tue, 16 Feb 2010 23:29:44 +0000
parents	3e15a07a32fa
children	8838c56b6952

rev	line source
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2 :mod:`pprint` --- Data pretty printer
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	3 =====================================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	4
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	5 .. module:: pprint
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	6 :synopsis: Data pretty printer.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	7 .. moduleauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	8 .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	9
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	10
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	11 The :mod:`pprint` module provides a capability to "pretty-print" arbitrary
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	12 Python data structures in a form which can be used as input to the interpreter.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	13 If the formatted structures include objects which are not fundamental Python
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	14 types, the representation may not be loadable. This may be the case if objects
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	15 such as files, sockets, classes, or instances are included, as well as many
56818 3e15a07a32fa Merged revisions 74209 via svnmerge from Georg Brandl <georg@python.org> parents: 47797 diff changeset	16 other built-in objects which are not representable as Python constants.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	17
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	18 The formatted representation keeps objects on a single line if it can, and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	19 breaks them onto multiple lines if they don't fit within the allowed width.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	20 Construct :class:`PrettyPrinter` objects explicitly if you need to adjust the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	21 width constraint.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	22
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	23 .. versionchanged:: 2.5
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	24 Dictionaries are sorted by key before the display is computed; before 2.5, a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	25 dictionary was sorted only if its display required more than one line, although
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	26 that wasn't documented.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	27
44882 6bd4849b5458 Let pprint() support sets and frozensets (suggested by David Mertz). Raymond Hettinger <python@rcn.com> parents: 44383 diff changeset	28 .. versionchanged:: 2.6
6bd4849b5458 Let pprint() support sets and frozensets (suggested by David Mertz). Raymond Hettinger <python@rcn.com> parents: 44383 diff changeset	29 Added support for :class:`set` and :class:`frozenset`.
6bd4849b5458 Let pprint() support sets and frozensets (suggested by David Mertz). Raymond Hettinger <python@rcn.com> parents: 44383 diff changeset	30
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	31 The :mod:`pprint` module defines one class:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	32
44383 3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 44176 diff changeset	33 .. First the implementation class:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	34
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	35
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	36 .. class:: PrettyPrinter(...)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	37
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	38 Construct a :class:`PrettyPrinter` instance. This constructor understands
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	39 several keyword parameters. An output stream may be set using the stream
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	40 keyword; the only method used on the stream object is the file protocol's
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	41 :meth:`write` method. If not specified, the :class:`PrettyPrinter` adopts
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	42 ``sys.stdout``. Three additional parameters may be used to control the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	43 formatted representation. The keywords are indent, depth, and width. The
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	44 amount of indentation added for each recursive level is specified by indent;
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	45 the default is one. Other values can cause output to look a little odd, but can
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	46 make nesting easier to spot. The number of levels which may be printed is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	47 controlled by depth; if the data structure being printed is too deep, the next
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	48 contained level is replaced by ``...``. By default, there is no constraint on
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	49 the depth of the objects being formatted. The desired output width is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	50 constrained using the width parameter; the default is 80 characters. If a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	51 structure cannot be formatted within the constrained width, a best effort will
46006 f97785c7de9b Make more doctests in pprint docs testable. Georg Brandl <georg@python.org> parents: 44882 diff changeset	52 be made.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	53
44176 40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	54 >>> import pprint
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	55 >>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	56 >>> stuff.insert(0, stuff[:])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	57 >>> pp = pprint.PrettyPrinter(indent=4)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	58 >>> pp.pprint(stuff)
47797 016166b7b976 Fixed issue #2888. Now the behaviour of pprint when working with nested Facundo Batista <facundobatista@gmail.com> parents: 46947 diff changeset	59 [ ['spam', 'eggs', 'lumberjack', 'knights', 'ni'],
44176 40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	60 'spam',
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	61 'eggs',
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	62 'lumberjack',
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	63 'knights',
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	64 'ni']
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	65 >>> tup = ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead',
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	66 ... ('parrot', ('fresh fruit',))))))))
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	67 >>> pp = pprint.PrettyPrinter(depth=6)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	68 >>> pp.pprint(tup)
46947 07a53bb82baa #1713041: fix pprint's handling of maximum depth. Georg Brandl <georg@python.org> parents: 46006 diff changeset	69 ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead', (...)))))))
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	70
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	71 The :class:`PrettyPrinter` class supports several derivative functions:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	72
44383 3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 44176 diff changeset	73 .. Now the derivative functions:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	74
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	75 .. function:: pformat(object[, indent[, width[, depth]]])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	76
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	77 Return the formatted representation of object as a string. indent, width
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	78 and depth will be passed to the :class:`PrettyPrinter` constructor as
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	79 formatting parameters.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	80
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	81 .. versionchanged:: 2.4
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	82 The parameters indent, width and depth were added.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	83
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	84
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	85 .. function:: pprint(object[, stream[, indent[, width[, depth]]]])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	86
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	87 Prints the formatted representation of object on stream, followed by a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	88 newline. If stream is omitted, ``sys.stdout`` is used. This may be used in
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	89 the interactive interpreter instead of a :keyword:`print` statement for
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	90 inspecting values. indent, width and depth will be passed to the
46006 f97785c7de9b Make more doctests in pprint docs testable. Georg Brandl <georg@python.org> parents: 44882 diff changeset	91 :class:`PrettyPrinter` constructor as formatting parameters.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	92
44176 40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	93 >>> import pprint
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	94 >>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	95 >>> stuff.insert(0, stuff)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	96 >>> pprint.pprint(stuff)
46006 f97785c7de9b Make more doctests in pprint docs testable. Georg Brandl <georg@python.org> parents: 44882 diff changeset	97 [<Recursion on list with id=...>,
f97785c7de9b Make more doctests in pprint docs testable. Georg Brandl <georg@python.org> parents: 44882 diff changeset	98 'spam',
f97785c7de9b Make more doctests in pprint docs testable. Georg Brandl <georg@python.org> parents: 44882 diff changeset	99 'eggs',
f97785c7de9b Make more doctests in pprint docs testable. Georg Brandl <georg@python.org> parents: 44882 diff changeset	100 'lumberjack',
f97785c7de9b Make more doctests in pprint docs testable. Georg Brandl <georg@python.org> parents: 44882 diff changeset	101 'knights',
f97785c7de9b Make more doctests in pprint docs testable. Georg Brandl <georg@python.org> parents: 44882 diff changeset	102 'ni']
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	103
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	104 .. versionchanged:: 2.4
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	105 The parameters indent, width and depth were added.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	106
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	107
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	108 .. function:: isreadable(object)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	109
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	110 .. index:: builtin: eval
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	111
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	112 Determine if the formatted representation of object is "readable," or can be
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	113 used to reconstruct the value using :func:`eval`. This always returns ``False``
46006 f97785c7de9b Make more doctests in pprint docs testable. Georg Brandl <georg@python.org> parents: 44882 diff changeset	114 for recursive objects.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	115
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	116 >>> pprint.isreadable(stuff)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	117 False
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	118
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	119
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	120 .. function:: isrecursive(object)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	121
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	122 Determine if object requires a recursive representation.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	123
46006 f97785c7de9b Make more doctests in pprint docs testable. Georg Brandl <georg@python.org> parents: 44882 diff changeset	124
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	125 One more support function is also defined:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	126
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	127 .. function:: saferepr(object)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	128
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	129 Return a string representation of object, protected against recursive data
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	130 structures. If the representation of object exposes a recursive entry, the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	131 recursive reference will be represented as ``<Recursion on typename with
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	132 id=number>``. The representation is not otherwise formatted.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	133
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	134 >>> pprint.saferepr(stuff)
46006 f97785c7de9b Make more doctests in pprint docs testable. Georg Brandl <georg@python.org> parents: 44882 diff changeset	135 "[<Recursion on list with id=...>, 'spam', 'eggs', 'lumberjack', 'knights', 'ni']"
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	136
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	137
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	138 .. _prettyprinter-objects:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	139
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	140 PrettyPrinter Objects
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	141 ---------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	142
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	143 :class:`PrettyPrinter` instances have the following methods:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	144
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	145
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	146 .. method:: PrettyPrinter.pformat(object)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	147
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	148 Return the formatted representation of object. This takes into account the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	149 options passed to the :class:`PrettyPrinter` constructor.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	150
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	151
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	152 .. method:: PrettyPrinter.pprint(object)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	153
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	154 Print the formatted representation of object on the configured stream,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	155 followed by a newline.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	156
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	157 The following methods provide the implementations for the corresponding
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	158 functions of the same names. Using these methods on an instance is slightly
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	159 more efficient since new :class:`PrettyPrinter` objects don't need to be
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	160 created.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	161
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	162
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	163 .. method:: PrettyPrinter.isreadable(object)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	164
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	165 .. index:: builtin: eval
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	166
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	167 Determine if the formatted representation of the object is "readable," or can be
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	168 used to reconstruct the value using :func:`eval`. Note that this returns
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	169 ``False`` for recursive objects. If the depth parameter of the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	170 :class:`PrettyPrinter` is set and the object is deeper than allowed, this
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	171 returns ``False``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	172
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	173
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	174 .. method:: PrettyPrinter.isrecursive(object)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	175
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	176 Determine if the object requires a recursive representation.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	177
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	178 This method is provided as a hook to allow subclasses to modify the way objects
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	179 are converted to strings. The default implementation uses the internals of the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	180 :func:`saferepr` implementation.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	181
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	182
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	183 .. method:: PrettyPrinter.format(object, context, maxlevels, level)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	184
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	185 Returns three values: the formatted version of object as a string, a flag
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	186 indicating whether the result is readable, and a flag indicating whether
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	187 recursion was detected. The first argument is the object to be presented. The
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	188 second is a dictionary which contains the :func:`id` of objects that are part of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	189 the current presentation context (direct and indirect containers for object
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	190 that are affecting the presentation) as the keys; if an object needs to be
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	191 presented which is already represented in context, the third return value
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	192 should be ``True``. Recursive calls to the :meth:`format` method should add
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	193 additional entries for containers to this dictionary. The third argument,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	194 maxlevels, gives the requested limit to recursion; this will be ``0`` if there
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	195 is no requested limit. This argument should be passed unmodified to recursive
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	196 calls. The fourth argument, level, gives the current level; recursive calls
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	197 should be passed a value less than that of the current call.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	198
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	199 .. versionadded:: 2.3
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	200
44176 40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	201 .. _pprint-example:
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	202
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	203 pprint Example
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	204 --------------
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	205
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	206 This example demonstrates several uses of the :func:`pprint` function and its parameters.
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	207
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	208 >>> import pprint
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	209 >>> tup = ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead',
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	210 ... ('parrot', ('fresh fruit',))))))))
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	211 >>> stuff = ['a' * 10, tup, ['a' * 30, 'b' * 30], ['c' * 20, 'd' * 20]]
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	212 >>> pprint.pprint(stuff)
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	213 ['aaaaaaaaaa',
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	214 ('spam',
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	215 ('eggs',
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	216 ('lumberjack',
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	217 ('knights', ('ni', ('dead', ('parrot', ('fresh fruit',)))))))),
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	218 ['aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa', 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'],
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	219 ['cccccccccccccccccccc', 'dddddddddddddddddddd']]
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	220 >>> pprint.pprint(stuff, depth=3)
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	221 ['aaaaaaaaaa',
46947 07a53bb82baa #1713041: fix pprint's handling of maximum depth. Georg Brandl <georg@python.org> parents: 46006 diff changeset	222 ('spam', ('eggs', (...))),
44176 40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	223 ['aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa', 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'],
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	224 ['cccccccccccccccccccc', 'dddddddddddddddddddd']]
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	225 >>> pprint.pprint(stuff, width=60)
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	226 ['aaaaaaaaaa',
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	227 ('spam',
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	228 ('eggs',
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	229 ('lumberjack',
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	230 ('knights',
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	231 ('ni', ('dead', ('parrot', ('fresh fruit',)))))))),
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	232 ['aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	233 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'],
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	234 ['cccccccccccccccccccc', 'dddddddddddddddddddd']]
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	235

Mercurial > cpython-lru_cache-weakref

annotate Doc/library/pprint.rst @ 58925:eecf1bef052d 2.6