Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/pandas/io/formats/printing.py: 10%

Shortcuts on this page

r m x   toggle line displays

j k   next/prev highlighted chunk

0   (zero) top of page

1   (one) first highlighted chunk

203 statements  

1""" 

2Printing tools. 

3""" 

4from __future__ import annotations 

5 

6import sys 

7from typing import ( 

8 Any, 

9 Callable, 

10 Dict, 

11 Iterable, 

12 Mapping, 

13 Sequence, 

14 TypeVar, 

15 Union, 

16) 

17 

18from pandas._config import get_option 

19 

20from pandas.core.dtypes.inference import is_sequence 

21 

22EscapeChars = Union[Mapping[str, str], Iterable[str]] 

23_KT = TypeVar("_KT") 

24_VT = TypeVar("_VT") 

25 

26 

27def adjoin(space: int, *lists: list[str], **kwargs) -> str: 

28 """ 

29 Glues together two sets of strings using the amount of space requested. 

30 The idea is to prettify. 

31 

32 ---------- 

33 space : int 

34 number of spaces for padding 

35 lists : str 

36 list of str which being joined 

37 strlen : callable 

38 function used to calculate the length of each str. Needed for unicode 

39 handling. 

40 justfunc : callable 

41 function used to justify str. Needed for unicode handling. 

42 """ 

43 strlen = kwargs.pop("strlen", len) 

44 justfunc = kwargs.pop("justfunc", justify) 

45 

46 out_lines = [] 

47 newLists = [] 

48 lengths = [max(map(strlen, x)) + space for x in lists[:-1]] 

49 # not the last one 

50 lengths.append(max(map(len, lists[-1]))) 

51 maxLen = max(map(len, lists)) 

52 for i, lst in enumerate(lists): 

53 nl = justfunc(lst, lengths[i], mode="left") 

54 nl = ([" " * lengths[i]] * (maxLen - len(lst))) + nl 

55 newLists.append(nl) 

56 toJoin = zip(*newLists) 

57 for lines in toJoin: 

58 out_lines.append("".join(lines)) 

59 return "\n".join(out_lines) 

60 

61 

62def justify(texts: Iterable[str], max_len: int, mode: str = "right") -> list[str]: 

63 """ 

64 Perform ljust, center, rjust against string or list-like 

65 """ 

66 if mode == "left": 

67 return [x.ljust(max_len) for x in texts] 

68 elif mode == "center": 

69 return [x.center(max_len) for x in texts] 

70 else: 

71 return [x.rjust(max_len) for x in texts] 

72 

73 

74# Unicode consolidation 

75# --------------------- 

76# 

77# pprinting utility functions for generating Unicode text or 

78# bytes(3.x)/str(2.x) representations of objects. 

79# Try to use these as much as possible rather than rolling your own. 

80# 

81# When to use 

82# ----------- 

83# 

84# 1) If you're writing code internal to pandas (no I/O directly involved), 

85# use pprint_thing(). 

86# 

87# It will always return unicode text which can handled by other 

88# parts of the package without breakage. 

89# 

90# 2) if you need to write something out to file, use 

91# pprint_thing_encoded(encoding). 

92# 

93# If no encoding is specified, it defaults to utf-8. Since encoding pure 

94# ascii with utf-8 is a no-op you can safely use the default utf-8 if you're 

95# working with straight ascii. 

96 

97 

98def _pprint_seq( 

99 seq: Sequence, _nest_lvl: int = 0, max_seq_items: int | None = None, **kwds 

100) -> str: 

101 """ 

102 internal. pprinter for iterables. you should probably use pprint_thing() 

103 rather than calling this directly. 

104 

105 bounds length of printed sequence, depending on options 

106 """ 

107 if isinstance(seq, set): 

108 fmt = "{{{body}}}" 

109 else: 

110 fmt = "[{body}]" if hasattr(seq, "__setitem__") else "({body})" 

111 

112 if max_seq_items is False: 

113 nitems = len(seq) 

114 else: 

115 nitems = max_seq_items or get_option("max_seq_items") or len(seq) 

116 

117 s = iter(seq) 

118 # handle sets, no slicing 

119 r = [ 

120 pprint_thing(next(s), _nest_lvl + 1, max_seq_items=max_seq_items, **kwds) 

121 for i in range(min(nitems, len(seq))) 

122 ] 

123 body = ", ".join(r) 

124 

125 if nitems < len(seq): 

126 body += ", ..." 

