Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libpprint.tex @ 36118:044d35ca3424 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
fixed one more typo
author Fredrik Lundh <fredrik@pythonware.com>
date Sun, 25 Dec 2005 12:05:42 +0000
parents 76741e73bb64
children 2eb8be0f8731
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
8918
acfffe14628e New section header style.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
1 \section{\module{pprint} ---
15142
563dee598d3a Fixed lots of small nits caught by Ka-Ping Yee <ping@lfw.org>.
Fred Drake <fdrake@acm.org>
parents: 10239
diff changeset
2 Data pretty printer}
10239
c1befdbd64e5 Record module & documentation author.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
3
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
4 \declaremodule{standard}{pprint}
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
5 \modulesynopsis{Data pretty printer.}
10239
c1befdbd64e5 Record module & documentation author.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
6 \moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
c1befdbd64e5 Record module & documentation author.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
7 \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
8
5836
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
9
7424
11e9337cda3d Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
10 The \module{pprint} module provides a capability to ``pretty-print''
5836
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
11 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
12 to the interpreter. If the formatted structures include objects which
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
13 are not fundamental Python types, the representation may not be
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
14 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
15 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
16 objects which are not representable as Python constants.
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
17
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
18 The formatted representation keeps objects on a single line if it can,
5896
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
19 and breaks them onto multiple lines if they don't fit within the
7424
11e9337cda3d Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
20 allowed width. Construct \class{PrettyPrinter} objects explicitly if
11e9337cda3d Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
21 you need to adjust the width constraint.
5836
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
22
7424
11e9337cda3d Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
23 The \module{pprint} module defines one 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
5896
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
26 % First the implementation class:
5836
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
27
7424
11e9337cda3d Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
28 \begin{classdesc}{PrettyPrinter}{...}
11e9337cda3d Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
29 Construct a \class{PrettyPrinter} instance. This constructor
11e9337cda3d Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
30 understands several keyword parameters. An output stream may be set
11e9337cda3d Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
31 using the \var{stream} keyword; the only method used on the stream
11e9337cda3d Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
32 object is the file protocol's \method{write()} method. If not
11e9337cda3d Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
33 specified, the \class{PrettyPrinter} adopts \code{sys.stdout}. Three
11e9337cda3d Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
34 additional parameters may be used to control the formatted
11e9337cda3d Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
35 representation. The keywords are \var{indent}, \var{depth}, and
11e9337cda3d Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
36 \var{width}. The amount of indentation added for each recursive level
11e9337cda3d Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
37 is specified by \var{indent}; the default is one. Other values can
11e9337cda3d Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
38 cause output to look a little odd, but can make nesting easier to
11e9337cda3d Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
39 spot. The number of levels which may be printed is controlled by
11e9337cda3d Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
40 \var{depth}; if the data structure being printed is too deep, the next
11e9337cda3d Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
41 contained level is replaced by \samp{...}. By default, there is no
11e9337cda3d Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
42 constraint on the depth of the objects being formatted. The desired
11e9337cda3d Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
43 output width is constrained using the \var{width} parameter; the
11e9337cda3d Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
44 default is eighty characters. If a structure cannot be formatted
11e9337cda3d Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
45 within the constrained width, a best effort will be made.
5836
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
46
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
47 \begin{verbatim}
5896
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
48 >>> import pprint, sys
5836
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
49 >>> stuff = sys.path[:]
5896
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
50 >>> stuff.insert(0, stuff[:])
5836
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
51 >>> pp = pprint.PrettyPrinter(indent=4)
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
52 >>> pp.pprint(stuff)
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
53 [ [ '',
5896
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
54 '/usr/local/lib/python1.5',
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
55 '/usr/local/lib/python1.5/test',
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
56 '/usr/local/lib/python1.5/sunos5',
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
57 '/usr/local/lib/python1.5/sharedmodules',
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
58 '/usr/local/lib/python1.5/tkinter'],
5836
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
59 '',
5896
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
60 '/usr/local/lib/python1.5',
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
61 '/usr/local/lib/python1.5/test',
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
62 '/usr/local/lib/python1.5/sunos5',
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
63 '/usr/local/lib/python1.5/sharedmodules',
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
64 '/usr/local/lib/python1.5/tkinter']
5836
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
65 >>>
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
66 >>> import parser
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
67 >>> tup = parser.ast2tuple(
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
68 ... parser.suite(open('pprint.py').read()))[1][1][1]
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
69 >>> pp = pprint.PrettyPrinter(depth=6)
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
70 >>> pp.pprint(tup)
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
71 (266, (267, (307, (287, (288, (...))))))
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
72 \end{verbatim}
7424
11e9337cda3d Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
73 \end{classdesc}
5896
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
74
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
75
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
76 % Now the derivative functions:
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
77
7424
11e9337cda3d Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
78 The \class{PrettyPrinter} class supports several derivative functions:
5896
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
79
31085
a2f6c6a67f24 Add parameters indent, width and depth to pprint.pprint() and pprint.pformat()
Walter Dörwald <walter@livinglogic.de>
parents: 31029
diff changeset
80 \begin{funcdesc}{pformat}{object\optional{, indent\optional{,
a2f6c6a67f24 Add parameters indent, width and depth to pprint.pprint() and pprint.pformat()
Walter Dörwald <walter@livinglogic.de>
parents: 31029
diff changeset
81 width\optional{, depth}}}}
a2f6c6a67f24 Add parameters indent, width and depth to pprint.pprint() and pprint.pformat()
Walter Dörwald <walter@livinglogic.de>
parents: 31029
diff changeset
82 Return the formatted representation of \var{object} as a string. \var{indent},
a2f6c6a67f24 Add parameters indent, width and depth to pprint.pprint() and pprint.pformat()
Walter Dörwald <walter@livinglogic.de>
parents: 31029
diff changeset
83 \var{width} and \var{depth} will be passed to the \class{PrettyPrinter}
a2f6c6a67f24 Add parameters indent, width and depth to pprint.pprint() and pprint.pformat()
Walter Dörwald <walter@livinglogic.de>
parents: 31029
diff changeset
84 constructor as formatting parameters.
a2f6c6a67f24 Add parameters indent, width and depth to pprint.pprint() and pprint.pformat()
Walter Dörwald <walter@livinglogic.de>
parents: 31029
diff changeset
85 \versionchanged[The parameters \var{indent}, \var{width} and \var{depth}
a2f6c6a67f24 Add parameters indent, width and depth to pprint.pprint() and pprint.pformat()
Walter Dörwald <walter@livinglogic.de>
parents: 31029
diff changeset
86 were added]{2.4}
5896
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
87 \end{funcdesc}
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
88
31085
a2f6c6a67f24 Add parameters indent, width and depth to pprint.pprint() and pprint.pformat()
Walter Dörwald <walter@livinglogic.de>
parents: 31029
diff changeset
89 \begin{funcdesc}{pprint}{object\optional{, stream\optional{,
a2f6c6a67f24 Add parameters indent, width and depth to pprint.pprint() and pprint.pformat()
Walter Dörwald <walter@livinglogic.de>
parents: 31029
diff changeset
90 indent\optional{, width\optional{, depth}}}}}
5896
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
91 Prints the formatted representation of \var{object} on \var{stream},
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
92 followed by a newline. If \var{stream} is omitted, \code{sys.stdout}
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
93 is used. This may be used in the interactive interpreter instead of a
31085
a2f6c6a67f24 Add parameters indent, width and depth to pprint.pprint() and pprint.pformat()
Walter Dörwald <walter@livinglogic.de>
parents: 31029
diff changeset
94 \keyword{print} statement for inspecting values. \var{indent},
a2f6c6a67f24 Add parameters indent, width and depth to pprint.pprint() and pprint.pformat()
Walter Dörwald <walter@livinglogic.de>
parents: 31029
diff changeset
95 \var{width} and \var{depth} will be passed to the \class{PrettyPrinter}
a2f6c6a67f24 Add parameters indent, width and depth to pprint.pprint() and pprint.pformat()
Walter Dörwald <walter@livinglogic.de>
parents: 31029
diff changeset
96 constructor as formatting parameters.
5896
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
97
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
98 \begin{verbatim}
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
99 >>> stuff = sys.path[:]
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
100 >>> stuff.insert(0, stuff)
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
101 >>> pprint.pprint(stuff)
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
102 [<Recursion on list with id=869440>,
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
103 '',
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
104 '/usr/local/lib/python1.5',
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
105 '/usr/local/lib/python1.5/test',
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
106 '/usr/local/lib/python1.5/sunos5',
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
107 '/usr/local/lib/python1.5/sharedmodules',
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
108 '/usr/local/lib/python1.5/tkinter']
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
109 \end{verbatim}
31085
a2f6c6a67f24 Add parameters indent, width and depth to pprint.pprint() and pprint.pformat()
Walter Dörwald <walter@livinglogic.de>
parents: 31029
diff changeset
110 \versionchanged[The parameters \var{indent}, \var{width} and \var{depth}
a2f6c6a67f24 Add parameters indent, width and depth to pprint.pprint() and pprint.pformat()
Walter Dörwald <walter@livinglogic.de>
parents: 31029
diff changeset
111 were added]{2.4}
5896
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
112 \end{funcdesc}
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
113
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
114 \begin{funcdesc}{isreadable}{object}
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
115 Determine if the formatted representation of \var{object} is
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
116 ``readable,'' or can be used to reconstruct the value using
7829
e2fb25784530 Talk about some minor nits...
Fred Drake <fdrake@acm.org>
parents: 7768
diff changeset
117 \function{eval()}\bifuncindex{eval}. This always returns false for
7424
11e9337cda3d Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
118 recursive objects.
5896
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
119
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
120 \begin{verbatim}
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
121 >>> pprint.isreadable(stuff)
31029
ce07118ee5d2 Patch #849350: Update to document bool return values. Backported to 2.3.
Martin v. Löwis <martin@v.loewis.de>
parents: 22766
diff changeset
122 False
5896
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
123 \end{verbatim}
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
124 \end{funcdesc}
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
125
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
126 \begin{funcdesc}{isrecursive}{object}
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
127 Determine if \var{object} requires a recursive representation.
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
128 \end{funcdesc}
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
129
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
130
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
131 One more support function is also defined:
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
132
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
133 \begin{funcdesc}{saferepr}{object}
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
134 Return a string representation of \var{object}, protected against
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
135 recursive data structures. If the representation of \var{object}
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
136 exposes a recursive entry, the recursive reference will be represented
6901
adb300cbd566 Make the word "Module" in the section header start with an upper-case "M".
Fred Drake <fdrake@acm.org>
parents: 6647
diff changeset
137 as \samp{<Recursion on \var{typename} with id=\var{number}>}. The
5896
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
138 representation is not otherwise formatted.
7608
893a32095222 Small nits.
Fred Drake <fdrake@acm.org>
parents: 7424
diff changeset
139 \end{funcdesc}
5896
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
140
7608
893a32095222 Small nits.
Fred Drake <fdrake@acm.org>
parents: 7424
diff changeset
141 % This example is outside the {funcdesc} to keep it from running over
893a32095222 Small nits.
Fred Drake <fdrake@acm.org>
parents: 7424
diff changeset
142 % the right margin.
5896
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
143 \begin{verbatim}
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
144 >>> pprint.saferepr(stuff)
7829
e2fb25784530 Talk about some minor nits...
Fred Drake <fdrake@acm.org>
parents: 7768
diff changeset
145 "[<Recursion on list with id=682968>, '', '/usr/local/lib/python1.5', '/usr/loca
e2fb25784530 Talk about some minor nits...
Fred Drake <fdrake@acm.org>
parents: 7768
diff changeset
146 l/lib/python1.5/test', '/usr/local/lib/python1.5/sunos5', '/usr/local/lib/python
e2fb25784530 Talk about some minor nits...
Fred Drake <fdrake@acm.org>
parents: 7768
diff changeset
147 1.5/sharedmodules', '/usr/local/lib/python1.5/tkinter']"
5896
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
148 \end{verbatim}
5836
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
149
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
150
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
151 \subsection{PrettyPrinter Objects}
7424
11e9337cda3d Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
152 \label{PrettyPrinter Objects}
5836
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
153
7608
893a32095222 Small nits.
Fred Drake <fdrake@acm.org>
parents: 7424
diff changeset
154 \class{PrettyPrinter} instances have the following methods:
5836
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
155
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
156
7768
8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7608
diff changeset
157 \begin{methoddesc}{pformat}{object}
5836
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
158 Return the formatted representation of \var{object}. This takes into
36118
044d35ca3424 fixed one more typo
Fredrik Lundh <fredrik@pythonware.com>
parents: 36116
diff changeset
159 account the options passed to the \class{PrettyPrinter} constructor.
7768
8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7608
diff changeset
160 \end{methoddesc}
5836
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
161
7768
8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7608
diff changeset
162 \begin{methoddesc}{pprint}{object}
5836
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
163 Print the formatted representation of \var{object} on the configured
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
164 stream, followed by a newline.
7768
8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7608
diff changeset
165 \end{methoddesc}
5836
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 The following methods provide the implementations for the
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
168 corresponding functions of the same names. Using these methods on an
7424
11e9337cda3d Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
169 instance is slightly more efficient since new \class{PrettyPrinter}
11e9337cda3d Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
170 objects don't need to be created.
5836
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
171
7768
8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7608
diff changeset
172 \begin{methoddesc}{isreadable}{object}
5836
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
173 Determine if the formatted representation of the object is
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
174 ``readable,'' or can be used to reconstruct the value using
7424
11e9337cda3d Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
175 \function{eval()}\bifuncindex{eval}. Note that this returns false for
11e9337cda3d Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
176 recursive objects. If the \var{depth} parameter of the
11e9337cda3d Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
177 \class{PrettyPrinter} is set and the object is deeper than allowed,
11e9337cda3d Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
178 this returns false.
7768
8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7608
diff changeset
179 \end{methoddesc}
5836
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
180
7768
8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7608
diff changeset
181 \begin{methoddesc}{isrecursive}{object}
5836
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
182 Determine if the object requires a recursive representation.
7768
8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7608
diff changeset
183 \end{methoddesc}
22766
d26d8575ac62 Add an experimental mechanism to support extending the pprint formatting.
Fred Drake <fdrake@acm.org>
parents: 15142
diff changeset
184
d26d8575ac62 Add an experimental mechanism to support extending the pprint formatting.
Fred Drake <fdrake@acm.org>
parents: 15142
diff changeset
185 This method is provided as a hook to allow subclasses to modify the
d26d8575ac62 Add an experimental mechanism to support extending the pprint formatting.
Fred Drake <fdrake@acm.org>
parents: 15142
diff changeset
186 way objects are converted to strings. The default implementation uses
d26d8575ac62 Add an experimental mechanism to support extending the pprint formatting.
Fred Drake <fdrake@acm.org>
parents: 15142
diff changeset
187 the internals of the \function{saferepr()} implementation.
d26d8575ac62 Add an experimental mechanism to support extending the pprint formatting.
Fred Drake <fdrake@acm.org>
parents: 15142
diff changeset
188
d26d8575ac62 Add an experimental mechanism to support extending the pprint formatting.
Fred Drake <fdrake@acm.org>
parents: 15142
diff changeset
189 \begin{methoddesc}{format}{object, context, maxlevels, level}
d26d8575ac62 Add an experimental mechanism to support extending the pprint formatting.
Fred Drake <fdrake@acm.org>
parents: 15142
diff changeset
190 Returns three values: the formatted version of \var{object} as a
d26d8575ac62 Add an experimental mechanism to support extending the pprint formatting.
Fred Drake <fdrake@acm.org>
parents: 15142
diff changeset
191 string, a flag indicating whether the result is readable, and a flag
d26d8575ac62 Add an experimental mechanism to support extending the pprint formatting.
Fred Drake <fdrake@acm.org>
parents: 15142
diff changeset
192 indicating whether recursion was detected. The first argument is the
d26d8575ac62 Add an experimental mechanism to support extending the pprint formatting.
Fred Drake <fdrake@acm.org>
parents: 15142
diff changeset
193 object to be presented. The second is a dictionary which contains the
d26d8575ac62 Add an experimental mechanism to support extending the pprint formatting.
Fred Drake <fdrake@acm.org>
parents: 15142
diff changeset
194 \function{id()} of objects that are part of the current presentation
d26d8575ac62 Add an experimental mechanism to support extending the pprint formatting.
Fred Drake <fdrake@acm.org>
parents: 15142
diff changeset
195 context (direct and indirect containers for \var{object} that are
d26d8575ac62 Add an experimental mechanism to support extending the pprint formatting.
Fred Drake <fdrake@acm.org>
parents: 15142
diff changeset
196 affecting the presentation) as the keys; if an object needs to be
d26d8575ac62 Add an experimental mechanism to support extending the pprint formatting.
Fred Drake <fdrake@acm.org>
parents: 15142
diff changeset
197 presented which is already represented in \var{context}, the third
d26d8575ac62 Add an experimental mechanism to support extending the pprint formatting.
Fred Drake <fdrake@acm.org>
parents: 15142
diff changeset
198 return value should be true. Recursive calls to the \method{format()}
34296
67f2190e1f6d SF Patch #1093896: miscellaneous doc typos
Raymond Hettinger <python@rcn.com>
parents: 31085
diff changeset
199 method should add additional entries for containers to this
36116
76741e73bb64 fixed two typos in pprint reference page
Fredrik Lundh <fredrik@pythonware.com>
parents: 34296
diff changeset
200 dictionary. The third argument, \var{maxlevels}, gives the requested
22766
d26d8575ac62 Add an experimental mechanism to support extending the pprint formatting.
Fred Drake <fdrake@acm.org>
parents: 15142
diff changeset
201 limit to recursion; this will be \code{0} if there is no requested
d26d8575ac62 Add an experimental mechanism to support extending the pprint formatting.
Fred Drake <fdrake@acm.org>
parents: 15142
diff changeset
202 limit. This argument should be passed unmodified to recursive calls.
36116
76741e73bb64 fixed two typos in pprint reference page
Fredrik Lundh <fredrik@pythonware.com>
parents: 34296
diff changeset
203 The fourth argument, \var{level}, gives the current level; recursive
22766
d26d8575ac62 Add an experimental mechanism to support extending the pprint formatting.
Fred Drake <fdrake@acm.org>
parents: 15142
diff changeset
204 calls should be passed a value less than that of the current call.
d26d8575ac62 Add an experimental mechanism to support extending the pprint formatting.
Fred Drake <fdrake@acm.org>
parents: 15142
diff changeset
205 \versionadded{2.3}
d26d8575ac62 Add an experimental mechanism to support extending the pprint formatting.
Fred Drake <fdrake@acm.org>
parents: 15142
diff changeset
206 \end{methoddesc}