Mercurial > cpython-lru_cache-weakref
annotate Doc/lib/libpprint.tex @ 6719:faebc1940432 legacy-trunk
Understand -Xlinker option.
| author | Guido van Rossum <guido@python.org> |
|---|---|
| date | Tue, 02 Dec 1997 20:38:11 +0000 |
| parents | a7ea74a27993 |
| children | adb300cbd566 |
| rev | line source |
|---|---|
|
5836
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
1 %% Author: Fred L. Drake, Jr. <fdrake@acm.org> |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
2 |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
3 \section{Standard module \sectcode{pprint}} |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
4 \stmodindex{pprint} |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
5 |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
6 The \code{pprint} module provides a capability to ``pretty-print'' |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
7 arbitrary Python data structures in a form which can be used as input |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
8 to the interpreter. If the formatted structures include objects which |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
9 are not fundamental Python types, the representation may not be |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
10 loadable. This may be the case if objects such as files, sockets, |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
11 classes, or instances are included, as well as many other builtin |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
12 objects which are not representable as Python constants. |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
13 |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
14 The formatted representation keeps objects on a single line if it can, |
| 5896 | 15 and breaks them onto multiple lines if they don't fit within the |
| 16 allowed width. Construct PrettyPrinter objects explicitly if you need | |
| 17 to adjust the width constraint. | |
|
5836
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
18 |
| 5896 | 19 The \code{pprint} module defines one class: |
|
5836
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
20 |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
21 \renewcommand{\indexsubitem}{(in module pprint)} |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
22 |
| 5896 | 23 % First the implementation class: |
|
5836
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
24 |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
25 \begin{funcdesc}{PrettyPrinter}{...} |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
26 Construct a PrettyPrinter instance. This constructor understands |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
27 several keyword parameters. An output stream may be set using the |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
28 \var{stream} keyword; the only method used on the stream object is the |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
29 file protocol's \code{write()} method. If not specified, the |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
30 PrettyPrinter adopts \code{sys.stdout}. Three additional parameters |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
31 may be used to control the formatted representation. The keywords are |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
32 \var{indent}, \var{depth}, and \var{width}. The amount of indentation |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
33 added for each recursive level is specified by \var{indent}; the |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
34 default is one. Other values can cause output to look a little odd, |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
35 but can make nesting easier to spot. The number of levels which may |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
36 be printed is controlled by \var{depth}; if the data structure being |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
37 printed is too deep, the next contained level is replaced by |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
38 \samp{...}. By default, there is no constraint on the depth of the |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
39 objects being formatted. The desired output width is constrained |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
40 using the \var{width} parameter; the default is eighty characters. If |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
41 a structure cannot be formatted within the constrained width, a best |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
42 effort will be made. |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
43 |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
44 \begin{verbatim} |
| 5896 | 45 >>> import pprint, sys |
|
5836
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
46 >>> stuff = sys.path[:] |
| 5896 | 47 >>> stuff.insert(0, stuff[:]) |
|
5836
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
48 >>> pp = pprint.PrettyPrinter(indent=4) |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
49 >>> pp.pprint(stuff) |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
50 [ [ '', |
| 5896 | 51 '/usr/local/lib/python1.5', |
| 52 '/usr/local/lib/python1.5/test', | |
| 53 '/usr/local/lib/python1.5/sunos5', | |
| 54 '/usr/local/lib/python1.5/sharedmodules', | |
| 55 '/usr/local/lib/python1.5/tkinter'], | |
|
5836
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
56 '', |
| 5896 | 57 '/usr/local/lib/python1.5', |
| 58 '/usr/local/lib/python1.5/test', | |
| 59 '/usr/local/lib/python1.5/sunos5', | |
| 60 '/usr/local/lib/python1.5/sharedmodules', | |
| 61 '/usr/local/lib/python1.5/tkinter'] | |
|
5836
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
62 >>> |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
63 >>> import parser |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
64 >>> tup = parser.ast2tuple( |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
65 ... parser.suite(open('pprint.py').read()))[1][1][1] |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
66 >>> pp = pprint.PrettyPrinter(depth=6) |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
67 >>> pp.pprint(tup) |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
68 (266, (267, (307, (287, (288, (...)))))) |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
69 \end{verbatim} |
| 5896 | 70 \end{funcdesc} |
| 71 | |
| 72 | |
| 73 % Now the derivative functions: | |
| 74 | |
| 75 The PrettyPrinter class supports several derivative functions: | |
| 76 | |
| 77 \begin{funcdesc}{pformat}{object} | |
| 78 Return the formatted representation of \var{object} as a string. The | |
| 79 default parameters for formatting are used. | |
| 80 \end{funcdesc} | |
| 81 | |
| 82 \begin{funcdesc}{pprint}{object\optional{, stream}} | |
| 83 Prints the formatted representation of \var{object} on \var{stream}, | |
| 84 followed by a newline. If \var{stream} is omitted, \code{sys.stdout} | |
| 85 is used. This may be used in the interactive interpreter instead of a | |
| 86 \code{print} command for inspecting values. The default parameters | |
| 87 for formatting are used. | |
| 88 | |
| 89 \begin{verbatim} | |
| 90 >>> stuff = sys.path[:] | |
| 91 >>> stuff.insert(0, stuff) | |
| 92 >>> pprint.pprint(stuff) | |
| 93 [<Recursion on list with id=869440>, | |
| 94 '', | |
| 95 '/usr/local/lib/python1.5', | |
| 96 '/usr/local/lib/python1.5/test', | |
| 97 '/usr/local/lib/python1.5/sunos5', | |
| 98 '/usr/local/lib/python1.5/sharedmodules', | |
| 99 '/usr/local/lib/python1.5/tkinter'] | |
| 100 \end{verbatim} | |
| 101 \end{funcdesc} | |
| 102 | |
| 103 \begin{funcdesc}{isreadable}{object} | |
| 104 Determine if the formatted representation of \var{object} is | |
| 105 ``readable,'' or can be used to reconstruct the value using | |
| 106 \code{eval()}. Note that this returns false for recursive objects. | |
| 107 | |
| 108 \begin{verbatim} | |
| 109 >>> pprint.isreadable(stuff) | |
| 110 0 | |
| 111 \end{verbatim} | |
| 112 \end{funcdesc} | |
| 113 | |
| 114 \begin{funcdesc}{isrecursive}{object} | |
| 115 Determine if \var{object} requires a recursive representation. | |
| 116 \end{funcdesc} | |
| 117 | |
| 118 | |
| 119 One more support function is also defined: | |
| 120 | |
| 121 \begin{funcdesc}{saferepr}{object} | |
| 122 Return a string representation of \var{object}, protected against | |
| 123 recursive data structures. If the representation of \var{object} | |
| 124 exposes a recursive entry, the recursive reference will be represented | |
|
6647
a7ea74a27993
Get rid of math mode in some places.
Guido van Rossum <guido@python.org>
parents:
5896
diff
changeset
|
125 as \code{<Recursion on \var{typename} with id=\var{number}>}. The |
| 5896 | 126 representation is not otherwise formatted. |
| 127 | |
| 128 \begin{verbatim} | |
| 129 >>> pprint.saferepr(stuff) | |
| 130 "[<Recursion on list with id=682968>, '', '/usr/local/lib/python1.4', '/usr/loca | |
| 131 l/lib/python1.4/test', '/usr/local/lib/python1.4/sunos5', '/usr/local/lib/python | |
| 132 1.4/sharedmodules', '/usr/local/lib/python1.4/tkinter']" | |
| 133 \end{verbatim} | |
| 134 \end{funcdesc} | |
|
5836
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
135 |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
136 |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
137 \subsection{PrettyPrinter Objects} |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
138 |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
139 PrettyPrinter instances (returned by \code{PrettyPrinter()} above) |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
140 have the following methods. |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
141 |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
142 \renewcommand{\indexsubitem}{(PrettyPrinter method)} |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
143 |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
144 \begin{funcdesc}{pformat}{object} |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
145 Return the formatted representation of \var{object}. This takes into |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
146 account the options passed to the PrettyPrinter constructor. |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
147 \end{funcdesc} |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
148 |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
149 \begin{funcdesc}{pprint}{object} |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
150 Print the formatted representation of \var{object} on the configured |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
151 stream, followed by a newline. |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
152 \end{funcdesc} |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
153 |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
154 The following methods provide the implementations for the |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
155 corresponding functions of the same names. Using these methods on an |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
156 instance is slightly more efficient since new PrettyPrinter objects |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
157 don't need to be created. |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
158 |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
159 \begin{funcdesc}{isreadable}{object} |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
160 Determine if the formatted representation of the object is |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
161 ``readable,'' or can be used to reconstruct the value using |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
162 \code{eval()}. Note that this returns false for recursive objects. |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
163 If the \var{depth} parameter of the PrettyPrinter is set and the |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
164 object is deeper than allowed, this returns false. |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
165 \end{funcdesc} |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
166 |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
167 \begin{funcdesc}{isrecursive}{object} |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
168 Determine if the object requires a recursive representation. |
|
3a798677506c
Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
169 \end{funcdesc} |