127 elif isinstance(seq, tuple) and len(seq) == 1: 

128 body += "," 

129 

130 return fmt.format(body=body) 

131 

132 

133def _pprint_dict( 

134 seq: Mapping, _nest_lvl: int = 0, max_seq_items: int | None = None, **kwds 

135) -> str: 

136 """ 

137 internal. pprinter for iterables. you should probably use pprint_thing() 

138 rather than calling this directly. 

139 """ 

140 fmt = "{{{things}}}" 

141 pairs = [] 

142 

143 pfmt = "{key}: {val}" 

144 

145 if max_seq_items is False: 

146 nitems = len(seq) 

147 else: 

148 nitems = max_seq_items or get_option("max_seq_items") or len(seq) 

149 

150 for k, v in list(seq.items())[:nitems]: 

151 pairs.append( 

152 pfmt.format( 

153 key=pprint_thing(k, _nest_lvl + 1, max_seq_items=max_seq_items, **kwds), 

154 val=pprint_thing(v, _nest_lvl + 1, max_seq_items=max_seq_items, **kwds), 

155 ) 

156 ) 

157 

158 if nitems < len(seq): 

159 return fmt.format(things=", ".join(pairs) + ", ...") 

160 else: 

161 return fmt.format(things=", ".join(pairs)) 

162 

163 

164def pprint_thing( 

165 thing: Any, 

166 _nest_lvl: int = 0, 

167 escape_chars: EscapeChars | None = None, 

168 default_escapes: bool = False, 

169 quote_strings: bool = False, 

170 max_seq_items: int | None = None, 

171) -> str: 

172 """ 

173 This function is the sanctioned way of converting objects 

174 to a string representation and properly handles nested sequences. 

175 

176 Parameters 

177 ---------- 

178 thing : anything to be formatted 

179 _nest_lvl : internal use only. pprint_thing() is mutually-recursive 

180 with pprint_sequence, this argument is used to keep track of the 

181 current nesting level, and limit it. 

182 escape_chars : list or dict, optional 

183 Characters to escape. If a dict is passed the values are the 

184 replacements 

185 default_escapes : bool, default False 

186 Whether the input escape characters replaces or adds to the defaults 

187 max_seq_items : int or None, default None 

188 Pass through to other pretty printers to limit sequence printing 

189 

190 Returns 

191 ------- 

192 str 

193 """ 

194 

195 def as_escaped_string( 

196 thing: Any, escape_chars: EscapeChars | None = escape_chars 

197 ) -> str: 

198 translate = {"\t": r"\t", "\n": r"\n", "\r": r"\r"} 

199 if isinstance(escape_chars, dict): 

200 if default_escapes: 

201 translate.update(escape_chars) 

202 else: 

203 translate = escape_chars 

204 escape_chars = list(escape_chars.keys()) 

205 else: 

206 escape_chars = escape_chars or () 

207 

208 result = str(thing) 

209 for c in escape_chars: 

210 result = result.replace(c, translate[c]) 

211 return result 

212 

213 if hasattr(thing, "__next__"): 

214 return str(thing) 

215 elif isinstance(thing, dict) and _nest_lvl < get_option( 

216 "display.pprint_nest_depth" 

217 ): 

218 result = _pprint_dict( 

219 thing, _nest_lvl, quote_strings=True, max_seq_items=max_seq_items 

220 ) 

221 elif is_sequence(thing) and _nest_lvl < get_option("display.pprint_nest_depth"): 

222 result = _pprint_seq( 

223 thing, 

224 _nest_lvl, 

225 escape_chars=escape_chars, 

226 quote_strings=quote_strings, 

227 max_seq_items=max_seq_items, 

228 ) 

229 elif isinstance(thing, str) and quote_strings: 

230 result = f"'{as_escaped_string(thing)}'" 

231 else: 

232 result = as_escaped_string(thing) 

233 

234 return result 

235 

236 

237def pprint_thing_encoded( 

238 object, encoding: str = "utf-8", errors: str = "replace" 

239) -> bytes: 

240 value = pprint_thing(object) # get unicode representation of object 

241 return value.encode(encoding, errors) 

242 

243 

244def enable_data_resource_formatter(enable: bool) -> None: 

245 if "IPython" not in sys.modules: 

246 # definitely not in IPython 

247 return 

248 from IPython import get_ipython 

249 

250 ip = get_ipython() 

251 if ip is None: 

252 # still not in IPython 

