diff options
Diffstat (limited to 'Doc/library/pprint.rst')
| -rw-r--r-- | Doc/library/pprint.rst | 213 |
1 files changed, 213 insertions, 0 deletions
diff --git a/Doc/library/pprint.rst b/Doc/library/pprint.rst new file mode 100644 index 0000000..3630176 --- /dev/null +++ b/Doc/library/pprint.rst @@ -0,0 +1,213 @@ + +:mod:`pprint` --- Data pretty printer +===================================== + +.. module:: pprint + :synopsis: Data pretty printer. +.. moduleauthor:: Fred L. Drake, Jr. <fdrake@acm.org> +.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org> + + +The :mod:`pprint` module provides a capability to "pretty-print" arbitrary +Python data structures in a form which can be used as input to the interpreter. +If the formatted structures include objects which are not fundamental Python +types, the representation may not be loadable. This may be the case if objects +such as files, sockets, classes, or instances are included, as well as many +other builtin objects which are not representable as Python constants. + +The formatted representation keeps objects on a single line if it can, and +breaks them onto multiple lines if they don't fit within the allowed width. +Construct :class:`PrettyPrinter` objects explicitly if you need to adjust the +width constraint. + +.. versionchanged:: 2.5 + Dictionaries are sorted by key before the display is computed; before 2.5, a + dictionary was sorted only if its display required more than one line, although + that wasn't documented. + +The :mod:`pprint` module defines one class: + +.. % First the implementation class: + + +.. class:: PrettyPrinter(...) + + Construct a :class:`PrettyPrinter` instance. This constructor understands + several keyword parameters. An output stream may be set using the *stream* + keyword; the only method used on the stream object is the file protocol's + :meth:`write` method. If not specified, the :class:`PrettyPrinter` adopts + ``sys.stdout``. Three additional parameters may be used to control the + formatted representation. The keywords are *indent*, *depth*, and *width*. The + amount of indentation added for each recursive level is specified by *indent*; + the default is one. Other values can cause output to look a little odd, but can + make nesting easier to spot. The number of levels which may be printed is + controlled by *depth*; if the data structure being printed is too deep, the next + contained level is replaced by ``...``. By default, there is no constraint on + the depth of the objects being formatted. The desired output width is + constrained using the *width* parameter; the default is 80 characters. If a + structure cannot be formatted within the constrained width, a best effort will + be made. :: + + >>> import pprint, sys + >>> stuff = sys.path[:] + >>> 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] + >>> pp = pprint.PrettyPrinter(depth=6) + >>> pp.pprint(tup) + (266, (267, (307, (287, (288, (...)))))) + +The :class:`PrettyPrinter` class supports several derivative functions: + +.. % Now the derivative functions: + + +.. function:: pformat(object[, indent[, width[, depth]]]) + + Return the formatted representation of *object* as a string. *indent*, *width* + and *depth* will be passed to the :class:`PrettyPrinter` constructor as + formatting parameters. + + .. versionchanged:: 2.4 + The parameters *indent*, *width* and *depth* were added. + + +.. function:: pprint(object[, stream[, indent[, width[, depth]]]]) + + Prints the formatted representation of *object* on *stream*, followed by a + newline. If *stream* is omitted, ``sys.stdout`` is used. This may be used in + the interactive interpreter instead of a :keyword:`print` statement for + inspecting values. *indent*, *width* and *depth* will be passed to the + :class:`PrettyPrinter` constructor as formatting parameters. :: + + >>> stuff = sys.path[:] + >>> stuff.insert(0, stuff) + >>> pprint.pprint(stuff) + [<Recursion on list with id=869440>, + '', + '/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'] + + .. versionchanged:: 2.4 + The parameters *indent*, *width* and *depth* were added. + + +.. function:: isreadable(object) + + .. index:: builtin: eval + + Determine if the formatted representation of *object* is "readable," or can be + used to reconstruct the value using :func:`eval`. This always returns ``False`` + for recursive objects. :: + + >>> pprint.isreadable(stuff) + False + + +.. function:: isrecursive(object) + + Determine if *object* requires a recursive representation. + +One more support function is also defined: + + +.. function:: saferepr(object) + + Return a string representation of *object*, protected against recursive data + structures. If the representation of *object* exposes a recursive entry, the + recursive reference will be represented as ``<Recursion on typename with + id=number>``. The representation is not otherwise formatted. + +.. % This example is outside the {funcdesc} to keep it from running over +.. % the right margin. + +:: + + >>> pprint.saferepr(stuff) + "[<Recursion on list with id=682968>, '', '/usr/local/lib/python1.5', '/usr/loca + l/lib/python1.5/test', '/usr/local/lib/python1.5/sunos5', '/usr/local/lib/python + 1.5/sharedmodules', '/usr/local/lib/python1.5/tkinter']" + + +.. _prettyprinter-objects: + +PrettyPrinter Objects +--------------------- + +:class:`PrettyPrinter` instances have the following methods: + + +.. method:: PrettyPrinter.pformat(object) + + Return the formatted representation of *object*. This takes into account the + options passed to the :class:`PrettyPrinter` constructor. + + +.. method:: PrettyPrinter.pprint(object) + + Print the formatted representation of *object* on the configured stream, + followed by a newline. + +The following methods provide the implementations for the corresponding +functions of the same names. Using these methods on an instance is slightly +more efficient since new :class:`PrettyPrinter` objects don't need to be +created. + + +.. method:: PrettyPrinter.isreadable(object) + + .. index:: builtin: eval + + Determine if the formatted representation of the object is "readable," or can be + used to reconstruct the value using :func:`eval`. Note that this returns + ``False`` for recursive objects. If the *depth* parameter of the + :class:`PrettyPrinter` is set and the object is deeper than allowed, this + returns ``False``. + + +.. method:: PrettyPrinter.isrecursive(object) + + Determine if the object requires a recursive representation. + +This method is provided as a hook to allow subclasses to modify the way objects +are converted to strings. The default implementation uses the internals of the +:func:`saferepr` implementation. + + +.. method:: PrettyPrinter.format(object, context, maxlevels, level) + + Returns three values: the formatted version of *object* as a string, a flag + indicating whether the result is readable, and a flag indicating whether + recursion was detected. The first argument is the object to be presented. The + second is a dictionary which contains the :func:`id` of objects that are part of + the current presentation context (direct and indirect containers for *object* + that are affecting the presentation) as the keys; if an object needs to be + presented which is already represented in *context*, the third return value + should be ``True``. Recursive calls to the :meth:`format` method should add + additional entries for containers to this dictionary. The third argument, + *maxlevels*, gives the requested limit to recursion; this will be ``0`` if there + is no requested limit. This argument should be passed unmodified to recursive + calls. The fourth argument, *level*, gives the current level; recursive calls + should be passed a value less than that of the current call. + + .. versionadded:: 2.3 + |