Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libpprint.tex @ 38546:2eb8be0f8731 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
pprint functions used to sort a dict (by key) if and only if the output required more than one line. "Small" dicts got displayed in seemingly random order (the hash-induced order produced by dict.__repr__). None of this was documented. Now pprint functions always sort dicts by key, and the docs promise it. This was proposed and agreed to during the PyCon 2006 core sprint -- I just didn't have time for it before now.
author Tim Peters <tim.peters@gmail.com>
date Fri, 02 Jun 2006 23:22:51 +0000
parents 044d35ca3424
children 06145fbc7ab9 76e63e033356
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
38546
2eb8be0f8731 pprint functions used to sort a dict (by key) if and only if
Tim Peters <tim.peters@gmail.com>
parents: 36118
diff changeset
23 \versionchanged[Dictionaries are sorted by key before the display is
2eb8be0f8731 pprint functions used to sort a dict (by key) if and only if
Tim Peters <tim.peters@gmail.com>
parents: 36118
diff changeset
24 computed; before 2.5, a dictionary was sorted only if its display
2eb8be0f8731 pprint functions used to sort a dict (by key) if and only if
Tim Peters <tim.peters@gmail.com>
parents: 36118
diff changeset
25 required more than one line, although that wasn't documented]{2.5}
2eb8be0f8731 pprint functions used to sort a dict (by key) if and only if
Tim Peters <tim.peters@gmail.com>
parents: 36118
diff changeset
26
7424
11e9337cda3d Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
27 The \module{pprint} module defines one class:
5836
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
28
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
29
5896
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
30 % First the implementation class:
5836
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
31
7424
11e9337cda3d Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
32 \begin{classdesc}{PrettyPrinter}{...}
11e9337cda3d Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
33 Construct a \class{PrettyPrinter} instance. This constructor
11e9337cda3d Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
34 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
35 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
36 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
37 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
38 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
39 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
40 \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
41 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
42 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
43 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
44 \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
45 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
46 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
47 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
48 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
49 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
50
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
51 \begin{verbatim}
5896
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
52 >>> import pprint, sys
5836
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
53 >>> stuff = sys.path[:]
5896
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
54 >>> stuff.insert(0, stuff[:])
5836
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
55 >>> pp = pprint.PrettyPrinter(indent=4)
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
56 >>> pp.pprint(stuff)
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
57 [ [ '',
5896
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
58 '/usr/local/lib/python1.5',
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
59 '/usr/local/lib/python1.5/test',
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
60 '/usr/local/lib/python1.5/sunos5',
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
61 '/usr/local/lib/python1.5/sharedmodules',
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
62 '/usr/local/lib/python1.5/tkinter'],
5836
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
63 '',
5896
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
64 '/usr/local/lib/python1.5',
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
65 '/usr/local/lib/python1.5/test',
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
66 '/usr/local/lib/python1.5/sunos5',
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
67 '/usr/local/lib/python1.5/sharedmodules',
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
68 '/usr/local/lib/python1.5/tkinter']
5836
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
69 >>>
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
70 >>> import parser
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
71 >>> tup = parser.ast2tuple(
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
72 ... parser.suite(open('pprint.py').read()))[1][1][1]
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
73 >>> pp = pprint.PrettyPrinter(depth=6)
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
74 >>> pp.pprint(tup)
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
75 (266, (267, (307, (287, (288, (...))))))
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
76 \end{verbatim}
7424
11e9337cda3d Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
77 \end{classdesc}
5896
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
78
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
79
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
80 % Now the derivative functions:
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
81
7424
11e9337cda3d Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
82 The \class{PrettyPrinter} class supports several derivative functions:
5896
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
83
31085
a2f6c6a67f24 Add parameters indent, width and depth to pprint.pprint() and pprint.pformat()
Walter Dörwald <walter@livinglogic.de>
parents: 31029
diff changeset
84 \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
85 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
86 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
87 \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
88 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
89 \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
90 were added]{2.4}
5896
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
91 \end{funcdesc}
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
92
31085
a2f6c6a67f24 Add parameters indent, width and depth to pprint.pprint() and pprint.pformat()
Walter Dörwald <walter@livinglogic.de>
parents: 31029
diff changeset
93 \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
94 indent\optional{, width\optional{, depth}}}}}
5896
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
95 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
96 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
97 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
98 \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
99 \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
100 constructor as formatting parameters.
5896
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
101
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
102 \begin{verbatim}
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
103 >>> stuff = sys.path[:]
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
104 >>> stuff.insert(0, stuff)
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
105 >>> pprint.pprint(stuff)
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
106 [<Recursion on list with id=869440>,
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
107 '',
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
108 '/usr/local/lib/python1.5',
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
109 '/usr/local/lib/python1.5/test',
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
110 '/usr/local/lib/python1.5/sunos5',
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
111 '/usr/local/lib/python1.5/sharedmodules',
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
112 '/usr/local/lib/python1.5/tkinter']
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
113 \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
114 \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
115 were added]{2.4}
5896
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
116 \end{funcdesc}
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
117
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
118 \begin{funcdesc}{isreadable}{object}
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
119 Determine if the formatted representation of \var{object} is
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
120 ``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
121 \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
122 recursive objects.
5896
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
123
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
124 \begin{verbatim}
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
125 >>> 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
126 False
5896
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
127 \end{verbatim}
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 \begin{funcdesc}{isrecursive}{object}
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
131 Determine if \var{object} requires a recursive representation.
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
132 \end{funcdesc}
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
133
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
134
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
135 One more support function is also defined:
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
136
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
137 \begin{funcdesc}{saferepr}{object}
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
138 Return a string representation of \var{object}, protected against
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
139 recursive data structures. If the representation of \var{object}
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
140 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
141 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
142 representation is not otherwise formatted.
7608
893a32095222 Small nits.
Fred Drake <fdrake@acm.org>
parents: 7424
diff changeset
143 \end{funcdesc}
5896
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
144
7608
893a32095222 Small nits.
Fred Drake <fdrake@acm.org>
parents: 7424
diff changeset
145 % This example is outside the {funcdesc} to keep it from running over
893a32095222 Small nits.
Fred Drake <fdrake@acm.org>
parents: 7424
diff changeset
146 % the right margin.
5896
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
147 \begin{verbatim}
67022d28a65d A couple of grammatical nits.
Fred Drake <fdrake@acm.org>
parents: 5836
diff changeset
148 >>> pprint.saferepr(stuff)
7829
e2fb25784530 Talk about some minor nits...
Fred Drake <fdrake@acm.org>
parents: 7768
diff changeset
149 "[<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
150 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
151 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
152 \end{verbatim}
5836
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
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
155 \subsection{PrettyPrinter Objects}
7424
11e9337cda3d Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
156 \label{PrettyPrinter Objects}
5836
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
157
7608
893a32095222 Small nits.
Fred Drake <fdrake@acm.org>
parents: 7424
diff changeset
158 \class{PrettyPrinter} instances have the following methods:
5836
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
159
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
160
7768
8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7608
diff changeset
161 \begin{methoddesc}{pformat}{object}
5836
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
162 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
163 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
164 \end{methoddesc}
5836
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
165
7768
8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7608
diff changeset
166 \begin{methoddesc}{pprint}{object}
5836
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
167 Print the formatted representation of \var{object} on the configured
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
168 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
169 \end{methoddesc}
5836
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
170
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
171 The following methods provide the implementations for the
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
172 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
173 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
174 objects don't need to be created.
5836
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
175
7768
8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7608
diff changeset
176 \begin{methoddesc}{isreadable}{object}
5836
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
177 Determine if the formatted representation of the object is
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
178 ``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
179 \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
180 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
181 \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
182 this returns false.
7768
8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7608
diff changeset
183 \end{methoddesc}
5836
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
184
7768
8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7608
diff changeset
185 \begin{methoddesc}{isrecursive}{object}
5836
3a798677506c Documentation for the pprint module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
186 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
187 \end{methoddesc}
22766
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 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
190 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
191 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
192
d26d8575ac62 Add an experimental mechanism to support extending the pprint formatting.
Fred Drake <fdrake@acm.org>
parents: 15142
diff changeset
193 \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
194 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
195 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
196 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
197 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
198 \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
199 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
200 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
201 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
202 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
203 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
204 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
205 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
206 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
207 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
208 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
209 \versionadded{2.3}
d26d8575ac62 Add an experimental mechanism to support extending the pprint formatting.
Fred Drake <fdrake@acm.org>
parents: 15142
diff changeset
210 \end{methoddesc}