253 return 

254 

255 formatters = ip.display_formatter.formatters 

256 mimetype = "application/vnd.dataresource+json" 

257 

258 if enable: 

259 if mimetype not in formatters: 

260 # define tableschema formatter 

261 from IPython.core.formatters import BaseFormatter 

262 from traitlets import ObjectName 

263 

264 class TableSchemaFormatter(BaseFormatter): 

265 print_method = ObjectName("_repr_data_resource_") 

266 _return_type = (dict,) 

267 

268 # register it: 

269 formatters[mimetype] = TableSchemaFormatter() 

270 # enable it if it's been disabled: 

271 formatters[mimetype].enabled = True 

272 else: 

273 # unregister tableschema mime-type 

274 if mimetype in formatters: 

275 formatters[mimetype].enabled = False 

276 

277 

278def default_pprint(thing: Any, max_seq_items: int | None = None) -> str: 

279 return pprint_thing( 

280 thing, 

281 escape_chars=("\t", "\r", "\n"), 

282 quote_strings=True, 

283 max_seq_items=max_seq_items, 

284 ) 

285 

286 

287def format_object_summary( 

288 obj, 

289 formatter: Callable, 

290 is_justify: bool = True, 

291 name: str | None = None, 

292 indent_for_name: bool = True, 

293 line_break_each_value: bool = False, 

294) -> str: 

295 """ 

296 Return the formatted obj as a unicode string 

297 

298 Parameters 

299 ---------- 

300 obj : object 

301 must be iterable and support __getitem__ 

302 formatter : callable 

303 string formatter for an element 

304 is_justify : bool 

305 should justify the display 

306 name : name, optional 

307 defaults to the class name of the obj 

308 indent_for_name : bool, default True 

309 Whether subsequent lines should be indented to 

310 align with the name. 

311 line_break_each_value : bool, default False 

312 If True, inserts a line break for each value of ``obj``. 

313 If False, only break lines when the a line of values gets wider 

314 than the display width. 

315 

316 Returns 

317 ------- 

318 summary string 

319 """ 

320 from pandas.io.formats.console import get_console_size 

321 from pandas.io.formats.format import get_adjustment 

322 

323 display_width, _ = get_console_size() 

324 if display_width is None: 

325 display_width = get_option("display.width") or 80 

326 if name is None: 

327 name = type(obj).__name__ 

328 

329 if indent_for_name: 

330 name_len = len(name) 

331 space1 = f'\n{(" " * (name_len + 1))}' 

332 space2 = f'\n{(" " * (name_len + 2))}' 

333 else: 

334 space1 = "\n" 

335 space2 = "\n " # space for the opening '[' 

336 

337 n = len(obj) 

338 if line_break_each_value: 

339 # If we want to vertically align on each value of obj, we need to 

340 # separate values by a line break and indent the values 

341 sep = ",\n " + " " * len(name) 

342 else: 

343 sep = "," 

344 max_seq_items = get_option("display.max_seq_items") or n 

345 

346 # are we a truncated display 

347 is_truncated = n > max_seq_items 

348 

349 # adj can optionally handle unicode eastern asian width 

350 adj = get_adjustment() 

351 

352 def _extend_line( 

353 s: str, line: str, value: str, display_width: int, next_line_prefix: str 

354 ) -> tuple[str, str]: 

355 if adj.len(line.rstrip()) + adj.len(value.rstrip()) >= display_width: 

356 s += line.rstrip() 

357 line = next_line_prefix 

358 line += value 

359 return s, line 

360 

361 def best_len(values: list[str]) -> int: 

362 if values: 

363 return max(adj.len(x) for x in values) 

364 else: 

365 return 0 

366 

367 close = ", " 

368 

369 if n == 0: 

370 summary = f"[]{close}" 

371 elif n == 1 and not line_break_each_value: 

372 first = formatter(obj[0]) 

373 summary = f"[{first}]{close}" 

374 elif n == 2 and not line_break_each_value: 

375 first = formatter(obj[0]) 

376 last = formatter(obj[-1]) 

377 summary = f"[{first}, {last}]{close}" 

378 else: 

379 if max_seq_items == 1: 

380 # If max_seq_items=1 show only last element 

381 head = [] 

382 tail = [formatter(x) for x in obj[-1:]] 

383 elif n > max_seq_items: 

