blob: 6449868d5d8f558fc1dc27cbf4ae8b6114f160d8 [file] [log] [blame]
Guido van Rossum45e2fbc1998-03-26 21:13:24 +00001# Author: Fred L. Drake, Jr.
Fred Drake3e5e6612001-10-09 20:53:48 +00002# fdrake@acm.org
Guido van Rossum5e92aff1997-04-16 00:49:59 +00003#
4# This is a simple little module I wrote to make life easier. I didn't
5# see anything quite like it in the library, though I may have overlooked
6# something. I wrote this when I was trying to read some heavily nested
Thomas Wouters7e474022000-07-16 12:04:32 +00007# tuples with fairly non-descriptive content. This is modeled very much
Guido van Rossum5e92aff1997-04-16 00:49:59 +00008# after Lisp/Scheme - style pretty-printing of lists. If you find it
9# useful, thank small children who sleep at night.
10
11"""Support to pretty-print lists, tuples, & dictionaries recursively.
12
13Very simple, but useful, especially in debugging data structures.
14
Fred Drakea89fda01997-04-16 16:59:30 +000015Classes
16-------
17
18PrettyPrinter()
19 Handle pretty-printing operations onto a stream using a configured
20 set of formatting parameters.
21
Guido van Rossum5e92aff1997-04-16 00:49:59 +000022Functions
23---------
24
25pformat()
26 Format a Python object into a pretty-printed representation.
27
28pprint()
Skip Montanaro2dc0c132004-05-14 16:31:56 +000029 Pretty-print a Python object to a stream [default is sys.stdout].
Guido van Rossum5e92aff1997-04-16 00:49:59 +000030
Fred Drakea89fda01997-04-16 16:59:30 +000031saferepr()
32 Generate a 'standard' repr()-like value, but protect against recursive
33 data structures.
Guido van Rossum5e92aff1997-04-16 00:49:59 +000034
35"""
36
Fred Drake397b6152002-12-31 07:14:18 +000037import sys as _sys
Guido van Rossum5e92aff1997-04-16 00:49:59 +000038
Guido van Rossum34d19282007-08-09 01:03:29 +000039from io import StringIO as _StringIO
Guido van Rossum5e92aff1997-04-16 00:49:59 +000040
Skip Montanaroc62c81e2001-02-12 02:00:42 +000041__all__ = ["pprint","pformat","isreadable","isrecursive","saferepr",
42 "PrettyPrinter"]
Guido van Rossum5e92aff1997-04-16 00:49:59 +000043
Fred Drake49cc01e2001-11-01 17:50:38 +000044# cache these for faster access:
45_commajoin = ", ".join
Fred Drake49cc01e2001-11-01 17:50:38 +000046_id = id
47_len = len
48_type = type
49
50
Walter Dörwaldc8de4582003-12-03 20:26:05 +000051def pprint(object, stream=None, indent=1, width=80, depth=None):
Skip Montanaro2dc0c132004-05-14 16:31:56 +000052 """Pretty-print a Python object to a stream [default is sys.stdout]."""
Walter Dörwaldc8de4582003-12-03 20:26:05 +000053 printer = PrettyPrinter(
54 stream=stream, indent=indent, width=width, depth=depth)
Fred Drakea89fda01997-04-16 16:59:30 +000055 printer.pprint(object)
Guido van Rossum5e92aff1997-04-16 00:49:59 +000056
Walter Dörwaldc8de4582003-12-03 20:26:05 +000057def pformat(object, indent=1, width=80, depth=None):
Fred Drakea89fda01997-04-16 16:59:30 +000058 """Format a Python object into a pretty-printed representation."""
Walter Dörwaldc8de4582003-12-03 20:26:05 +000059 return PrettyPrinter(indent=indent, width=width, depth=depth).pformat(object)
Guido van Rossum5e92aff1997-04-16 00:49:59 +000060
Fred Drakea89fda01997-04-16 16:59:30 +000061def saferepr(object):
62 """Version of repr() which can handle recursive data structures."""
Fred Drake49cc01e2001-11-01 17:50:38 +000063 return _safe_repr(object, {}, None, 0)[0]
Guido van Rossum5e92aff1997-04-16 00:49:59 +000064
Tim Petersa814db52001-05-14 07:05:58 +000065def isreadable(object):
66 """Determine if saferepr(object) is readable by eval()."""
Fred Drake49cc01e2001-11-01 17:50:38 +000067 return _safe_repr(object, {}, None, 0)[1]
Tim Petersa814db52001-05-14 07:05:58 +000068
69def isrecursive(object):
70 """Determine if object requires a recursive representation."""
Fred Drake49cc01e2001-11-01 17:50:38 +000071 return _safe_repr(object, {}, None, 0)[2]
Guido van Rossum5e92aff1997-04-16 00:49:59 +000072
Fred Drakea89fda01997-04-16 16:59:30 +000073class PrettyPrinter:
74 def __init__(self, indent=1, width=80, depth=None, stream=None):
Guido van Rossum45e2fbc1998-03-26 21:13:24 +000075 """Handle pretty printing operations onto a stream using a set of
76 configured parameters.
Guido van Rossum5e92aff1997-04-16 00:49:59 +000077
Guido van Rossum45e2fbc1998-03-26 21:13:24 +000078 indent
79 Number of spaces to indent for each level of nesting.
Guido van Rossum5e92aff1997-04-16 00:49:59 +000080
Guido van Rossum45e2fbc1998-03-26 21:13:24 +000081 width
82 Attempted maximum number of columns in the output.
Guido van Rossum5e92aff1997-04-16 00:49:59 +000083
Guido van Rossum45e2fbc1998-03-26 21:13:24 +000084 depth
85 The maximum depth to print out nested structures.
Guido van Rossum5e92aff1997-04-16 00:49:59 +000086
Guido van Rossum45e2fbc1998-03-26 21:13:24 +000087 stream
88 The desired output stream. If omitted (or false), the standard
89 output stream available at construction will be used.
Guido van Rossum5e92aff1997-04-16 00:49:59 +000090
Guido van Rossum45e2fbc1998-03-26 21:13:24 +000091 """
92 indent = int(indent)
93 width = int(width)
Walter Dörwald7a7ede52003-12-03 20:15:28 +000094 assert indent >= 0, "indent must be >= 0"
Tim Petersa814db52001-05-14 07:05:58 +000095 assert depth is None or depth > 0, "depth must be > 0"
Walter Dörwald7a7ede52003-12-03 20:15:28 +000096 assert width, "width must be != 0"
Fred Drakee6691ef2002-07-08 12:28:06 +000097 self._depth = depth
98 self._indent_per_level = indent
99 self._width = width
Raymond Hettinger16e3c422002-06-01 16:07:16 +0000100 if stream is not None:
Fred Drakee6691ef2002-07-08 12:28:06 +0000101 self._stream = stream
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000102 else:
Fred Drake397b6152002-12-31 07:14:18 +0000103 self._stream = _sys.stdout
Guido van Rossum5e92aff1997-04-16 00:49:59 +0000104
Fred Drakea89fda01997-04-16 16:59:30 +0000105 def pprint(self, object):
Walter Dörwalde62e9362005-11-11 18:18:51 +0000106 self._format(object, self._stream, 0, 0, {}, 0)
107 self._stream.write("\n")
Fred Drakea89fda01997-04-16 16:59:30 +0000108
109 def pformat(self, object):
Fred Drake397b6152002-12-31 07:14:18 +0000110 sio = _StringIO()
Fred Drakee6691ef2002-07-08 12:28:06 +0000111 self._format(object, sio, 0, 0, {}, 0)
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000112 return sio.getvalue()
Fred Drakea89fda01997-04-16 16:59:30 +0000113
Fred Drakee0ffabe1997-07-18 20:42:39 +0000114 def isrecursive(self, object):
Fred Drake397b6152002-12-31 07:14:18 +0000115 return self.format(object, {}, 0, 0)[2]
Fred Drakee0ffabe1997-07-18 20:42:39 +0000116
117 def isreadable(self, object):
Fred Drake397b6152002-12-31 07:14:18 +0000118 s, readable, recursive = self.format(object, {}, 0, 0)
Fred Drakeaee113d2002-04-02 05:08:35 +0000119 return readable and not recursive
Fred Drakee0ffabe1997-07-18 20:42:39 +0000120
Fred Drakee6691ef2002-07-08 12:28:06 +0000121 def _format(self, object, stream, indent, allowance, context, level):
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000122 level = level + 1
Fred Drake49cc01e2001-11-01 17:50:38 +0000123 objid = _id(object)
124 if objid in context:
125 stream.write(_recursion(object))
Fred Drakee6691ef2002-07-08 12:28:06 +0000126 self._recursive = True
127 self._readable = False
Fred Drake49cc01e2001-11-01 17:50:38 +0000128 return
Fred Drakee6691ef2002-07-08 12:28:06 +0000129 rep = self._repr(object, context, level - 1)
Fred Drake49cc01e2001-11-01 17:50:38 +0000130 typ = _type(object)
Fred Drakee6691ef2002-07-08 12:28:06 +0000131 sepLines = _len(rep) > (self._width - 1 - indent - allowance)
Fred Drake49cc01e2001-11-01 17:50:38 +0000132 write = stream.write
Fred Drakea89fda01997-04-16 16:59:30 +0000133
Fred Drake49cc01e2001-11-01 17:50:38 +0000134 if sepLines:
Walter Dörwald1b626ca2004-11-15 13:51:41 +0000135 r = getattr(typ, "__repr__", None)
Walter Dörwald7a7ede52003-12-03 20:15:28 +0000136 if issubclass(typ, dict) and r is dict.__repr__:
Fred Drake49cc01e2001-11-01 17:50:38 +0000137 write('{')
Fred Drakee6691ef2002-07-08 12:28:06 +0000138 if self._indent_per_level > 1:
139 write((self._indent_per_level - 1) * ' ')
Fred Drake49cc01e2001-11-01 17:50:38 +0000140 length = _len(object)
141 if length:
142 context[objid] = 1
Fred Drakee6691ef2002-07-08 12:28:06 +0000143 indent = indent + self._indent_per_level
Guido van Rossum07f24362007-02-11 22:59:48 +0000144 items = sorted(object.items())
Fred Drake49cc01e2001-11-01 17:50:38 +0000145 key, ent = items[0]
Fred Drakee6691ef2002-07-08 12:28:06 +0000146 rep = self._repr(key, context, level)
Fred Drake49cc01e2001-11-01 17:50:38 +0000147 write(rep)
148 write(': ')
Fred Drakee6691ef2002-07-08 12:28:06 +0000149 self._format(ent, stream, indent + _len(rep) + 2,
Fred Drake49cc01e2001-11-01 17:50:38 +0000150 allowance + 1, context, level)
151 if length > 1:
152 for key, ent in items[1:]:
Fred Drakee6691ef2002-07-08 12:28:06 +0000153 rep = self._repr(key, context, level)
Barry Warsaw00859c02001-11-28 05:49:39 +0000154 write(',\n%s%s: ' % (' '*indent, rep))
Fred Drakee6691ef2002-07-08 12:28:06 +0000155 self._format(ent, stream, indent + _len(rep) + 2,
Fred Drake49cc01e2001-11-01 17:50:38 +0000156 allowance + 1, context, level)
Fred Drakee6691ef2002-07-08 12:28:06 +0000157 indent = indent - self._indent_per_level
Fred Drake49cc01e2001-11-01 17:50:38 +0000158 del context[objid]
159 write('}')
160 return
Fred Drakea89fda01997-04-16 16:59:30 +0000161
Walter Dörwald7a7ede52003-12-03 20:15:28 +0000162 if (issubclass(typ, list) and r is list.__repr__) or \
163 (issubclass(typ, tuple) and r is tuple.__repr__):
164 if issubclass(typ, list):
Fred Drake49cc01e2001-11-01 17:50:38 +0000165 write('[')
166 endchar = ']'
167 else:
168 write('(')
169 endchar = ')'
Fred Drakee6691ef2002-07-08 12:28:06 +0000170 if self._indent_per_level > 1:
171 write((self._indent_per_level - 1) * ' ')
Fred Drake49cc01e2001-11-01 17:50:38 +0000172 length = _len(object)
173 if length:
174 context[objid] = 1
Fred Drakee6691ef2002-07-08 12:28:06 +0000175 indent = indent + self._indent_per_level
176 self._format(object[0], stream, indent, allowance + 1,
177 context, level)
Fred Drake49cc01e2001-11-01 17:50:38 +0000178 if length > 1:
179 for ent in object[1:]:
180 write(',\n' + ' '*indent)
Fred Drakee6691ef2002-07-08 12:28:06 +0000181 self._format(ent, stream, indent,
Fred Drake49cc01e2001-11-01 17:50:38 +0000182 allowance + 1, context, level)
Fred Drakee6691ef2002-07-08 12:28:06 +0000183 indent = indent - self._indent_per_level
Fred Drake49cc01e2001-11-01 17:50:38 +0000184 del context[objid]
Walter Dörwald7a7ede52003-12-03 20:15:28 +0000185 if issubclass(typ, tuple) and length == 1:
Fred Drake49cc01e2001-11-01 17:50:38 +0000186 write(',')
187 write(endchar)
188 return
Fred Drakea89fda01997-04-16 16:59:30 +0000189
Fred Drake49cc01e2001-11-01 17:50:38 +0000190 write(rep)
Guido van Rossum5e92aff1997-04-16 00:49:59 +0000191
Fred Drakee6691ef2002-07-08 12:28:06 +0000192 def _repr(self, object, context, level):
Fred Drakeaee113d2002-04-02 05:08:35 +0000193 repr, readable, recursive = self.format(object, context.copy(),
Fred Drakee6691ef2002-07-08 12:28:06 +0000194 self._depth, level)
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000195 if not readable:
Fred Drakee6691ef2002-07-08 12:28:06 +0000196 self._readable = False
Tim Petersa814db52001-05-14 07:05:58 +0000197 if recursive:
Fred Drakee6691ef2002-07-08 12:28:06 +0000198 self._recursive = True
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000199 return repr
Guido van Rossum5e92aff1997-04-16 00:49:59 +0000200
Fred Drakeaee113d2002-04-02 05:08:35 +0000201 def format(self, object, context, maxlevels, level):
202 """Format object for a specific context, returning a string
203 and flags indicating whether the representation is 'readable'
204 and whether the object represents a recursive construct.
205 """
206 return _safe_repr(object, context, maxlevels, level)
207
208
Tim Petersa814db52001-05-14 07:05:58 +0000209# Return triple (repr_string, isreadable, isrecursive).
Guido van Rossum5e92aff1997-04-16 00:49:59 +0000210
Fred Drake49cc01e2001-11-01 17:50:38 +0000211def _safe_repr(object, context, maxlevels, level):
212 typ = _type(object)
Martin v. Löwisd02879d2003-06-07 20:47:37 +0000213 if typ is str:
Fred Drake397b6152002-12-31 07:14:18 +0000214 if 'locale' not in _sys.modules:
Walter Dörwald70a6b492004-02-12 17:35:32 +0000215 return repr(object), True, False
Fred Drake1ef106c2001-09-04 19:43:26 +0000216 if "'" in object and '"' not in object:
217 closure = '"'
218 quotes = {'"': '\\"'}
219 else:
220 closure = "'"
221 quotes = {"'": "\\'"}
Fred Drake49cc01e2001-11-01 17:50:38 +0000222 qget = quotes.get
Fred Drake397b6152002-12-31 07:14:18 +0000223 sio = _StringIO()
Fred Drake49cc01e2001-11-01 17:50:38 +0000224 write = sio.write
Fred Drake1ef106c2001-09-04 19:43:26 +0000225 for char in object:
226 if char.isalpha():
Fred Drake49cc01e2001-11-01 17:50:38 +0000227 write(char)
Fred Drake1ef106c2001-09-04 19:43:26 +0000228 else:
Walter Dörwald70a6b492004-02-12 17:35:32 +0000229 write(qget(char, repr(char)[1:-1]))
Guido van Rossum8ca162f2002-04-07 06:36:23 +0000230 return ("%s%s%s" % (closure, sio.getvalue(), closure)), True, False
Tim Peters95b3f782001-05-14 18:39:41 +0000231
Walter Dörwald1b626ca2004-11-15 13:51:41 +0000232 r = getattr(typ, "__repr__", None)
Walter Dörwald7a7ede52003-12-03 20:15:28 +0000233 if issubclass(typ, dict) and r is dict.__repr__:
Fred Drake49cc01e2001-11-01 17:50:38 +0000234 if not object:
Guido van Rossum8ca162f2002-04-07 06:36:23 +0000235 return "{}", True, False
Fred Drake49cc01e2001-11-01 17:50:38 +0000236 objid = _id(object)
237 if maxlevels and level > maxlevels:
Guido van Rossum8ca162f2002-04-07 06:36:23 +0000238 return "{...}", False, objid in context
Fred Drake49cc01e2001-11-01 17:50:38 +0000239 if objid in context:
Guido van Rossum8ca162f2002-04-07 06:36:23 +0000240 return _recursion(object), False, True
Fred Drake49cc01e2001-11-01 17:50:38 +0000241 context[objid] = 1
Guido van Rossum8ca162f2002-04-07 06:36:23 +0000242 readable = True
243 recursive = False
Tim Peters95b3f782001-05-14 18:39:41 +0000244 components = []
Fred Drake49cc01e2001-11-01 17:50:38 +0000245 append = components.append
246 level += 1
247 saferepr = _safe_repr
Guido van Rossum47b9ff62006-08-24 00:41:19 +0000248 items = object.items()
249 try:
250 items = sorted(items)
251 except TypeError:
Guido van Rossum1bc535d2007-05-15 18:46:22 +0000252 def sortkey(item):
253 key, value = item
254 return str(type(key)), key, value
255 items = sorted(items, key=sortkey)
Guido van Rossum47b9ff62006-08-24 00:41:19 +0000256 for k, v in items:
Fred Drake49cc01e2001-11-01 17:50:38 +0000257 krepr, kreadable, krecur = saferepr(k, context, maxlevels, level)
258 vrepr, vreadable, vrecur = saferepr(v, context, maxlevels, level)
259 append("%s: %s" % (krepr, vrepr))
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000260 readable = readable and kreadable and vreadable
Fred Drake49cc01e2001-11-01 17:50:38 +0000261 if krecur or vrecur:
Guido van Rossum8ca162f2002-04-07 06:36:23 +0000262 recursive = True
Fred Drake49cc01e2001-11-01 17:50:38 +0000263 del context[objid]
264 return "{%s}" % _commajoin(components), readable, recursive
Tim Peters95b3f782001-05-14 18:39:41 +0000265
Walter Dörwald7a7ede52003-12-03 20:15:28 +0000266 if (issubclass(typ, list) and r is list.__repr__) or \
267 (issubclass(typ, tuple) and r is tuple.__repr__):
268 if issubclass(typ, list):
Fred Drake49cc01e2001-11-01 17:50:38 +0000269 if not object:
Guido van Rossum8ca162f2002-04-07 06:36:23 +0000270 return "[]", True, False
Fred Drake49cc01e2001-11-01 17:50:38 +0000271 format = "[%s]"
272 elif _len(object) == 1:
273 format = "(%s,)"
274 else:
275 if not object:
Guido van Rossum8ca162f2002-04-07 06:36:23 +0000276 return "()", True, False
Fred Drake49cc01e2001-11-01 17:50:38 +0000277 format = "(%s)"
278 objid = _id(object)
279 if maxlevels and level > maxlevels:
Guido van Rossum8ca162f2002-04-07 06:36:23 +0000280 return format % "...", False, objid in context
Fred Drake49cc01e2001-11-01 17:50:38 +0000281 if objid in context:
Guido van Rossum8ca162f2002-04-07 06:36:23 +0000282 return _recursion(object), False, True
Fred Drake49cc01e2001-11-01 17:50:38 +0000283 context[objid] = 1
Guido van Rossum8ca162f2002-04-07 06:36:23 +0000284 readable = True
285 recursive = False
Tim Peters95b3f782001-05-14 18:39:41 +0000286 components = []
Fred Drake49cc01e2001-11-01 17:50:38 +0000287 append = components.append
288 level += 1
289 for o in object:
290 orepr, oreadable, orecur = _safe_repr(o, context, maxlevels, level)
291 append(orepr)
292 if not oreadable:
Guido van Rossum8ca162f2002-04-07 06:36:23 +0000293 readable = False
Fred Drake49cc01e2001-11-01 17:50:38 +0000294 if orecur:
Guido van Rossum8ca162f2002-04-07 06:36:23 +0000295 recursive = True
Fred Drake49cc01e2001-11-01 17:50:38 +0000296 del context[objid]
297 return format % _commajoin(components), readable, recursive
Tim Peters88768482001-11-13 21:51:26 +0000298
Walter Dörwald70a6b492004-02-12 17:35:32 +0000299 rep = repr(object)
Guido van Rossum8ca162f2002-04-07 06:36:23 +0000300 return rep, (rep and not rep.startswith('<')), False
Tim Peters95b3f782001-05-14 18:39:41 +0000301
Guido van Rossum5e92aff1997-04-16 00:49:59 +0000302
Fred Drake49cc01e2001-11-01 17:50:38 +0000303def _recursion(object):
304 return ("<Recursion on %s with id=%s>"
305 % (_type(object).__name__, _id(object)))
Fred Drakea89fda01997-04-16 16:59:30 +0000306
Fred Drake49cc01e2001-11-01 17:50:38 +0000307
308def _perfcheck(object=None):
309 import time
310 if object is None:
311 object = [("string", (1, 2), [3, 4], {5: 6, 7: 8})] * 100000
312 p = PrettyPrinter()
313 t1 = time.time()
314 _safe_repr(object, {}, None, 0)
315 t2 = time.time()
316 p.pformat(object)
317 t3 = time.time()
Guido van Rossumbe19ed72007-02-09 05:37:30 +0000318 print("_safe_repr:", t2 - t1)
319 print("pformat:", t3 - t2)
Fred Drake49cc01e2001-11-01 17:50:38 +0000320
321if __name__ == "__main__":
322 _perfcheck()