Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame] | 1 | \section{\module{pprint} --- |
Fred Drake | f8ca7d8 | 2000-10-10 17:03:45 +0000 | [diff] [blame] | 2 | Data pretty printer} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 3 | |
Fred Drake | 2a2f1fe | 1999-02-18 21:10:32 +0000 | [diff] [blame] | 4 | \declaremodule{standard}{pprint} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 5 | \modulesynopsis{Data pretty printer.} |
Fred Drake | 2a2f1fe | 1999-02-18 21:10:32 +0000 | [diff] [blame] | 6 | \moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org} |
| 7 | \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 8 | |
Fred Drake | ee8d3ca | 1997-07-18 20:41:58 +0000 | [diff] [blame] | 9 | |
Fred Drake | 2c8aa65 | 1998-02-20 06:03:52 +0000 | [diff] [blame] | 10 | The \module{pprint} module provides a capability to ``pretty-print'' |
Fred Drake | ee8d3ca | 1997-07-18 20:41:58 +0000 | [diff] [blame] | 11 | arbitrary Python data structures in a form which can be used as input |
| 12 | to the interpreter. If the formatted structures include objects which |
| 13 | are not fundamental Python types, the representation may not be |
| 14 | loadable. This may be the case if objects such as files, sockets, |
| 15 | classes, or instances are included, as well as many other builtin |
| 16 | objects which are not representable as Python constants. |
| 17 | |
| 18 | The formatted representation keeps objects on a single line if it can, |
Fred Drake | 12d9eac | 1997-07-24 15:39:16 +0000 | [diff] [blame] | 19 | and breaks them onto multiple lines if they don't fit within the |
Fred Drake | 2c8aa65 | 1998-02-20 06:03:52 +0000 | [diff] [blame] | 20 | allowed width. Construct \class{PrettyPrinter} objects explicitly if |
| 21 | you need to adjust the width constraint. |
Fred Drake | ee8d3ca | 1997-07-18 20:41:58 +0000 | [diff] [blame] | 22 | |
Fred Drake | 2c8aa65 | 1998-02-20 06:03:52 +0000 | [diff] [blame] | 23 | The \module{pprint} module defines one class: |
Fred Drake | ee8d3ca | 1997-07-18 20:41:58 +0000 | [diff] [blame] | 24 | |
Fred Drake | ee8d3ca | 1997-07-18 20:41:58 +0000 | [diff] [blame] | 25 | |
Fred Drake | 12d9eac | 1997-07-24 15:39:16 +0000 | [diff] [blame] | 26 | % First the implementation class: |
Fred Drake | ee8d3ca | 1997-07-18 20:41:58 +0000 | [diff] [blame] | 27 | |
Fred Drake | 2c8aa65 | 1998-02-20 06:03:52 +0000 | [diff] [blame] | 28 | \begin{classdesc}{PrettyPrinter}{...} |
| 29 | Construct a \class{PrettyPrinter} instance. This constructor |
| 30 | understands several keyword parameters. An output stream may be set |
| 31 | using the \var{stream} keyword; the only method used on the stream |
| 32 | object is the file protocol's \method{write()} method. If not |
| 33 | specified, the \class{PrettyPrinter} adopts \code{sys.stdout}. Three |
| 34 | additional parameters may be used to control the formatted |
| 35 | representation. The keywords are \var{indent}, \var{depth}, and |
| 36 | \var{width}. The amount of indentation added for each recursive level |
| 37 | is specified by \var{indent}; the default is one. Other values can |
| 38 | cause output to look a little odd, but can make nesting easier to |
| 39 | spot. The number of levels which may be printed is controlled by |
| 40 | \var{depth}; if the data structure being printed is too deep, the next |
| 41 | contained level is replaced by \samp{...}. By default, there is no |
| 42 | constraint on the depth of the objects being formatted. The desired |
| 43 | output width is constrained using the \var{width} parameter; the |
| 44 | default is eighty characters. If a structure cannot be formatted |
| 45 | within the constrained width, a best effort will be made. |
Fred Drake | ee8d3ca | 1997-07-18 20:41:58 +0000 | [diff] [blame] | 46 | |
| 47 | \begin{verbatim} |
Fred Drake | 12d9eac | 1997-07-24 15:39:16 +0000 | [diff] [blame] | 48 | >>> import pprint, sys |
Fred Drake | ee8d3ca | 1997-07-18 20:41:58 +0000 | [diff] [blame] | 49 | >>> stuff = sys.path[:] |
Fred Drake | 12d9eac | 1997-07-24 15:39:16 +0000 | [diff] [blame] | 50 | >>> stuff.insert(0, stuff[:]) |
Fred Drake | ee8d3ca | 1997-07-18 20:41:58 +0000 | [diff] [blame] | 51 | >>> pp = pprint.PrettyPrinter(indent=4) |
| 52 | >>> pp.pprint(stuff) |
| 53 | [ [ '', |
Fred Drake | 12d9eac | 1997-07-24 15:39:16 +0000 | [diff] [blame] | 54 | '/usr/local/lib/python1.5', |
| 55 | '/usr/local/lib/python1.5/test', |
| 56 | '/usr/local/lib/python1.5/sunos5', |
| 57 | '/usr/local/lib/python1.5/sharedmodules', |
| 58 | '/usr/local/lib/python1.5/tkinter'], |
Fred Drake | ee8d3ca | 1997-07-18 20:41:58 +0000 | [diff] [blame] | 59 | '', |
Fred Drake | 12d9eac | 1997-07-24 15:39:16 +0000 | [diff] [blame] | 60 | '/usr/local/lib/python1.5', |
| 61 | '/usr/local/lib/python1.5/test', |
| 62 | '/usr/local/lib/python1.5/sunos5', |
| 63 | '/usr/local/lib/python1.5/sharedmodules', |
| 64 | '/usr/local/lib/python1.5/tkinter'] |
Fred Drake | ee8d3ca | 1997-07-18 20:41:58 +0000 | [diff] [blame] | 65 | >>> |
| 66 | >>> import parser |
| 67 | >>> tup = parser.ast2tuple( |
| 68 | ... parser.suite(open('pprint.py').read()))[1][1][1] |
| 69 | >>> pp = pprint.PrettyPrinter(depth=6) |
| 70 | >>> pp.pprint(tup) |
| 71 | (266, (267, (307, (287, (288, (...)))))) |
| 72 | \end{verbatim} |
Fred Drake | 2c8aa65 | 1998-02-20 06:03:52 +0000 | [diff] [blame] | 73 | \end{classdesc} |
Fred Drake | 12d9eac | 1997-07-24 15:39:16 +0000 | [diff] [blame] | 74 | |
| 75 | |
| 76 | % Now the derivative functions: |
| 77 | |
Fred Drake | 2c8aa65 | 1998-02-20 06:03:52 +0000 | [diff] [blame] | 78 | The \class{PrettyPrinter} class supports several derivative functions: |
Fred Drake | 12d9eac | 1997-07-24 15:39:16 +0000 | [diff] [blame] | 79 | |
Walter Dörwald | c8de458 | 2003-12-03 20:26:05 +0000 | [diff] [blame] | 80 | \begin{funcdesc}{pformat}{object\optional{, indent\optional{, |
| 81 | width\optional{, depth}}}} |
| 82 | Return the formatted representation of \var{object} as a string. \var{indent}, |
| 83 | \var{width} and \var{depth} will be passed to the \class{PrettyPrinter} |
| 84 | constructor as formatting parameters. |
| 85 | \versionchanged[The parameters \var{indent}, \var{width} and \var{depth} |
| 86 | were added]{2.4} |
Fred Drake | 12d9eac | 1997-07-24 15:39:16 +0000 | [diff] [blame] | 87 | \end{funcdesc} |
| 88 | |
Walter Dörwald | c8de458 | 2003-12-03 20:26:05 +0000 | [diff] [blame] | 89 | \begin{funcdesc}{pprint}{object\optional{, stream\optional{, |
| 90 | indent\optional{, width\optional{, depth}}}}} |
Fred Drake | 12d9eac | 1997-07-24 15:39:16 +0000 | [diff] [blame] | 91 | Prints the formatted representation of \var{object} on \var{stream}, |
| 92 | followed by a newline. If \var{stream} is omitted, \code{sys.stdout} |
| 93 | is used. This may be used in the interactive interpreter instead of a |
Walter Dörwald | c8de458 | 2003-12-03 20:26:05 +0000 | [diff] [blame] | 94 | \keyword{print} statement for inspecting values. \var{indent}, |
| 95 | \var{width} and \var{depth} will be passed to the \class{PrettyPrinter} |
| 96 | constructor as formatting parameters. |
Fred Drake | 12d9eac | 1997-07-24 15:39:16 +0000 | [diff] [blame] | 97 | |
| 98 | \begin{verbatim} |
| 99 | >>> stuff = sys.path[:] |
| 100 | >>> stuff.insert(0, stuff) |
| 101 | >>> pprint.pprint(stuff) |
| 102 | [<Recursion on list with id=869440>, |
| 103 | '', |
| 104 | '/usr/local/lib/python1.5', |
| 105 | '/usr/local/lib/python1.5/test', |
| 106 | '/usr/local/lib/python1.5/sunos5', |
| 107 | '/usr/local/lib/python1.5/sharedmodules', |
| 108 | '/usr/local/lib/python1.5/tkinter'] |
| 109 | \end{verbatim} |
Walter Dörwald | c8de458 | 2003-12-03 20:26:05 +0000 | [diff] [blame] | 110 | \versionchanged[The parameters \var{indent}, \var{width} and \var{depth} |
| 111 | were added]{2.4} |
Fred Drake | 12d9eac | 1997-07-24 15:39:16 +0000 | [diff] [blame] | 112 | \end{funcdesc} |
| 113 | |
| 114 | \begin{funcdesc}{isreadable}{object} |
| 115 | Determine if the formatted representation of \var{object} is |
| 116 | ``readable,'' or can be used to reconstruct the value using |
Fred Drake | 14c198b | 1998-04-03 07:11:32 +0000 | [diff] [blame] | 117 | \function{eval()}\bifuncindex{eval}. This always returns false for |
Fred Drake | 2c8aa65 | 1998-02-20 06:03:52 +0000 | [diff] [blame] | 118 | recursive objects. |
Fred Drake | 12d9eac | 1997-07-24 15:39:16 +0000 | [diff] [blame] | 119 | |
| 120 | \begin{verbatim} |
| 121 | >>> pprint.isreadable(stuff) |
Martin v. Löwis | ccabed3 | 2003-11-27 19:48:03 +0000 | [diff] [blame] | 122 | False |
Fred Drake | 12d9eac | 1997-07-24 15:39:16 +0000 | [diff] [blame] | 123 | \end{verbatim} |
| 124 | \end{funcdesc} |
| 125 | |
| 126 | \begin{funcdesc}{isrecursive}{object} |
| 127 | Determine if \var{object} requires a recursive representation. |
| 128 | \end{funcdesc} |
| 129 | |
| 130 | |
| 131 | One more support function is also defined: |
| 132 | |
| 133 | \begin{funcdesc}{saferepr}{object} |
| 134 | Return a string representation of \var{object}, protected against |
| 135 | recursive data structures. If the representation of \var{object} |
| 136 | exposes a recursive entry, the recursive reference will be represented |
Fred Drake | 2303d31 | 1997-12-17 14:07:25 +0000 | [diff] [blame] | 137 | as \samp{<Recursion on \var{typename} with id=\var{number}>}. The |
Fred Drake | 12d9eac | 1997-07-24 15:39:16 +0000 | [diff] [blame] | 138 | representation is not otherwise formatted. |
Fred Drake | b55f9d3 | 1998-03-08 07:03:27 +0000 | [diff] [blame] | 139 | \end{funcdesc} |
Fred Drake | 12d9eac | 1997-07-24 15:39:16 +0000 | [diff] [blame] | 140 | |
Fred Drake | b55f9d3 | 1998-03-08 07:03:27 +0000 | [diff] [blame] | 141 | % This example is outside the {funcdesc} to keep it from running over |
| 142 | % the right margin. |
Fred Drake | 12d9eac | 1997-07-24 15:39:16 +0000 | [diff] [blame] | 143 | \begin{verbatim} |
| 144 | >>> pprint.saferepr(stuff) |
Fred Drake | 14c198b | 1998-04-03 07:11:32 +0000 | [diff] [blame] | 145 | "[<Recursion on list with id=682968>, '', '/usr/local/lib/python1.5', '/usr/loca |
| 146 | l/lib/python1.5/test', '/usr/local/lib/python1.5/sunos5', '/usr/local/lib/python |
| 147 | 1.5/sharedmodules', '/usr/local/lib/python1.5/tkinter']" |
Fred Drake | 12d9eac | 1997-07-24 15:39:16 +0000 | [diff] [blame] | 148 | \end{verbatim} |
Fred Drake | ee8d3ca | 1997-07-18 20:41:58 +0000 | [diff] [blame] | 149 | |
| 150 | |
| 151 | \subsection{PrettyPrinter Objects} |
Fred Drake | 2c8aa65 | 1998-02-20 06:03:52 +0000 | [diff] [blame] | 152 | \label{PrettyPrinter Objects} |
Fred Drake | ee8d3ca | 1997-07-18 20:41:58 +0000 | [diff] [blame] | 153 | |
Fred Drake | b55f9d3 | 1998-03-08 07:03:27 +0000 | [diff] [blame] | 154 | \class{PrettyPrinter} instances have the following methods: |
Fred Drake | ee8d3ca | 1997-07-18 20:41:58 +0000 | [diff] [blame] | 155 | |
Fred Drake | ee8d3ca | 1997-07-18 20:41:58 +0000 | [diff] [blame] | 156 | |
Fred Drake | 8fe533e | 1998-03-27 05:27:08 +0000 | [diff] [blame] | 157 | \begin{methoddesc}{pformat}{object} |
Fred Drake | ee8d3ca | 1997-07-18 20:41:58 +0000 | [diff] [blame] | 158 | Return the formatted representation of \var{object}. This takes into |
Fred Drake | 8fe533e | 1998-03-27 05:27:08 +0000 | [diff] [blame] | 159 | Account the options passed to the \class{PrettyPrinter} constructor. |
| 160 | \end{methoddesc} |
Fred Drake | ee8d3ca | 1997-07-18 20:41:58 +0000 | [diff] [blame] | 161 | |
Fred Drake | 8fe533e | 1998-03-27 05:27:08 +0000 | [diff] [blame] | 162 | \begin{methoddesc}{pprint}{object} |
Fred Drake | ee8d3ca | 1997-07-18 20:41:58 +0000 | [diff] [blame] | 163 | Print the formatted representation of \var{object} on the configured |
| 164 | stream, followed by a newline. |
Fred Drake | 8fe533e | 1998-03-27 05:27:08 +0000 | [diff] [blame] | 165 | \end{methoddesc} |
Fred Drake | ee8d3ca | 1997-07-18 20:41:58 +0000 | [diff] [blame] | 166 | |
| 167 | The following methods provide the implementations for the |
| 168 | corresponding functions of the same names. Using these methods on an |
Fred Drake | 2c8aa65 | 1998-02-20 06:03:52 +0000 | [diff] [blame] | 169 | instance is slightly more efficient since new \class{PrettyPrinter} |
| 170 | objects don't need to be created. |
Fred Drake | ee8d3ca | 1997-07-18 20:41:58 +0000 | [diff] [blame] | 171 | |
Fred Drake | 8fe533e | 1998-03-27 05:27:08 +0000 | [diff] [blame] | 172 | \begin{methoddesc}{isreadable}{object} |
Fred Drake | ee8d3ca | 1997-07-18 20:41:58 +0000 | [diff] [blame] | 173 | Determine if the formatted representation of the object is |
| 174 | ``readable,'' or can be used to reconstruct the value using |
Fred Drake | 2c8aa65 | 1998-02-20 06:03:52 +0000 | [diff] [blame] | 175 | \function{eval()}\bifuncindex{eval}. Note that this returns false for |
| 176 | recursive objects. If the \var{depth} parameter of the |
| 177 | \class{PrettyPrinter} is set and the object is deeper than allowed, |
| 178 | this returns false. |
Fred Drake | 8fe533e | 1998-03-27 05:27:08 +0000 | [diff] [blame] | 179 | \end{methoddesc} |
Fred Drake | ee8d3ca | 1997-07-18 20:41:58 +0000 | [diff] [blame] | 180 | |
Fred Drake | 8fe533e | 1998-03-27 05:27:08 +0000 | [diff] [blame] | 181 | \begin{methoddesc}{isrecursive}{object} |
Fred Drake | ee8d3ca | 1997-07-18 20:41:58 +0000 | [diff] [blame] | 182 | Determine if the object requires a recursive representation. |
Fred Drake | 8fe533e | 1998-03-27 05:27:08 +0000 | [diff] [blame] | 183 | \end{methoddesc} |
Fred Drake | aee113d | 2002-04-02 05:08:35 +0000 | [diff] [blame] | 184 | |
| 185 | This method is provided as a hook to allow subclasses to modify the |
| 186 | way objects are converted to strings. The default implementation uses |
| 187 | the internals of the \function{saferepr()} implementation. |
| 188 | |
| 189 | \begin{methoddesc}{format}{object, context, maxlevels, level} |
| 190 | Returns three values: the formatted version of \var{object} as a |
| 191 | string, a flag indicating whether the result is readable, and a flag |
| 192 | indicating whether recursion was detected. The first argument is the |
| 193 | object to be presented. The second is a dictionary which contains the |
| 194 | \function{id()} of objects that are part of the current presentation |
| 195 | context (direct and indirect containers for \var{object} that are |
| 196 | affecting the presentation) as the keys; if an object needs to be |
| 197 | presented which is already represented in \var{context}, the third |
| 198 | return value should be true. Recursive calls to the \method{format()} |
| 199 | method should add additionaly entries for containers to this |
| 200 | dictionary. The fourth argument, \var{maxlevels}, gives the requested |
| 201 | limit to recursion; this will be \code{0} if there is no requested |
| 202 | limit. This argument should be passed unmodified to recursive calls. |
| 203 | The fourth argument, \var{level} gives the current level; recursive |
| 204 | calls should be passed a value less than that of the current call. |
| 205 | \versionadded{2.3} |
| 206 | \end{methoddesc} |