384 n = min(max_seq_items // 2, 10) 

385 head = [formatter(x) for x in obj[:n]] 

386 tail = [formatter(x) for x in obj[-n:]] 

387 else: 

388 head = [] 

389 tail = [formatter(x) for x in obj] 

390 

391 # adjust all values to max length if needed 

392 if is_justify: 

393 if line_break_each_value: 

394 # Justify each string in the values of head and tail, so the 

395 # strings will right align when head and tail are stacked 

396 # vertically. 

397 head, tail = _justify(head, tail) 

398 elif is_truncated or not ( 

399 len(", ".join(head)) < display_width 

400 and len(", ".join(tail)) < display_width 

401 ): 

402 # Each string in head and tail should align with each other 

403 max_length = max(best_len(head), best_len(tail)) 

404 head = [x.rjust(max_length) for x in head] 

405 tail = [x.rjust(max_length) for x in tail] 

406 # If we are not truncated and we are only a single 

407 # line, then don't justify 

408 

409 if line_break_each_value: 

410 # Now head and tail are of type List[Tuple[str]]. Below we 

411 # convert them into List[str], so there will be one string per 

412 # value. Also truncate items horizontally if wider than 

413 # max_space 

414 max_space = display_width - len(space2) 

415 value = tail[0] 

416 for max_items in reversed(range(1, len(value) + 1)): 

417 pprinted_seq = _pprint_seq(value, max_seq_items=max_items) 

418 if len(pprinted_seq) < max_space: 

419 head = [_pprint_seq(x, max_seq_items=max_items) for x in head] 

420 tail = [_pprint_seq(x, max_seq_items=max_items) for x in tail] 

421 break 

422 

423 summary = "" 

424 line = space2 

425 

426 for head_value in head: 

427 word = head_value + sep + " " 

428 summary, line = _extend_line(summary, line, word, display_width, space2) 

429 

430 if is_truncated: 

431 # remove trailing space of last line 

432 summary += line.rstrip() + space2 + "..." 

433 line = space2 

434 

435 for tail_item in tail[:-1]: 

436 word = tail_item + sep + " " 

437 summary, line = _extend_line(summary, line, word, display_width, space2) 

438 

439 # last value: no sep added + 1 space of width used for trailing ',' 

440 summary, line = _extend_line(summary, line, tail[-1], display_width - 2, space2) 

441 summary += line 

442 

443 # right now close is either '' or ', ' 

444 # Now we want to include the ']', but not the maybe space. 

445 close = "]" + close.rstrip(" ") 

446 summary += close 

447 

448 if len(summary) > (display_width) or line_break_each_value: 

449 summary += space1 

450 else: # one row 

451 summary += " " 

452 

453 # remove initial space 

454 summary = "[" + summary[len(space2) :] 

455 

456 return summary 

457 

458 

459def _justify( 

460 head: list[Sequence[str]], tail: list[Sequence[str]] 

461) -> tuple[list[tuple[str, ...]], list[tuple[str, ...]]]: 

462 """ 

463 Justify items in head and tail, so they are right-aligned when stacked. 

464 

465 Parameters 

466 ---------- 

467 head : list-like of list-likes of strings 

468 tail : list-like of list-likes of strings 

469 

470 Returns 

471 ------- 

472 tuple of list of tuples of strings 

473 Same as head and tail, but items are right aligned when stacked 

474 vertically. 

475 

476 Examples 

477 -------- 

478 >>> _justify([['a', 'b']], [['abc', 'abcd']]) 

479 ([(' a', ' b')], [('abc', 'abcd')]) 

480 """ 

481 combined = head + tail 

482 

483 # For each position for the sequences in ``combined``, 

484 # find the length of the largest string. 

485 max_length = [0] * len(combined[0]) 

486 for inner_seq in combined: 

487 length = [len(item) for item in inner_seq] 

488 max_length = [max(x, y) for x, y in zip(max_length, length)] 

489 

490 # justify each item in each list-like in head and tail using max_length 

491 head_tuples = [ 

492 tuple(x.rjust(max_len) for x, max_len in zip(seq, max_length)) for seq in head 

493 ] 

494 tail_tuples = [ 

495 tuple(x.rjust(max_len) for x, max_len in zip(seq, max_length)) for seq in tail 

496 ] 

497 return head_tuples, tail_tuples 

498 

499 

500class PrettyDict(Dict[_KT, _VT]): 

501 """Dict extension to support abbreviated __repr__""" 

502 

503 def __repr__(self) -> str: 

504 return pprint_thing(self)